Skip to main content

Troubleshooting & FAQ

Quick fixes for the issues teams hit most often. If none apply, check the Ingest & OTLP and Configuration references.

No data appears in the dashboard​

Work through three things in order:

  1. Endpoint. Confirm the SDK's endpoint (or OTEL_EXPORTER_OTLP_ENDPOINT) points where your collector actually is — https://ingest.splyntra.com on Cloud, http://localhost:4318 when self-hosting. A trailing typo or wrong port silently drops spans.
  2. Key. The ingest key must be valid and sent as Authorization: Bearer <key>. See the 401 section below.
  3. Instrumentation. Make sure you actually initialize the SDK before your agent/LLM code runs, and that instrument names the frameworks/providers you use (e.g. ("openai",) / ["openai"]). An instrumentor whose package isn't installed is a safe no-op — but it also captures nothing.

Also confirm you selected the right project and environment in the dashboard; a run sent with environment="development" won't show under a production filter.

401 Unauthorized​

The key is missing, malformed, or wrong:

  • The header must be exactly Authorization: Bearer <ingest key> — the word Bearer and a space, then the raw key.
  • Raw keys are shown once at creation and stored only as SHA-256 hashes. If you lost it, mint a new one under Settings → API keys.
  • Pass the key through an environment variable, not a literal, so it isn't truncated or quoted incorrectly.

The dev key is rejected in production​

splyntra_dev_key is a development-only fallback. The collector accepts it only when running with ENV/NODE_ENV=development, and rejects it in production (fail-closed). Mint a real ingest key and set SPLYNTRA_API_KEY to it. Production services should refuse to start on the dev key — see Production agent.

The guard let a request through (fail-open)​

The inline guard is fail-open by default (guard_fail_open=True / guardFailOpen: true): if the guard service is unreachable, the call is allowed so a guard outage doesn't take your agent down. If you need blocking to take precedence over availability, set fail-open to false to fail closed. Also confirm guard is set to "block" (not "monitor" or "off") for enforcement. See Guardrails.

Spans are missing from short-lived scripts​

Spans are buffered and exported asynchronously. A script that exits immediately after its last call can terminate before the batch is flushed. Flush explicitly before the process ends:

  • TypeScript: await splyntra.shutdown();
  • Python: the SDK flushes on normal interpreter exit and on SIGTERM/SIGINT; for a hard early exit, let the process drain rather than killing it.

Long-running services flush on graceful shutdown — just make sure you flush before process.exit(). See Production agent.

Commercial endpoints return 404​

The governance, identity, and compliance endpoints (/v1/ledger, /v1/policies, /v1/delegation, /v1/authorize, /v1/spend-limits, /v1/approvals, /v1/approval-rules, /v1/compliance/*, /v1/identity/*) are registered only by the commercial collector-cloud binary. The Community collector imports none of the ee/* modules, so these paths return 404 by design. To use them, run the Enterprise/Cloud edition. The open-core endpoints (/v1/traces, /v1/logs, /v1/scorers, /v1/guard, /v1/integrations/<platform>) are present in every edition. See API overview and Editions & licensing.

Still stuck?​