> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry

> Connect AgentCat with OpenTelemetry-compatible platforms.

## 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](https://opentelemetry.io).

## Configuration

<CodeGroup>
  ```typescript TypeScript theme={null}
  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"
      }
    }
  })
  ```

  ```python Python theme={null}
  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"
      }
    }
  ))
  ```

  ```go Go theme={null}
  mcpcat.Track(s, "", &mcpcat.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",
          },
      },
  })
  ```
</CodeGroup>

## 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`    | `"mcpcat-python"`, `"mcpcat-typescript"`, or `"mcpcat-go"` |
| `mcpcat_version`        | `telemetry.sdk.version` | AgentCat SDK version                                       |

### 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.