---
name: tidal-telemetry
description: Instrument any app to send LLM telemetry to Tidal Telemetry, verify the setup, and troubleshoot ingestion. Use when the user wants to set up, verify, or debug Tidal Telemetry / LLM observability for their project.
---

# Tidal Telemetry — setup, verification & troubleshooting

Tidal Telemetry ingests OpenTelemetry (OTLP HTTP/protobuf) traces, metrics and logs per project. Each project has its own endpoint and bearer token, shown on the project's onboarding page.

## Connect the Tidal MCP first (one command)

```bash
claude mcp add --transport http tidal https://otlp.llmcfo.com/mcp --header "Authorization: Bearer <project-token>"
```

Then prefer the MCP tools over guessing:
- `account_status` — project identity + live ingestion stats (span counts, last trace time, services seen).
- `verify_setup` — end-to-end checklist: token, collector, recent data.
- `send_test_trace` — server injects a synthetic span and confirms it lands in storage.
- `setup_instructions` — credential-filled instructions per platform (python, typescript, docker, kubernetes, zero-code OTel).
- `troubleshoot` — symptom-driven debugging (no data, 401, 404, timeouts) with live server-side facts.

## Instrumenting

1. Preferred: the Tidal SDK (`pip install tidal-telemetry` / `npm install tidal-telemetry`), then `tidal.init(api_key=..., project=...)` in Python or `tidal.init({ apiKey, project })` in Node. One call auto-instruments OpenAI, Anthropic, LangChain, LlamaIndex, Bedrock, Ollama, vector DBs, and records token counts + costs. Env-var config: `TIDAL_API_KEY` + `TIDAL_PROJECT`.
2. Fallback: plain OTel env vars — `OTEL_EXPORTER_OTLP_ENDPOINT` (base URL, no /v1/traces suffix), `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, `OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"`, `OTEL_SERVICE_NAME`.
3. Docker: env vars on the service. Kubernetes: Secret + `envFrom`. Never commit the token to git.

## Verifying

1. `curl -sS -X POST "<endpoint>/v1/traces" -H "Content-Type: application/json" -H "Authorization: Bearer <token>" -d '{"resourceSpans":[]}'` → expect HTTP 200 `{"partialSuccess":{}}`.
2. Trigger one real LLM call in the app.
3. Call MCP `verify_setup` — it checks whether spans actually reached storage in the last minutes.

## Troubleshooting quick map

- **401** → wrong/missing token. Header must be exactly `Authorization: Bearer <token>` (in OTel env syntax: `Authorization=Bearer <token>`).
- **404 unknown tenant** → endpoint path wrong; use the exact endpoint from the onboarding page, don't append /v1/traces yourself in the env var.
- **200 but no data in dashboard** → SDK batching (wait ~30 s), wrong project selected in the UI, or app exits before flush (call the SDK shutdown/force-flush on exit).
- **Timeouts from inside Docker/K8s** → egress/proxy rules; test the curl from inside the container/pod.
- Anything else → MCP `troubleshoot` with the symptom.