OpenTelemetry - AgentCat

Overview

Integrate AgentCat with any OpenTelemetry Protocol (OTLP) compatible platform like Jaeger, Grafana Tempo, New Relic, or AWS X-Ray. Learn more about OpenTelemetry at opentelemetry.io.

Configuration

agentcat.track(server, null, {
  exporters: {
    otlp: {
      type: "otlp",
      endpoint: "http://localhost:4318/v1/traces",
      protocol: "http/protobuf",
      headers: {
        "api-key": "your-api-key"
      },
      compression: "gzip"
    }
  }
})

agentcat.track(server, None, agentcat.AgentCatOptions(
  exporters={
    "otlp": {
      "type": "otlp",
      "endpoint": "http://localhost:4318/v1/traces",
      "protocol": "http/protobuf",
      "headers": {
        "api-key": "your-api-key"
      },
      "compression": "gzip"
    }
  }
))

agentcat.Track(s, "", &agentcat.Options{
    Exporters: map[string]any{
        "otlp": map[string]any{
            "type":     "otlp",
            "endpoint": "http://localhost:4318/v1/traces",
            "protocol": "http/protobuf",
            "headers": map[string]any{
                "api-key": "your-api-key",
            },
            "compression": "gzip",
        },
    },
})

Configuration Fields

Field	Type	Required	Description
`endpoint`	string	Yes	OTLP endpoint URL
`protocol`	string	No	Protocol format: `"http/protobuf"` or `"grpc"` (default: `"http/protobuf"`)
`headers`	object	No	Additional headers to send with requests
`compression`	string	No	Compression method: `"gzip"` or `"none"` (default: `"none"`)

Field Mapping

AgentCat events are mapped to OTLP spans with the following structure:

Trace and Span IDs

AgentCat Field	OTLP Field	Format
`session_id`	`traceId`	32-character hex (SHA256 hash, one per session)
`id`	`spanId`	16-character hex (SHA256 hash, unique per event)

Resource Attributes

AgentCat Internal Field	OTLP Attribute	Description
`server_name`	`service.name`	MCP server name
`server_version`	`service.version`	MCP server version
`sdk_language`	`telemetry.sdk.name`	`"agentcat-python"` (Python SDK only; the TypeScript SDK reports the SDK via the OTLP scope `name: "agentcat"` instead)
`agentcat_version`	`telemetry.sdk.version`	AgentCat SDK version (Python SDK only)

Span Attributes

AgentCat Field	OTLP Attribute	Description
`event_type`	`mcp.event_type`	Event type (e.g., “tools/call”)
`session_id`	`mcp.session_id`	Session identifier
`project_id`	`mcp.project_id`	AgentCat project ID (if provided)
`resource_name`	`mcp.resource_name`	Tool/prompt/resource name
`user_intent`	`mcp.user_intent`	User’s intent (if captured)
`identify_actor_given_id`	`mcp.actor_id`	User identifier (if identified)
`identify_actor_name`	`mcp.actor_name`	User name (if identified)
`client_name`	`mcp.client_name`	MCP client name
`client_version`	`mcp.client_version`	MCP client version

Attributes with empty or falsy string values are automatically filtered out and will not appear in the exported span.

Span Properties

Property	Value	Description
`name`	Event type or `"mcp.event"`	Span display name
`kind`	`2` (`SPAN_KIND_SERVER`)	Indicates server-side span
`startTimeUnixNano`	Event timestamp	In nanoseconds
`endTimeUnixNano`	Start + duration	In nanoseconds (if duration available)
`status.code`	`1` (OK) or `2` (ERROR)	Based on `is_error` flag

Timestamp values are serialized as strings, not integers.

​Overview

​Configuration

​Configuration Fields

​Field Mapping

​Trace and Span IDs

​Resource Attributes

​Span Attributes

​Span Properties