Firetiger Instrument
Instrument an application with OpenTelemetry so it exports traces (and logs/metrics) to Firetiger. For full
onboarding that also connects integrations and creates a monitoring agent, use firetiger-setup — this skill
is instrumentation only.
Workflow
- Get credentials. Call the Firetiger MCP tool
get_ingest_credentials → OTLP endpoint + username +
password. If the MCP tools aren't available, tell the user to connect the Firetiger MCP server
(https://api.cloud.firetiger.com/mcp/v1) and sign in, then retry.
- Detect the framework (table below) and open the matching reference.
- Check for existing instrumentation — search for
@opentelemetry (Node), opentelemetry (Python), or
go.opentelemetry.io (Go) imports. If present, just repoint the exporter at Firetiger instead of adding a
second SDK.
- Add the SDK init + env vars, run, and verify data lands.
| Detected file |
Stack |
Reference |
next.config.js / next.config.ts |
Next.js (uses @vercel/otel) |
references/nodejs.md |
package.json |
Node.js / TypeScript |
references/nodejs.md |
requirements.txt / pyproject.toml / setup.py |
Python |
references/python.md |
go.mod |
Go |
references/go.md |
Cargo.toml |
Rust |
references/rust.md |
For business-critical spans, log/trace correlation, and attribute best practices, see
references/custom-spans.md.
Critical: initialization order
OpenTelemetry MUST initialize before any other import. If instrumented libraries (Express, HTTP clients,
database drivers) load before the SDK starts, auto-instrumentation never attaches and you get no spans. Load
the instrumentation file first (node --import ./instrumentation.js …, opentelemetry-instrument python …,
or an init call at the very top of main).
Authentication & environment variables
Firetiger authenticates ingest with HTTP Basic auth — the OTLP header is
Authorization=Basic <base64(username:password)>, not a Bearer token. Configure these wherever the app
runs (.env.local for dev, the deploy platform for prod), using values from get_ingest_credentials:
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.cloud.firetiger.com" # use the value from get_ingest_credentials
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64(username:password)>"
OTEL_SERVICE_NAME="your-service-name"
Add credential files to .gitignore (.env.local, .env.*.local). Never commit credentials.
Verify
- Generate some traffic.
- Query with the
firetiger-query skill:
SELECT name, start_time FROM "opentelemetry/traces/your-service-name" WHERE start_time >= NOW() - INTERVAL '15 minutes' LIMIT 10
(run SHOW TABLES; first to confirm your service's table appeared).
Common Mistakes
| # |
Mistake |
Fix |
| 1 |
Init imported after app code |
Load the instrumentation file first — otherwise auto-instrumentation can't patch already-imported libraries. |
| 2 |
Using Authorization=Bearer … |
Firetiger ingest is HTTP Basic auth — Authorization=Basic <base64(user:pass)>. |
| 3 |
Hardcoding the endpoint |
Use the endpoint from get_ingest_credentials; it can differ per org/region. |
| 4 |
Adding a second SDK on top of existing OTEL |
Detect existing instrumentation and repoint the exporter instead. |
| 5 |
SimpleSpanProcessor in production |
Use BatchSpanProcessor with gzip compression for throughput. |
| 6 |
Committing .env.local |
Add credential files to .gitignore. |
| 7 |
Service name mismatch |
The OTEL_SERVICE_NAME you set is the {service_name} in the query table "opentelemetry/traces/{service_name}". |
| 8 |
No graceful shutdown |
Call sdk.shutdown() on SIGTERM so buffered spans flush before exit. |
Related
- Verify the data landed and start querying it:
firetiger-query (SHOW TABLES;, then the per-service tables this instrumentation creates).
- Add business-critical spans, log/trace correlation, and attribute hygiene: references/custom-spans.md.
- Full onboarding beyond instrumentation (connect integrations, register deploys, create a monitoring agent):
firetiger-setup.
- Not writing app code? If you only have platform logs/traces (Vercel, AWS, GCP, Cloudflare) or a Datadog Agent, wire a drain via
firetiger-setup instead of an SDK.
- Once your change ships: have Firetiger watch the deploy with
firetiger-monitor-deploy.
1---2name: firetiger-instrument3description: Use when adding OpenTelemetry instrumentation to an application so it sends telemetry to Firetiger — setting up tracing, configuring the OTLP exporter, or connecting a Node.js, Next.js, Python, Go, or Rust app to Firetiger. Always use this skill when instrumenting for Firetiger — it carries the critical gotchas (init must load before any other import, Firetiger ingest uses HTTP Basic auth not Bearer, credentials come from the get_ingest_credentials MCP tool) that make telemetry actually show up.4license: Apache-2.05---67# Firetiger Instrument89Instrument an application with OpenTelemetry so it exports traces (and logs/metrics) to Firetiger. For full10onboarding that also connects integrations and creates a monitoring agent, use `firetiger-setup` — this skill11is instrumentation only.1213## Workflow14151. **Get credentials.** Call the Firetiger MCP tool **`get_ingest_credentials`** → OTLP endpoint + username +16 password. If the MCP tools aren't available, tell the user to connect the Firetiger MCP server17 (`https://api.cloud.firetiger.com/mcp/v1`) and sign in, then retry.182. **Detect the framework** (table below) and open the matching reference.193. **Check for existing instrumentation** — search for `@opentelemetry` (Node), `opentelemetry` (Python), or20 `go.opentelemetry.io` (Go) imports. If present, just repoint the exporter at Firetiger instead of adding a21 second SDK.224. **Add the SDK init + env vars**, run, and verify data lands.2324| Detected file | Stack | Reference |25|---------------|-------|-----------|26| `next.config.js` / `next.config.ts` | Next.js (uses `@vercel/otel`) | [references/nodejs.md](references/nodejs.md) |27| `package.json` | Node.js / TypeScript | [references/nodejs.md](references/nodejs.md) |28| `requirements.txt` / `pyproject.toml` / `setup.py` | Python | [references/python.md](references/python.md) |29| `go.mod` | Go | [references/go.md](references/go.md) |30| `Cargo.toml` | Rust | [references/rust.md](references/rust.md) |3132For business-critical spans, log/trace correlation, and attribute best practices, see33[references/custom-spans.md](references/custom-spans.md).3435## Critical: initialization order3637**OpenTelemetry MUST initialize before any other import.** If instrumented libraries (Express, HTTP clients,38database drivers) load before the SDK starts, auto-instrumentation never attaches and you get no spans. Load39the instrumentation file first (`node --import ./instrumentation.js …`, `opentelemetry-instrument python …`,40or an init call at the very top of `main`).4142## Authentication & environment variables4344Firetiger authenticates ingest with **HTTP Basic auth** — the OTLP header is45`Authorization=Basic <base64(username:password)>`, **not** a Bearer token. Configure these wherever the app46runs (`.env.local` for dev, the deploy platform for prod), using values from `get_ingest_credentials`:4748```bash49OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.cloud.firetiger.com" # use the value from get_ingest_credentials50OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64(username:password)>"51OTEL_SERVICE_NAME="your-service-name"52```5354Add credential files to `.gitignore` (`.env.local`, `.env.*.local`). Never commit credentials.5556## Verify57581. Generate some traffic.592. Query with the `firetiger-query` skill:60 `SELECT name, start_time FROM "opentelemetry/traces/your-service-name" WHERE start_time >= NOW() - INTERVAL '15 minutes' LIMIT 10`61 (run `SHOW TABLES;` first to confirm your service's table appeared).6263## Common Mistakes6465| # | Mistake | Fix |66|---|---------|-----|67| 1 | **Init imported after app code** | Load the instrumentation file first — otherwise auto-instrumentation can't patch already-imported libraries. |68| 2 | **Using `Authorization=Bearer …`** | Firetiger ingest is HTTP Basic auth — `Authorization=Basic <base64(user:pass)>`. |69| 3 | **Hardcoding the endpoint** | Use the endpoint from `get_ingest_credentials`; it can differ per org/region. |70| 4 | **Adding a second SDK on top of existing OTEL** | Detect existing instrumentation and repoint the exporter instead. |71| 5 | **`SimpleSpanProcessor` in production** | Use `BatchSpanProcessor` with `gzip` compression for throughput. |72| 6 | **Committing `.env.local`** | Add credential files to `.gitignore`. |73| 7 | **Service name mismatch** | The `OTEL_SERVICE_NAME` you set is the `{service_name}` in the query table `"opentelemetry/traces/{service_name}"`. |74| 8 | **No graceful shutdown** | Call `sdk.shutdown()` on `SIGTERM` so buffered spans flush before exit. |7576## Related7778- **Verify the data landed and start querying it:** `firetiger-query` (`SHOW TABLES;`, then the per-service tables this instrumentation creates).79- **Add business-critical spans, log/trace correlation, and attribute hygiene:** [references/custom-spans.md](references/custom-spans.md).80- **Full onboarding beyond instrumentation** (connect integrations, register deploys, create a monitoring agent): `firetiger-setup`.81- **Not writing app code?** If you only have platform logs/traces (Vercel, AWS, GCP, Cloudflare) or a Datadog Agent, wire a drain via `firetiger-setup` instead of an SDK.82- **Once your change ships:** have Firetiger watch the deploy with `firetiger-monitor-deploy`.
firetiger-oss