OBSERVABILITY
Export agent traces
Connect OpenTelemetry spans to the requests your agents make through Netra.
Overview
Enable request recording for your organization before exporting traces. Export requests return 403 while recording is disabled. Review your instrumentation’s content-capture settings before sending prompts, outputs or tool data.
An agent run can include model calls, retrieval, tools, and other steps. Export those steps as OpenTelemetry spans so Observe can show their relationships. An inference request alone supplies usage; it does not describe every action in an external framework.
Configure an OTLP/HTTP exporter
The endpoint accepts POST https://api.netraruntime.com/v1/otel/v1/traces with a Netra bearer key. Supported encodings are application/x-protobuf and OTLP JSON (application/json). Use an OTLP HTTP exporter, not a gRPC exporter.
For an application already instrumented with a compatible OpenTelemetry SDK/exporter:
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.netraruntime.com/v1/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20${NETRA_API_KEY}"
export OTEL_RESOURCE_ATTRIBUTES="service.name=support-app,netra.project=support,gen_ai.agent.name=support-agent,deployment.environment.name=production"These variables configure an installed exporter; they do not instrument your application by themselves. Check your framework's exporter setup, startup order, and flush/shutdown handling. The signal-specific traces endpoint is the complete URL; a generic OTLP base endpoint instead appends a signal path. Header escaping follows exporter configuration conventions. See the OpenTelemetry exporter specification for SDK configuration behavior.
Use the same Netra key for inference and trace export if you want one MCP connection to inspect both. Propagate trace context to the inference HTTP call using your tracing library; send its valid W3C traceparent header. Independent random IDs on each call do not establish parent-child relationships.
Attributes Netra recognizes
| Attribute | Purpose |
|---|---|
Resource gen_ai.agent.name | Stable agent label. Pair it with X-Netra-Agent on inference requests. |
Resource netra.project | Project grouping; uses service.name when omitted. |
Resource deployment.environment or deployment.environment.name | Environment label. |
Span openinference.span.kind | OpenInference operation type. |
Span gen_ai.operation.name | GenAI operation hint. |
Span input.value / output.value | Input/output content when your instrumentation explicitly captures it. |
Span gen_ai.prompt / gen_ai.completion | Alternative input/output content fields. |
Only export the content needed for your investigation. Scrub secrets and sensitive payloads at the application/exporter boundary. The organization recording toggle controls whether Netra accepts trace exports; it does not stop your application from emitting data. Disable or filter content capture in your instrumentation when you do not want to send it.
Export limits and missing spans
- Default export body limit: 4 MiB; at most 512 accepted spans per request.
- Export budget: 300 requests per minute per organization;
429includes retry guidance. - Each input/output field is capped at 64 KiB, with a truncation marker. Leftover attribute values and maps also have size caps.
- Invalid IDs, missing start times, and spans beyond the batch cap can produce an OTLP partial-success response. Check
rejected_spanseven when HTTP status is 200. - Organization sampling can intentionally omit traces. Sampling omissions are not reported as rejected spans.
- Stored spans are scheduled for deletion after 30 days; retained usage metadata can outlive detailed traces.
Trace ingest is observational and does not alter inference billing. Exported status, names, and content are reported by the application, so they are evidence to investigate rather than independent proof of correctness.