> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent-mintlify-f21cea86.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry tracing and SigNoz observability

> Enable OpenTelemetry traces, metrics, and logs from Arka and ship them to SigNoz to monitor LLM provider calls, failover events, latency, and token usage.

Export traces, metrics, and logs to [SigNoz](https://signoz.io). **On by default** to local OTLP at `http://127.0.0.1:4318` when SigNoz is running.

## Quick start

```bash theme={null}
arka signoz status
arka signoz setup -y
arka signoz demo
arka ai trace-status
arka observability doctor
```

### Autostart on login (macOS / Linux)

After a one-time `arka signoz setup -y`, enable the local Docker stack to come up at login:

```bash theme={null}
arka signoz autostart install
arka signoz autostart status
```

On macOS, also enable **Docker Desktop → Settings → General → Start Docker Desktop when you sign in**.
Autostart waits for Docker, then runs `foundryctl cast -f casting.yaml --no-gauge`.
Logs: `~/.cache/fish-agent/signoz-autostart.log` (or your `CACHE_DIR`).

Remove with `arka signoz autostart uninstall`. Pass `--autostart` to `arka signoz setup -y` to install in the same step.

`arka observability doctor` is a read-only local check. It reports whether
OpenTelemetry is enabled and configured, but does not claim that SigNoz has
received data. After enabling telemetry, run `arka signoz demo` and verify
`service.name = arka` in the SigNoz traces view. If the doctor reports a
configured exporter but no traces appear, the problem is ingestion or the
SigNoz endpoint—not Arka's route instrumentation.

## Configuration

```env theme={null}
# Enabled by default — override only when needed
SIGNOZ_ENDPOINT=http://localhost:4318
SIGNOZ_UI_URL=http://localhost:8080
OTEL_SERVICE_NAME=arka
# OTEL_SDK_DISABLED=true          # disable all OTLP export
# OTEL_TRACES_ENABLED=0           # disable traces (metrics/logs follow)
# SIGNOZ_API_KEY=                 # for alerts / MCP
```

## What gets traced

* LLM provider calls (model, latency, tokens, failover events)
* **Symbolic / deterministic routing** — offline rule matches, matched `route_*` handler, sub-ms route latency, and `arka.llm.used=false`
* **Deterministic skill execution** — local skills (password, calc, convert, help, etc.) with `arka.execution.kind=deterministic`
* Skill dispatch and routing decisions (linked under `arka.request` for natural-language CLI input)
* MCP client calls
* Supermemory operations

Every dispatched skill records a bounded skill name, duration, exit status, execution kind
(`deterministic`, `llm_skill`, `llm_routed`, `fish`, or `shell`), and whether an LLM was used.
Arka does not add secrets or full user prompts to these attributes.
This makes failures in long-running loops and MCP-backed skills visible without
turning exported logs into a copy of your code or credentials.

Structured logs include `trace_id` and `span_id` when emitted inside an active
span. Use SigNoz log ↔ trace correlation to jump from a skill failure log to
its trace. Metrics `arka.routing.decisions`, `arka.skill.duration`, and
`arka.llm.failover` complement span attributes in the Metrics explorer.

Useful SigNoz trace filters:

* `name = 'arka.request'` — full NL request waterfall (route → skill)
* `name = 'arka.route' AND arka.route.decision = 'symbolic'` — offline symbolic routes only
* `arka.execution.kind = 'deterministic'` — local skills with no LLM
* `arka.llm.used = false` — any span where no LLM participated

## SigNoz dashboard

Install the bundled Arka agent observability dashboard (15 panels: service overview,
skill dispatch latency/errors, routing, LLM failover, model/provider mix, token usage, correlated logs):

```bash theme={null}
arka signoz dashboard install
arka signoz dashboard install --alerts   # also create bundled alert rules
arka signoz dashboard install --dry-run  # preview without POST
arka signoz dashboard list
```

Requires `SIGNOZ_API_KEY` from SigNoz → Settings → Service Accounts. Template JSON:
`signoz/dashboards/arka-agent-observability.json`.

MCP-orchestrated install via self-build:

```bash theme={null}
arka self build observability
arka self build observability --apply
arka self build dashboard --apply
```

## SigNoz MCP + Cursor

```bash theme={null}
arka signoz mcp tools
arka signoz cursor-setup
```

Bundled SigNoz assets (dashboards, alerts, demos) live in `signoz/` in the repo.

<Note>
  OTLP export is on by default to `http://127.0.0.1:4318`. Set `OTEL_SDK_DISABLED=true` or `OTEL_TRACES_ENABLED=0` to opt out.
</Note>

## Production-to-codebase connectors

Export JSON from SigNoz, Sentry, Datadog, or New Relic, then correlate stack
paths with the current repository:

```bash theme={null}
arka telemetry-connect ./production-events.json --root .
arka telemetry-connect ./production-events.json --json
```

This is read-only: it reports event counts, providers, unmatched events, and
frequent file/line hotspots without uploading exports, reading provider
credentials, or editing code.


## Related topics

- [Testing Arka with the pytest suite](/guides/testing.md)
- [How Arka compares to other agents](/concepts/comparison.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Troubleshooting Arka: LLM, routing, voice, and RAG fixes](/reference/troubleshooting.md)
- [Output viewer](/guides/output-viewer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.