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

Quick start

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:

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

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):

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:

arka self build observability
arka self build observability --apply
arka self build dashboard --apply

SigNoz MCP + Cursor

arka signoz mcp tools
arka signoz cursor-setup

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

Both OTEL_TRACES_ENABLED=1 and SIGNOZ_ENDPOINT must be set for traces to export.

Production-to-codebase connectors

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

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.