Event Structure

Base event structure, common attributes, and system information schema.

Event Structure

All events follow a common base structure with event-specific attributes:

Base Event Schema

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "trace_id": "32-character-hex-string",
  "span_id": "16-character-hex-string",
  "name": "event.name",
  "level": "INFO|DEBUG|WARNING|ERROR",
  "agent_id": "agent-id",
  "session_id": "session-id",
  "attributes": {}
}

Base Schema Fields

Required Fields

• schema_version: API schema version (currently “1.0”)
• timestamp: ISO 8601 timestamp with timezone information
• name: Event type identifier (e.g., “session.start”, “llm.call.finish”)
• level: Log level: INFO, DEBUG, WARNING, or ERROR
• session_id: Unique identifier for the agent session

Optional Fields

• trace_id: 32-character hex string for distributed tracing
• span_id: 16-character hex string for operation tracking
• agent_id: Agent identifier (auto-generated if not provided)

System Information Attributes

The following system information can be optionally added to all events:

Host Information

• host.name: Hostname
• host.arch: System architecture
• host.cpu_count: Number of CPUs

Runtime Information

• os.name: Operating system name
• os.version: OS version
• process.runtime.name: Runtime name (e.g., “python”)
• process.runtime.version: Runtime version

System Attributes Example

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "trace_id": "abc123def456789012345678901234567890abcd",
  "span_id": "1234567890abcdef",
  "name": "session.start",
  "level": "INFO",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "user.id": "user-456",
    "client.type": "gateway",
    "host.name": "app-server-01",
    "host.arch": "x86_64",
    "host.cpu_count": 8,
    "os.name": "Linux",
    "os.version": "Ubuntu 22.04.3 LTS",
    "process.runtime.name": "python",
    "process.runtime.version": "3.11.6"
  }
}

Data Types and Validation

Timestamps

• Format: ISO 8601 with timezone (RFC 3339)
• Example: 2024-01-15T10:30:00.000Z
• Timezone: UTC recommended for consistency

Trace & Span IDs

• Trace ID: 32-character lowercase hexadecimal string
• Span ID: 16-character lowercase hexadecimal string
• Compatibility: OpenTelemetry standard format

Event Levels

• INFO: Normal operation events
• DEBUG: Detailed diagnostic information
• WARNING: Potentially concerning events
• ERROR: Error conditions and failures

Identifiers

• Session ID: Unique string identifier, consistent across session events
• Agent ID: Optional string identifier for multi-agent scenarios
• User ID: Application-specific user identifier

Schema Versioning

Current Version: 1.0

All events must include schema_version: "1.0" to ensure proper processing and compatibility.

Backward Compatibility

The API maintains backward compatibility within major versions. Minor schema updates may add optional fields without breaking existing integrations.

Future Versions

Schema version updates will be announced with migration guides. The API supports multiple schema versions during transition periods.