Skip to content
Status

Observability / Data export

Data export

Export product telemetry, risk findings, and MCP tool call logs from each project to an OTLP/HTTP destination.

Data exports send normalized OpenTelemetry (OTEL) from AI products, policy findings, and MCP tool calls to project-scoped OTLP/HTTP destinations. The Exports page, under Organization settings > Data > Exports in the dashboard, shows every configured project route in one organization-level view. To confirm telemetry is reaching the platform before routing it anywhere, use the event feed.

A direct OTEL connection requires a Hooks API key and a project slug. Plugins handle the connection automatically. Viewing data exports requires the org:read scope. Creating, changing, pausing, or deleting an export requires the org:admin scope, which is included in the default Admin role.

AI products with native OTEL exporters send telemetry to the platform. The platform normalizes each signal, adds organization and project context, and checks for an enabled data export route for that project. The route connects one data source to one OTLP destination.

Data export flow: AI products with native OTEL exporters send OTLP/HTTP Protobuf to the AI Control Plane. Inside the platform, step 1 Speakeasy OTLP ingest receives logs, metrics, and traces; step 2 normalizes and enriches each signal, joined by AI Control Plane organization and project context; step 3 checks for an enabled project data export route, which connects one data source to one OTLP destination. The route fans out to Langfuse, Datadog, Grafana Cloud, or other OTLP backends.

The destination is independent of the producer. Changing a route does not require reconfiguring the AI product that sends telemetry to the platform.

Risk findings and tool call logs originate inside the platform instead of at an OTLP producer. Their routes need no producer configuration.

Three data sources can be exported. Product telemetry exports normalized OTLP logs, metrics, and traces from supported products. Risk findings exports one OTLP log record per policy finding, carrying a stable finding ID, the policy and policy version, rule, source, confidence, and non-secret position anchors, never the matched content; exclusion rules are re-checked before every delivery so a finding excluded after detection is not exported. Tool call logs exports one OTLP log record for every tool call the platform serves for hosted or proxied MCP servers, successes and failures alike, each carrying its log ID so a destination can deduplicate. See Export MCP tool call logs.

SourceSignalsExport behavior
Compatible OTLP/HTTP producersLogs, metrics, and tracesNormalized and sent as OTLP/HTTP Protobuf to /v1/logs, /v1/metrics, and /v1/traces
Products without an OTEL exporterPlugin hook eventsAvailable to Observability and Security and Policy, but not included in OTLP data exports
Risk findingsLogsOne privacy-safe record per finding, sent to /v1/logs; exclusions re-checked before delivery
Tool call logsLogsOne record per tool call on hosted or proxied MCP servers, sent to /v1/logs with the log ID for deduplication

OpenCode and OpenClaw do not expose native OTEL exporters. Their observability plugins still supply sessions, tool calls, tokens, and cost to the platform, but those plugin-only events are not part of the Product telemetry export.

Organizations that use the MCP gateway usually need a record of each tool call the gateway serves. Product telemetry does not carry those records. It relays only what producers send to the OTLP ingest endpoints, such as Claude Code telemetry enriched with platform context. A tool call the platform executes for a hosted or proxied MCP server never passes through those endpoints, so a failed call can appear in Tool Logs and still be missing from a Product telemetry destination. Route the Tool call logs source to deliver those calls.

Data needed at the destinationData source
Tool calls served by hosted or proxied MCP servers, including failed callsTool call logs
Agent sessions, model usage, and tool use reported by agent OTEL exportersProduct telemetry
Policy findings from risk policiesRisk findings

Each source is a separate route, so a project can send tool call logs and product telemetry to the same destination or to different ones. Existing Product telemetry routes do not start carrying tool call logs. Add a Tool call logs route to receive them.

The Tool call logs source covers the tool calls the platform executes itself:

  • Every tool call served for a hosted or proxied MCP server, whatever the outcome.
  • Tool arguments and results, when Record Tool I/O is on in Logging Settings. A destination that excludes sensitive data receives them as [REDACTED]. See Control sensitive data.

