OpenTelemetry
Send OTLP/HTTP traces from existing OpenTelemetry instrumentation. GenAI semantic conventions are mapped automatically.
On this page
Applications that already use OpenTelemetry can send traces to Worksi without any Worksi package. Spans that follow the OpenTelemetry GenAI semantic conventions (or OpenLLMetry-style instrumentation) are mapped to Worksi’s span model automatically and show up in traces, dashboards, detection, the AI Graph and auto-discovery like any other telemetry.
Endpoint#
| URL | POST https:// |
| Encodings | application/ (the default) and application/. Content-Encoding: is supported. |
| Auth | Authorization: with the traces:write scope. The organization, workspace and environment come from the key only. |
| Limits | 5 MiB per request and 5,000 spans per request |
| Capture | The environment’s capture mode applies. X-AIW-Capture can make it stricter per request. |
| Response | An OTLP export response. Invalid spans are counted in partial_success.. |
Send traces#
# the gateway's OTLP endpoint and your Worksi API keyWORKSI_OTLP="https://gateway.worksi.ai/v1/otlp/v1/traces"WORKSI_AUTH="Authorization=Bearer%20${AIW_API_KEY}" export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="$WORKSI_OTLP"export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobufexport OTEL_EXPORTER_OTLP_TRACES_HEADERS="$WORKSI_AUTH"# becomes the agent when no agent attribute is setexport OTEL_SERVICE_NAME="billing-agent"exporters: otlphttp/worksi: endpoint: https://gateway.worksi.ai/v1/otlp headers: Authorization: "Bearer ${env:AIW_API_KEY}" service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlphttp/worksi]Attribute mapping#
Span attributes override resource attributes, and explicit aiw.* attributes win over GenAI conventions.
| Worksi field | Taken from (first present wins) |
|---|---|
| kind | aiw.kind; else gen_ai.operation.name (chat, text_completion, embeddings… → model call; execute_tool → tool call; invoke_agent → agent step); else gen_ai.tool.name → tool call |
| provider | aiw.provider, gen_ai.provider.name, gen_ai.system |
| model | aiw.model, gen_ai.request.model, gen_ai.response.model |
| agent | aiw.agent, gen_ai.agent.name, service.name |
| workflow, team | aiw.workflow, aiw.team |
| tool | aiw.tool, gen_ai.tool.name |
| input tokens | aiw.input_tokens, gen_ai., gen_ai. |
| output tokens | aiw.output_tokens, gen_ai., gen_ai. |
| cost | aiw.cost_usd; otherwise priced from your model registry when tokens are present |
| status | aiw.status; else the OpenTelemetry status (ERROR → error) |
| run | aiw.run_id, defaulting to the trace id |
| input, output | aiw.input and aiw.output, gen_ai.input.messages and gen_ai.output.messages, and the GenAI prompt and completion events. Content goes through your capture mode and redaction and is never kept as a raw attribute. |
Get the most out of OTLP data#
| You want | Send |
|---|---|
| Per-agent and per-workflow reporting, policies in reports, auto-discovery | aiw.agent (or gen_ai.agent.name or service.name) and aiw.workflow on every span |
| Run views and stuck-workflow detection | aiw.run_id on every span of a run, a run.started span with aiw.kind=run_event at the start and a root span with aiw.kind=workflow_run at the end |
| Loop and repeated-tool detection | aiw.prompt_hash on model spans and aiw.args_hash on tool spans |
| Cost | Token usage attributes, and the model registered with prices in Workforce → Models |
Limitations#
- OTLP is observation only. Gateway controls (model allowlists, budgets, rate limits, pause and stop) apply to traffic that goes through the gateway, so combine OTLP with gateway mode when you need enforcement.
- Only traces are ingested, not logs or metrics.
- No attribute can move a span into another organization, workspace or environment.
Questions? Email info@xeoo.io.