# Enable OpenTelemetry — arccrew

Set up OpenTelemetry tracing to send pipeline spans to Grafana, Datadog, Jaeger, or any OTLP-compatible backend.

**User request:** $ARGUMENTS

---

## When to use this instead of LangSmith

- Client environment cannot send data to external SaaS (compliance, PII, air-gapped)
- You already have Grafana, Datadog, or Jaeger running
- You want traces in the same system as your infra metrics

Use **LangSmith** (`/enable-langsmith`) when you want a managed UI with LLM-specific features (token counts, cost, prompt diffs).

## Steps

1. Install the OTel exporter:
   ```bash
   pip install arccrew[otel]
   ```

2. Add to `.env`:
   ```bash
   OTEL_ENABLED=true
   OTEL_ENDPOINT=http://localhost:4317   # your OTLP/gRPC endpoint
   OTEL_SERVICE_NAME=my-pipeline
   ```

3. Restart the server — tracing activates automatically:
   ```bash
   arccrew serve
   ```

## What gets traced

Every agent execution produces two span types:
- `agent.run_react` — attributes: `agent.name`, `max_rounds`
- `agent.reason` — attribute: `agent.name`

Spans are nested under whatever root span your OTLP backend provides.

## Verify it works

Look for this in the startup logs:
```
[OTel] Exporting traces to http://localhost:4317
[OTel] Tracing initialized — service: my-pipeline
```

If you see `[OTel] opentelemetry-sdk not installed` instead, run `pip install arccrew[otel]`.

## Common backends

| Backend | OTLP endpoint (default) |
|---|---|
| Grafana + Tempo | `http://localhost:4317` |
| Jaeger | `http://localhost:4317` |
| Datadog Agent | `http://localhost:4317` |
| Honeycomb | `https://api.honeycomb.io:443` (with API key header) |

For backends that require auth headers, configure them at the collector level — arccrew sends plain OTLP.

## Disable tracing

```bash
# .env
OTEL_ENABLED=false
```