It leaves out records that reach the platform another way:

  • Tool use that agents report through hooks, such as calls to shadow MCP servers, skills, and local tools. Tool Logs shows these calls, but they leave the platform through Product telemetry where the producer supports it. Routing both sources never delivers the same call twice.
  • MCP resource reads and tool discovery requests on the same servers.

Each tool call becomes one OTLP log record sent to /v1/logs. The record keeps the attributes Tool Logs filters on, so a query written for Tool Logs translates directly to the destination.

FieldValue
Event namegram.tool_call
Instrumentation scopegithub.com/speakeasy-api/gram/server/internal/telemetry
SeverityINFO, WARN, or ERROR, with the matching OTLP severity number
BodyThe log message shown in Tool Logs
Trace and span IDsThe IDs of the call, when it has valid ones
Resource attributesThe service and deployment that served the call, such as service.name and gram.deployment.id
gram.telemetry.log.idThe ID of the Tool Logs record, for deduplication
gram.event.sourceAlways tool_call
gram.org.idOrganization ID
Tool attributesTool and response context, such as gram.tool.name, gram.tool.urn, and http.response.status_code

Numeric attributes keep their type. An HTTP status code or a nanosecond timestamp arrives as an integer, not a floating-point value.

Delivery is at-least-once, so a destination can occasionally receive the same record twice. Deduplicate on gram.telemetry.log.id when exact counts matter.

If a supported Speakeasy plugin is installed, skip this section. The plugin connects the product to the platform automatically. Configure an OTEL producer directly only when the product is not using a plugin.

Create a Hooks key from the API Keys page, then configure the product or its OpenTelemetry SDK to use OTLP over HTTP with Protobuf encoding.

Most OpenTelemetry SDKs accept the standard exporter environment variables:

Terminal window
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ai.speakeasy.com/otel"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Speakeasy-AI-Key=<HOOKS_API_KEY>,Speakeasy-AI-Project=<PROJECT_SLUG>"

The generic endpoint appends the signal path automatically. For a trace-specific exporter, set the complete endpoint instead:

Terminal window
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://ai.speakeasy.com/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Speakeasy-AI-Key=<HOOKS_API_KEY>,Speakeasy-AI-Project=<PROJECT_SLUG>"

The trace endpoint accepts identity or gzip content encoding. Both the compressed request and its decompressed form must be no larger than 20 MiB. The endpoint acknowledges an export only after every span in the request has been accepted for processing, so standard OTLP retry behavior remains effective when ingestion fails.

The trace pipeline keeps the original OTLP resource, scope, span, event, link, status, and producer attributes. It adds attributes under the speakeasy.* namespace when the corresponding context is available.

AttributeDescription
speakeasy.organization.idAI Control Plane organization ID derived from the authenticated request
speakeasy.organization.slugOrganization slug, when available
speakeasy.project.idProject ID derived from the authenticated request
speakeasy.project.slugProject slug, when available
speakeasy.api_key.idID of the key that supplied the telemetry, when available
speakeasy.api_key.nameName of the key that supplied the telemetry, when available
speakeasy.tokens.countToken count calculated from supported prompt and completion attributes
speakeasy.tokens.codecTokenizer used for speakeasy.tokens.count
speakeasy.original_instrumentation_scope.nameProducer scope name before normalization, when one was present

Instrumentation scopes are normalized to com.speakeasy.ai.tracing. Unknown OTLP fields are retained for forward compatibility, while private transport metadata is removed before export.

Producer identity attributes such as user.email and user.id remain on the signal. Elsewhere in the AI Control Plane, these values resolve against organization membership and Directory Sync, which provides department, division, job title, employee type, cost center, IdP groups, and role context for identity-aware Observability views when that data is available from the connected directory.

Open Organization settings > Data > Exports in the dashboard. The page combines configured exports from every visible project into one topology.

