Skip to main content

​
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"
    }
  }
})

​
Configuration Fields

FieldTypeRequiredDescription
endpointstringYesOTLP endpoint URL
protocolstringNoProtocol format: "http/protobuf" or "grpc" (default: "http/protobuf")
headersobjectNoAdditional headers to send with requests
compressionstringNoCompression method: "gzip" or "none" (default: "none")

​
Field Mapping

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

​
Trace and Span IDs

AgentCat FieldOTLP FieldFormat
session_idtraceId32-character hex (SHA256 hash, one per session)
idspanId16-character hex (SHA256 hash, unique per event)

​
Resource Attributes

AgentCat Internal FieldOTLP AttributeDescription
server_nameservice.nameMCP server name
server_versionservice.versionMCP server version
sdk_languagetelemetry.sdk.name"mcpcat-python", "mcpcat-typescript", or "mcpcat-go"
mcpcat_versiontelemetry.sdk.versionAgentCat SDK version

​
Span Attributes

AgentCat FieldOTLP AttributeDescription
event_typemcp.event_typeEvent type (e.g., “tools/call”)
session_idmcp.session_idSession identifier
project_idmcp.project_idAgentCat project ID (if provided)
resource_namemcp.resource_nameTool/prompt/resource name
user_intentmcp.user_intentUser’s intent (if captured)
identify_actor_given_idmcp.actor_idUser identifier (if identified)
identify_actor_namemcp.actor_nameUser name (if identified)
client_namemcp.client_nameMCP client name
client_versionmcp.client_versionMCP client version
Attributes with empty or falsy string values are automatically filtered out and will not appear in the exported span.

​
Span Properties

PropertyValueDescription
nameEvent type or "mcp.event"Span display name
kind2 (SPAN_KIND_SERVER)Indicates server-side span
startTimeUnixNanoEvent timestampIn nanoseconds
endTimeUnixNanoStart + durationIn nanoseconds (if duration available)
status.code1 (OK) or 2 (ERROR)Based on is_error flag
Timestamp values are serialized as strings, not integers.