> ## Documentation Index
> Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenTelemetry
> Send OpenTelemetry traces to AgentMark from any instrumented app. The OTLP endpoint, authentication, and the semantic conventions AgentMark understands.
AgentMark ingests traces over [OpenTelemetry](https://opentelemetry.io/). Anything that exports OTLP (the [AgentMark SDK](/observe/tracing-setup), a framework instrumentor, or a raw OpenTelemetry setup) can send spans to AgentMark by pointing its exporter at one endpoint. There is no AgentMark-specific exporter to install.
This page covers the endpoint and authentication. If you're using a framework, start with the ecosystem that instruments it:
LangChain, LlamaIndex, OpenAI Agents SDK, CrewAI, DSPy, Haystack, and more
Traceloop and OpenLIT instrumentors: AutoGen, Semantic Kernel, Agno, and more
## Endpoint
AgentMark accepts OTLP over HTTP at:
```text theme={null}
https://api.agentmark.co/v1/traces
```
Every request needs two headers:
| Header | Value | Required |
| -------------------- | ------------------------------------------------------------------- | --------------------------- |
| `Authorization` | Your AgentMark API key, sent as the raw value (no `Bearer ` prefix) | Yes (missing returns `401`) |
| `X-Agentmark-App-Id` | The app the traces belong to | Yes (missing returns `400`) |
Find both in your project settings. The API key authenticates the request; the app id routes the spans to the right app.
## Point an exporter at AgentMark
Most OpenTelemetry SDKs and instrumentors read the standard OTLP environment variables, so they need no code change:
```bash theme={null}
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.agentmark.co/v1/traces"
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=,X-Agentmark-App-Id="
```
To configure the exporter in code instead:
```typescript TypeScript theme={null}
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
const exporter = new OTLPTraceExporter({
url: "https://api.agentmark.co/v1/traces",
headers: {
Authorization: process.env.AGENTMARK_API_KEY!, // raw key, no "Bearer" prefix
"X-Agentmark-App-Id": process.env.AGENTMARK_APP_ID!,
},
});
```
```python Python theme={null}
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
exporter = OTLPSpanExporter(
endpoint="https://api.agentmark.co/v1/traces",
headers={
"Authorization": "", # raw key, no "Bearer" prefix
"X-Agentmark-App-Id": "",
},
)
```
For local development, `agentmark dev` accepts the same OTLP format at `http://localhost:9418/v1/traces`, so you can point any instrumentor at your dev server before sending to the cloud.
## Supported semantic conventions
AgentMark reads several attribute conventions and normalizes them into one trace model (model, token usage, input and output messages, tool calls, and span kind) so it computes cost and latency the same way regardless of which library produced the span.
| Convention | Recognized by | Notes |
| -------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| OpenTelemetry GenAI (`gen_ai.*`) | The official `gen_ai` semantic conventions | The default. Spec-compliant emitters (including Pydantic AI via Logfire) work with no extra mapping |
| OpenInference | `openinference.span.kind` and `llm.*` attributes | The Arize instrumentor ecosystem. See [OpenInference](/integrations/tracing/openinference) |
| OpenLLMetry / Traceloop | `traceloop.*` and indexed `gen_ai.prompt.*` / `gen_ai.completion.*` attributes | Traceloop and OpenLIT instrumentors. See [OpenLLMetry](/integrations/tracing/openllmetry) |
Spans that match none of these are still stored with their attributes intact; only the normalized fields (model, tokens, I/O) depend on a recognized convention.
## What AgentMark does with a span
Once a span arrives, AgentMark:
* Classifies it as a model call (`GENERATION`) or another operation (`SPAN`), and resolves a [span kind](/observe/span-reference#spankind-values): `llm`, `tool`, `agent`, `retrieval`, `embedding`, or `guardrail`.
* Extracts the model, token counts, input and output, tool calls, and settings.
* Computes cost from the model and token counts using its [pricing model](/observe/cost-and-token-tracking).
You supply no span kind or attribute mapping. AgentMark infers it from the convention the instrumentor used.
## Next steps
Trace LangChain, LlamaIndex, CrewAI, and the rest of the OpenInference ecosystem
Trace AutoGen, Semantic Kernel, Agno, and other Traceloop/OpenLIT-instrumented frameworks
Instrument your own code directly with the AgentMark SDK
Explore the traces once they arrive
Have questions?
Reach out any time: