AI Observability Platform for LLMs, Apps & AI Agents

This prompt was copied from the Pydantic Logfire website. Set up Logfire in this repository end to end and confirm that fresh data reaches the intended Logfire project.

Keep the user informed with short progress updates, but continue through ordinary, reversible setup work without asking for approval. Do not require a clean Git working tree, a new branch, commits, a detailed task list, plan approval, or commands the user could run only because you chose not to run them. Preserve existing work and follow the repository's instructions.

Pause only for a real decision or boundary: interactive browser authentication, a genuinely ambiguous application or target project after inspection, enabling capture of potentially sensitive AI content, materially increasing production telemetry or cost, deployment or infrastructure changes, or destructive, irreversible, or unrelated work. Ask one concrete question when you need to pause.

## Goal

Get one representative runnable service sending useful traces, logs, or metrics to the exact Logfire project, then verify the first fresh signal. In a monorepo or multi-service system, prove this loop for one service before offering to expand to the rest.

## 1. Understand the repository

1. Read the applicable `AGENTS.md`, `CLAUDE.md`, `README.md`, contribution guidance, and existing setup or deployment files.
2. Identify the language, runtime, package manager, runnable application entry point, and one representative request, job, or agent run to exercise. If this is a library with no application entry point, do not put SDK configuration in library code; use an existing example application or ask one focused question about what should run.
3. Look for existing OpenTelemetry, tracing, logging, sampling, redaction, and exporter configuration. Reuse that telemetry path instead of creating a competing provider or duplicate exporter. Preserve existing scrubbing, sampling, and logging behavior.
4. Inspect the working tree so you do not overwrite the user's changes, but do not make cleanliness, branching, or commits prerequisites for setup.

## 2. Authenticate and select the exact project

Determine the target project's region from its URL or the user's context before authenticating. Run the Logfire CLI yourself from the application directory. Use `uvx logfire` for project authentication and selection regardless of the application's language or package manager; this is a setup tool, not an application dependency. If `uv` is unavailable, install it from https://docs.astral.sh/uv/getting-started/installation/, then use this sequence:

```bash
uvx logfire auth
uvx logfire projects list
uvx logfire projects use <project-name>
uvx logfire whoami
```

1. Run the `auth` command. Let the user complete the browser sign-in if prompted, then continue as soon as the CLI succeeds. The region flag is global and must come immediately after `logfire`, for example `uvx logfire --region eu auth`. Use the same placement on project commands when the target region is known. If it is unknown, omit the flag and let `auth` ask.
2. Run `projects list`. Select the organization and project established by the user's URL or context. If exactly one project is available, use it. If several projects are plausible and repository evidence does not identify the target, ask the user one concise project-selection question. If no projects exist, ask for the project name and run `uvx logfire projects new <project-name>` instead of stopping at an empty list.
3. If local `.logfire` credentials or `LOGFIRE_TOKEN` already exist, run `whoami` before creating another token. Reuse them only when they identify the exact intended project and region.
4. Otherwise, from the application root, run `projects use <project-name>` (add `--org <organization-name>` when needed). This creates `.logfire/logfire_credentials.json` plus `.logfire/.gitignore` with a project-scoped write token for local Python and Node.js development.
5. Run `whoami` and record the exact organization, project, region, and project URL. `LOGFIRE_TOKEN` takes precedence over local credentials, so correct or remove a mismatched ambient token before exercising the app. Authentication alone is not enough: credentials, instrumentation, verification, and every link you give the user must all refer to this same project. Never silently substitute a latest-project redirect or a different convenient project.

Never ask the user to paste a token into chat, and never print, log, hard-code, or commit one. Run local Python and Node.js workloads from the directory containing `.logfire`, or set `LOGFIRE_CREDENTIALS_DIR` when their working directory differs. For Rust, Workers, deployed applications, and generic OpenTelemetry setups that do not read local CLI credentials, transfer the CLI-created token without displaying it into the runtime's existing gitignored local secret mechanism: `LOGFIRE_TOKEN` for Rust and Workers, or the documented OTLP authorization header for generic clients. Put it in a local environment file only when the application already loads that file safely; use the deployment platform's secret manager for production. Browser code must send through an authenticated same-origin backend proxy and must never contain a write token. If a static browser app has no backend or proxy, do not use it as the first proof path.

## 3. Install and instrument

Use persistent dependency commands that match the repository, such as `uv add`, `pnpm add`, or `cargo add`, rather than a one-off global install.

Before editing instrumentation, fetch and read the official Logfire setup guide for coding agents at https://raw.githubusercontent.com/pydantic/logfire/refs/heads/main/logfire/.agents/skills/logfire-instrumentation/SKILL.md, then read the references it links for the representative service's language and frameworks. Use it to find the right runtime guidance, but verify exact APIs and dependency versions against the current linked documentation and installed package types rather than copying version literals.

- Python: install `logfire` with the relevant extras, such as `logfire[fastapi]`, and configure it once at application startup. For a long-running Python service, include system metrics with the repository's dependency command, for example `uv add 'logfire[system-metrics]'` plus detected framework extras, or `uv add 'logfire[fastapi,system-metrics]'`; then call `logfire.instrument_system_metrics()` after `configure()` so the Hosts view works. Skip it for serverless or short-lived workloads and when an existing OpenTelemetry Collector already sends host metrics; do not use `base='full'` without explicit approval.
- Node.js: use `@pydantic/logfire-node`.
- Browser: use `@pydantic/logfire-browser` with the documented backend `traceUrl` proxy.
- Cloudflare Workers: use `@pydantic/logfire-cf-workers` and `logfire`, with the token stored as a Worker secret.
- Rust: use the `logfire` crate and read `LOGFIRE_TOKEN` from the environment.
- Go, Java, .NET, Ruby, PHP, Elixir, and other languages: use the standard OpenTelemetry SDK and the relevant guide at https://pydantic.dev/docs/logfire/guides/alternative-clients/.

Read https://pydantic.dev/docs/logfire/resources/languages/ and the applicable pages under https://pydantic.dev/docs/logfire/integrations/. For Python, run `logfire inspect` inside the application's own environment after installing Logfire, for example `uv run logfire inspect`; do not use the isolated `uvx` environment for package detection. Prefer supported integrations for the frameworks, databases, HTTP clients, task queues, and AI libraries already used by the representative service. Add a stable service name. If no integration produces an identifiable operation, add one small, useful manual span around the representative request or job rather than scattering instrumentation through the codebase.

For AI instrumentation, begin in metadata-only or no-content mode: record timing, model/provider, token usage, tool names, status, and errors without prompts, responses, tool arguments, tool results, or binary content. Do not assume an instrumentor's default is content-safe and do not rely on scrubbing for AI message attributes. Use explicit documented controls, including `logfire.instrument_pydantic_ai(include_content=False, include_binary_content=False)` for Pydantic AI and `recordInputs: false, recordOutputs: false` with Vercel AI SDK telemetry. If an integration has no documented content-disable control, do not enable that integration on the initial pass; use a small metadata-only manual span or ask for explicit approval. After the first signal is verified, explain the debugging benefit and privacy tradeoff of content capture and enable it only with explicit user approval.

Make the smallest useful setup change. Do not refactor unrelated code, instrument every service before the first success, change production sampling, or deploy anything as part of the initial proof.

## 4. Exercise and verify

1. Run the relevant format, lint, typecheck, and focused tests for the files you changed. Distinguish pre-existing or unrelated failures from regressions caused by the setup; report them, but do not misrepresent them as a Logfire failure.
2. Start the real application or workload from the credential-aware working directory and trigger one representative request, job, or agent run. Note an identifiable service name and operation that should appear. If system metrics were enabled, keep the process alive long enough for at least one collection interval.
3. Check for startup, credential, and exporter errors, but do not treat their absence as success.
4. Confirm that fresh data appears in the exact project reported by `whoami`. Use available Logfire MCP, API, or signed-in browser capabilities to search for the service and operation yourself; the CLI can verify credentials but cannot prove ingestion. Ask the user to check the exact Live view only when you genuinely cannot access a verification path. If system metrics were enabled and you can access the UI or API, also confirm the host or a fresh `system.*` metric.

If data does not appear, trace the path in order: application startup and configuration, exact project credentials and region, integration registration, the exercised code path, exporter errors or flushing, and ingestion. Make the smallest safe correction, rerun the workload, and verify again. Report one specific blocker if you cannot complete the loop; do not return a generic troubleshooting checklist.

Success means fresh telemetry from the exercised workload was observed in the intended project. Summarize what you changed, what you ran, the exact project used, and the signal you verified. If system metrics were enabled, link to that exact project's Hosts view, offer the `Basic System Metrics (Logfire)` dashboard, and state whether host data was observed or is still awaiting its first collection. Then offer relevant next steps such as expanding to other services, production credential wiring, dashboards, alerts, additional integrations, or opt-in AI content capture. Offer commits or a pull request if useful, but do not make them a prerequisite and do not create a PR unless the user asks.