The Event Envelope: Making Behavior Explicit
Every observable fact in SpanForge is captured inside a single structure: the event envelope.
The envelope separates identity from meaning. Its metadata defines what the event is, when it occurred, and where it originated. Its payload describes what actually happened.
Consider the moment the model generates a response:
{
"version": 1,
"event_type": "llm.completion.succeeded",
"event_id": "01HZY3X8K9FZ7M2Q8A1B4C5D6E",
"timestamp_ns": 1710000000000000000,
"environment": "prod",
"service": "contract-analyzer",
"payload": {
"model": "gpt-4",
"prompt_tokens": 820,
"completion_tokens": 210,
"latency_ms": 1340,
"response": "Summary: ..."
}
}
This structure is deliberately strict.
Each event is self-describing through its type. Every payload is validated against a known schema. If a required field is missing, the event is rejected. The result is data that can be trusted in production.
The envelope is also versioned. New fields can be added without breaking existing consumers, while incompatible changes are introduced explicitly. This prevents silent schema drift—the most common cause of observability failure at scale.
The envelope is not an implementation detail. It is the system's source of truth.