> ## Documentation Index
> Fetch the complete documentation index at: https://docs.halios.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry reference

> What telemetry Halios accepts and how to configure OpenTelemetry export.

Halios accepts OpenTelemetry traces from standard OTel SDKs and common AI instrumentation libraries. If you already emit compatible telemetry, point your exporter at Halios. If not, your coding agent can add or adapt instrumentation.

***

## Compatible instrumentation

Halios works with standard OpenTelemetry-compatible traces and auto-instrumentors:

| Instrumentation             | What Halios can use                              |
| :-------------------------- | :----------------------------------------------- |
| **OpenTelemetry SDK**       | Traces, span hierarchy, custom attributes        |
| **OpenLLMetry / Traceloop** | Model calls, tool executions, document retrieval |
| **OpenInference**           | Model, tool, retrieval, and chain spans          |
| **LiteLLM**                 | Model calls, token usage, latency, tool activity |

***

## Configure the OTLP exporter

Point your standard OpenTelemetry exporter to Halios using standard environment variables:

```bash theme={null}
# OTLP HTTP Traces Endpoint
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.halios.ai/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-agent-otlp-token>"

# Service & Environment Metadata
export OTEL_SERVICE_NAME="support-agent"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production,service.version=v1.2.0"
export OTEL_PROPAGATORS="tracecontext,baggage"
```

***

## GenAI semantics Halios understands

Halios recognizes common GenAI operations such as:

* **Model calls** (input prompts, output completions, token usage)
* **Tool execution** (tool name, arguments, output results or errors)
* **Retrieval** (search queries, returned document chunks and IDs)
* **Agent / Sub-agent delegation** (multi-agent workflows, parent-child context)

Where available, Halios uses OpenTelemetry GenAI semantic convention attributes such as `gen_ai.operation.name`, model/provider metadata, tool names, messages, usage, and related execution context.

***

## Minimum recommended telemetry

For effective evaluations and debugging, aim to send:

* One trace per agent interaction or run
* Parent-child span relationships preserved across async calls
* Model and tool operation names
* Tool arguments and results where available
* Input and output messages if evaluations inspect them
* Service and environment metadata (`service.name`, `deployment.environment.name`, `service.version`)

> Halios can ingest partial traces, but richer traces produce better debugging and evaluation data.

***

## Redacting sensitive data

Trace payloads may contain prompts, user data, and tool arguments. Use your OpenTelemetry processor or exporter to redact or drop sensitive fields before export when required.

***

## Verify traces with the CLI

You can inspect and verify stored traces using the Halios CLI:

```bash theme={null}
halios trace show <trace-id> --include spans,checks
halios trace verify <trace-id>
```

Verification confirms that traces have valid W3C IDs, correct parent-child relationships, ended statuses, and captured operation metadata.

***

<CardGroup cols={2}>
  <Card title="CLI reference" icon="square-terminal" href="/reference/cli">
    Command reference for automation and CI pipelines.
  </Card>

  <Card title="Evaluation concepts" icon="boxes" href="/concepts/evaluation-concepts">
    Core mental model and key evaluation terms.
  </Card>
</CardGroup>