To add an export:

  • Click New export.
  • Choose a project. The picker includes only projects that do not already have a route for the selected data source.
  • Choose Product telemetry, Risk findings, or Tool call logs under Data to export.
  • Select an existing destination for that project, or select Create a new destination.
  • For a new destination, enter a name, the base OTLP endpoint, and any required headers.
  • Choose whether to include sensitive data.
  • Leave Start exporting on to enable delivery immediately, or turn it off to save the route paused.
  • Click Create export.

The endpoint must use HTTP or HTTPS. Enter the base without /v1/traces, /v1/logs, or /v1/metrics. The platform appends the path for each signal.

Destination headers are encrypted at rest and write-only. The API returns each header name and whether a value exists, but never returns the stored value.

New destinations exclude sensitive data by default. The exclude policy replaces classified content and identity values with [REDACTED] while preserving the OTLP attribute keys. Classified values include prompts, model input and output, tool arguments, tool results, and user identifiers.

Turning on Include sensitive data preserves the normalized OTLP payload. Apply access controls and retention policies at the destination before enabling this setting.

The policy belongs to the destination. Selecting an existing destination uses its stored policy.

The Exports page draws every route as one map, with Data on the left and Sent to on the right. Each source card includes controls to pause or enable delivery, change its destination, or delete the route. Deleting an export stops delivery and removes the route. The destination remains available for another export in the same project.

To receive risk findings over plain HTTP instead of OTLP, subscribe to risk_finding events with Webhooks.

The Event Feed page, under Organization settings > Data > Event Feed, lists every OpenTelemetry log record and span the platform has ingested across the organization, whichever project or API key delivered it. Use it to confirm telemetry is arriving while connecting a plugin, a direct OTLP producer, or an AI integration, before any Observability page has processed the data. The feed is in preview. Viewing it requires the org:read scope.

Filter by time range, kind (logs or spans), source, and name, or search event bodies. Select an event to see its trace and span IDs, attributes, and the full record. The feed is read-only. What appears in it depends on the switches in Logging Settings and on which producers send telemetry.

Data exports use the open OTLP/HTTP format. Any destination that accepts OTLP/HTTP Protobuf at the standard signal paths can receive exported telemetry. The configurations below support OTLP/HTTP traces. Confirm log and metric support with the destination when all three signals are required. Risk findings and Tool call logs send only logs, so their destinations must accept OTLP logs at /v1/logs.

Use the regional base endpoint ending in /api/public/otel. Add a Basic Authorization header. Langfuse v4 also recommends the x-langfuse-ingestion-version: 4 header. See the Langfuse OpenTelemetry integration.

Use the site-specific OTLP intake base endpoint and add a dd-api-key header. The optional compute_stats: true header enables trace metrics. Datadog recommends the Datadog Agent or OpenTelemetry Collector for production workloads. See the Datadog OTLP intake documentation.

Copy the base endpoint and Basic Authorization header from the OpenTelemetry connection tile for the Grafana Cloud stack. See the Grafana Cloud OTLP documentation.

Use the OTLP/HTTP receiver base URL, commonly port 4318, plus any headers enforced by the collector. The collector can process or route signals before sending them to another backend. See the OpenTelemetry Collector receiver documentation.

For a destination that supplies a signal-specific URL ending in /v1/traces, remove that suffix before saving the endpoint.

The platform sends normalized logs, metrics, and traces as application/x-protobuf. It appends the standard signal path to the configured base endpoint and applies the destination headers to every request.

Delivery is asynchronous after ingestion. The relay retries transient network failures, 408 and 429 responses, and 5xx responses. Other 4xx responses are treated as permanent configuration or authentication failures. Each outbound attempt has a ten-second timeout.

Delivery failures do not affect the source agent or the copy processed by the platform for Observability and Security and Policy. Route and destination changes can take up to 60 seconds to reach every relay worker.