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

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# 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) when enabled. **Off by default.**

## 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}
OTEL_TRACES_ENABLED=1
SIGNOZ_ENDPOINT=http://localhost:4318
SIGNOZ_UI_URL=http://localhost:8080
OTEL_SERVICE_NAME=arka
# SIGNOZ_API_KEY=               # for alerts / MCP
```

## What gets traced

* LLM provider calls (model, latency, tokens, failover events)
* Skill dispatch and routing decisions
* MCP client calls
* Supermemory operations

Every dispatched skill records a bounded skill name, duration, exit status, and
error state. Secrets and full user prompts are not added to these attributes.
This makes failures in long-running loops and MCP-backed skills visible without
turning exported logs into a copy of the user's 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.

## 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>
  Both `OTEL_TRACES_ENABLED=1` and `SIGNOZ_ENDPOINT` must be set for traces to export.
</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)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Troubleshooting Arka: LLM, routing, voice, and RAG fixes](/reference/troubleshooting.md)
- [Integrations](/guides/integrations.md)
- [Workspace discovery](/guides/workspace.md)