raven-logger 1.0.0

Application logging SDK for raven-log contract compliance — structured, validated JSON logs

raven-sdk

Application logging SDK for raven-log contract compliance — emit validated, structured JSON records from any Python service.

Install

pip install raven-sdk

Quick start

from raven_sdk import raven_log, new_trace_id, new_span_id

trace = new_trace_id()

raven_log(
    level="INFO",
    criticality="P3",
    message="User signed in",
    service="auth-service",
    env="prod",
    principal="user:42",
    project="my-app",
    trace_id=trace,
)

Output (one JSON line to stdout):

{
  "schema_version": "1",
  "timestamp": "2026-06-22T12:00:00.000000+00:00",
  "level": "INFO",
  "criticality": "P3",
  "service": "auth-service",
  "env": "prod",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "span_id": "a1b2c3d4",
  "principal": "user:42",
  "error_code": "",
  "message": "User signed in",
  "context": {},
  "sample_payload": "",
  "project": "my-app"
}

API

raven_log(...) -> dict

Parameter	Type	Required	Description
level	"ERROR" | "WARN" | "INFO" | "DEBUG"	✓	Log level
criticality	"P1" | "P2" | "P3" | "P4"	✓	Business criticality
message	str	✓	Human-readable description
service	str	✓	Emitting service name
env	"prod" | "staging" | "dev"	✓	Deployment environment
principal	str	✓	Acting identity (e.g. "user:42")
project	str	✓	Project/team identifier
error_code	str	Required for ERROR/WARN	Machine-readable error code
trace_id	str	—	Distributed trace ID (auto-generated if omitted)
span_id	str	—	Span ID (auto-generated if omitted)
context	dict	—	Arbitrary structured context
sample_payload	str	—	Redacted payload snippet

Returns the emitted record as a dict.

new_trace_id() -> str

Generates a UUID v4 trace ID for use at service boundaries.

new_span_id() -> str

Generates an 8-character span ID for operations within a trace.

Custom emitter (Kafka, etc.)

Pass _emit to replace the default stdout writer:

def kafka_emit(record: dict) -> None:
    producer.send("logs", json.dumps(record).encode())

raven_log(..., _emit=kafka_emit)

License

MIT © Giggso