Skip to main content
The Context Company consumes OpenTelemetry traces directly through OTLP over HTTP. The supported TCC integrations create the required agent run context, then export standards-compliant OTLP payloads to the TCC ingestion endpoint without a proprietary gateway.
TCC is not a general-purpose OpenTelemetry backend. The OTLP endpoint accepts trace payloads produced by supported TCC AI framework integrations. It does not infer agent runs from arbitrary application spans.

​
OTLP compatibility

OTLP over gRPC, metrics, and logs are not currently supported.

​
How TCC consumes OTLP

  1. A supported framework instrumentor creates OpenTelemetry spans for the agent run, model calls, and tool calls.
  2. The TCC integration adds a stable tcc.runId and preserves the framework attributes needed to interpret the trace.
  3. An OpenTelemetry exporter sends the trace directly to https://api.thecontext.company/v1/traces as OTLP/HTTP JSON or protobuf.
  4. TCC converts the recognized spans into runs, steps, and tool calls for analysis in the dashboard.
The endpoint receives standard OTLP payloads. TCC-specific attributes describe how those spans map to the TCC agent data model; they do not replace the OTLP transport or payload format.

​
Supported OTLP integrations

Vercel AI SDK

The Node.js and Next.js integration registers OpenTelemetry instrumentation and exports AI SDK agent, model, and tool spans through OTLP/HTTP.

LangChain and LangGraph

The Python integration instruments LangChain and LangGraph, attaches run context, and exports the resulting traces through OTLP/HTTP.

Agno

The Python integration uses OpenInference instrumentation and exports Agno agent, model, and tool spans through OTLP/HTTP.
Use the linked integration guide for setup. Each integration configures the exporter, authentication, run identifiers, and framework-specific span processing automatically.
Pointing an unmodified OpenTelemetry exporter at the TCC endpoint is not sufficient. The payload must include a recognized run span and the TCC run context added by a supported integration.

​
Authentication

Create an ingestion API key in Settings and provide it to the integration through TCC_API_KEY:
.env
The integration sends the key in the OTLP request:
Ingestion keys are separate from the read-only keys used by the TCC API and MCP integrations. Keep ingestion keys on the server and do not expose them in browser code.

​
Required run context

TCC groups model and tool spans into an agent run using tcc.runId. Supported integrations generate this value automatically. You can provide your own UUID when you need to correlate a run with feedback, deep links, or application data. Additional reserved attributes can associate a run with a session, agent, user, or organization:
The exact API for attaching metadata depends on the framework. Follow the linked framework guide and see TCC metadata keys for the complete reference.

​
Verify ingestion

  1. Register the TCC integration before initializing the AI framework.
  2. Execute one complete agent request.
  3. Flush the integration before a short-lived process exits.
  4. Open the TCC dashboard and confirm that the run contains its model steps and tool calls.
During initial setup, test with one request and record its unique tcc.runId. This makes it easier to separate export problems from sampling, batching, or unrelated application traffic.

​
Troubleshooting

​
The exporter receives 401 Unauthorized

Confirm that the request contains Authorization: Bearer <TCC_API_KEY> and that the value is an ingestion key. Read-only API keys cannot ingest traces.

​
The exporter reports an ingestion error

Check all of the following:
  • The request is sent to https://api.thecontext.company/v1/traces.
  • The integration sends an OTLP trace export using JSON or protobuf over HTTP.
  • You are using a supported TCC integration rather than an unmodified generic exporter.
  • The integration is registered before the AI framework initializes.
  • Span names, instrumentation scope names, parent relationships, and framework attributes have not been rewritten.

​
No run appears in the dashboard

Confirm that sampling retains the spans, a batch processor is flushed before shutdown, and the root run span includes a valid tcc.runId. Enabling debug logging in the relevant framework integration can confirm whether the exporter delivered the trace.

​
I need to ingest another framework

The OTLP endpoint does not currently infer a complete agent run from arbitrary spans. Use custom instrumentation to create explicit runs, steps, and tool calls, or contact founders@thecontextcompany.com with a representative trace payload.