Event Types

Complete event structures, attributes, and data formats for tracking agent behavior and system interactions.

Event Types Overview

The following event types are supported via the API:

Session Events

• session.start — Marks the beginning of a new session
• session.end — Marks the end of a session with summary metrics

LLM Events

• llm.call.start — Sent when an LLM API call begins
• llm.call.finish — Sent when an LLM API call completes successfully
• llm.call.error — Sent when an LLM API call fails

Tool Events

• tool.execution — Sent when a tool/function is invoked
• tool.result — Sent when a tool execution completes

Session Events

session.start

Sent when a new session begins.

Required Attributes:

• user.id — User identifier
• client.type — Client type (e.g., “web”, “mobile”, “gateway”)

Example:

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:25:00.000Z",
  "trace_id": "session1234567890123456789012345678901234",
  "span_id": "sess1234567890ab",
  "name": "session.start",
  "level": "INFO",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "user.id": "user-456",
    "client.type": "gateway"
  }
}

session.end

Sent when a session ends.

Required Attributes:

• session.duration_ms — Session duration in milliseconds
• session.events_count — Number of events in the session

Example:

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:45:00.000Z",
  "trace_id": "session1234567890123456789012345678901234",
  "span_id": "sess1234567890ab",
  "name": "session.end",
  "level": "INFO",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "session.duration_ms": 1200000,
    "session.events_count": 25
  }
}

LLM Events

llm.call.start

Sent when an LLM API call begins.

Required Attributes:

• llm.vendor — LLM provider (e.g., “anthropic”)
• llm.model — Model identifier
• llm.request.data — Complete request payload (PII data can be omitted)

Example:

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "trace_id": "abc123def456789012345678901234567890abcd",
  "span_id": "1234567890abcdef",
  "name": "llm.call.start",
  "level": "INFO",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "llm.vendor": "anthropic",
    "llm.model": "claude-3-sonnet-20240229",
    "llm.request.data": {
      "messages": [{"role": "user", "content": "Hello"}],
      "temperature": 0.7,
      "max_tokens": 150
    }
  }
}

llm.call.finish

Sent when an LLM API call completes successfully.

Required Attributes:

• llm.vendor — LLM provider
• llm.model — Model identifier
• llm.response.duration_ms — Response time in milliseconds

Optional Attributes:

• llm.usage.input_tokens — Input token count
• llm.usage.output_tokens — Output token count
• llm.usage.total_tokens — Total token count
• llm.response.content — Response content array

Example:

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:30:02.500Z",
  "trace_id": "abc123def456789012345678901234567890abcd",
  "span_id": "1234567890abcdef",
  "name": "llm.call.finish",
  "level": "INFO",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "llm.vendor": "anthropic",
    "llm.model": "claude-3-sonnet-20240229",
    "llm.response.duration_ms": 2500,
    "llm.usage.input_tokens": 25,
    "llm.usage.output_tokens": 8,
    "llm.usage.total_tokens": 33,
    "llm.response.content": [{"text": "Hello! How can I help you?"}]
  }
}

llm.call.error

Sent when an LLM API call fails.

Required Attributes:

• llm.vendor — LLM provider
• llm.model — Model identifier
• error.message — Error description

Optional Attributes:

• error.type — Error type/class name

Example:

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:30:01.000Z",
  "trace_id": "abc123def456789012345678901234567890abcd",
  "span_id": "1234567890abcdef",
  "name": "llm.call.error",
  "level": "ERROR",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "llm.vendor": "anthropic",
    "llm.model": "claude-3-sonnet-20240229",
    "error.message": "Rate limit exceeded",
    "error.type": "RateLimitError"
  }
}

Tool Events

tool.execution

Sent when a tool/function is invoked.

Required Attributes:

• tool.name — Tool/function name
• tool.params — Tool parameters

Optional Attributes:

• framework.name — Framework name (e.g., “langchain”, “llamaindex”)

Example:

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:31:00.000Z",
  "trace_id": "abc123def456789012345678901234567890abcd",
  "span_id": "tool1234567890ab",
  "name": "tool.execution",
  "level": "INFO",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "tool.name": "web_search",
    "tool.params": {"query": "AI developments 2024", "max_results": 5},
    "framework.name": "langchain"
  }
}

tool.result

Sent when a tool execution completes.

Required Attributes:

• tool.name — Tool/function name
• tool.status — Execution status (“success” or “error”)
• tool.execution_time_ms — Execution time in milliseconds

Optional Attributes:

• tool.result — Tool execution result
• error.message — Error message (if status is “error”)

Example:

{
  "schema_version": "1.0",
  "timestamp": "2024-01-15T10:31:03.200Z",
  "trace_id": "abc123def456789012345678901234567890abcd",
  "span_id": "tool1234567890ab",
  "name": "tool.result",
  "level": "INFO",
  "agent_id": "my-agent",
  "session_id": "session-xyz789",
  "attributes": {
    "tool.name": "web_search",
    "tool.status": "success",
    "tool.execution_time_ms": 3200,
    "tool.result": {"results": [{"title": "AI News", "url": "https://example.com"}]}
  }
}