logfire

What you will run into

You want observability for your Python app — traces, spans, metrics — without building a whole observability stack; Logfire is OpenTelemetry-based observability for Python. The two things people trip on: the first install is slow (opentelemetry dependency family, 3-5 minutes — normal, not stuck), and the "must log in?" question — local preview runs without any token (verified), only uploading to the hosted platform needs logfire auth. When to use it:

• Tracing Python apps with minimal code (logfire.configure + instrument_*);
• Local preview of traces/spans without accounts;
• Uploading to the hosted platform with token auth.

When not to use it: you need a self-hosted full observability stack with your own retention/policies.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

pip installs logfire==4.41.0 (Python >= 3.10; opentelemetry family deps, first install 3-5 minutes — normal). logfire.configure is the instrumentation entry; local preview mode runs without a token; logfire auth stores the token in ~/.logfire/ for uploading telemetry. Key concepts:

• configure: instrumentation entry point;
• preview: local preview of traces/spans (no token);
• auth: browser/device-code login (token stored in ~/.logfire/).

Where it writes: ~/.logfire/ (own directory, no shared registration surface).

Step by step

Step 1: Install the package (why pin the version: 4.41.0 is the verified collection version)

Why: logfire depends on the opentelemetry family; the first install takes 3-5 minutes — be patient, it is not stuck. Mainland PyPI official times out, so the Tsinghua mirror prefix is required.

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple logfire==4.41.0
logfire --version

Expected output: Running Logfire 4.41.0 with CPython ...

logfire --help

Expected output: full CLI docs After install, confirm:

• --version prints 4.41.0;
• logfire --help has full CLI docs.

Stuck? How to recover:

• install takes long → opentelemetry deps are many, normal (first 3-5 minutes); confirm the Tsinghua mirror prefix;
• Python version → confirm >= 3.10.

Step 2: Code instrumentation smoke (local preview, no token)

Why: logfire.configure is the instrumentation entry; local preview mode runs without a token — verify the library works first, then decide whether to connect the hosted platform.

python3 -c "import logfire; logfire.configure; print('logfire configured: OK')"

Expected output: logfire configured: OK (local preview runs without a token) After install, confirm:

• prints logfire configured: OK, no auth error.

Stuck? How to recover:

• token error → local preview does not need a token; if it prompts to log in, use logfire preview or skip auth;
• import fails → confirm pip and python3 share the same environment.

Step 3: Login to the hosted platform + local preview (optional)

Why: logfire auth goes through browser/device-code login (token stored in ~/.logfire/), needed only for uploading telemetry; logfire preview starts a local preview to view traces/spans.

logfire auth

Expected output: browser/device-code login flow (interactive; token stored in ~/.logfire/)

logfire preview

Expected output: local preview address (view traces/spans; Ctrl+C to exit) After install, confirm:

• after auth, ~/.logfire/ has a token;
• preview opens the preview address.

Stuck? How to recover:

• auth interactive stuck → use --non-interactive or the device-code flow;
• preview port taken → see global options in --help (--base-url/--region etc.).

How to confirm it works

Step 1: Confirm the library imports and configures

Why: import logfire + configure without errors means the library is installed complete and the dependency chain is fine; local preview mode passes this line without a token.

python3 -c "import logfire; logfire.configure; print('logfire configured: OK')"

Expected output: logfire configured: OK (local preview runs without a token) Stuck? How to recover:

• import fails → confirm pip and python3 share the same environment (activate the venv first);
• token error → local preview does not need a token; skip auth.

Step 2: Confirm the CLI and optional connectivity surface

Why: logfire --version confirms the CLI; when uploading to the hosted platform, logfire auth then checking ~/.logfire/ for a token confirms the auth path.

logfire --version

Expected output: Running Logfire 4.41.0 with CPython ... Stuck? How to recover:

• auth interactive stuck → use --non-interactive or the device-code flow;
• preview port taken → see global options in --help (--base-url/--region etc.).

Other environments

• Install time: opentelemetry family deps, first install 3-5 minutes is normal, not stuck; mainland must use the Tsinghua mirror prefix.
• Windows / macOS: pip install and instrumentation code are the same; token and config also go to ~/.logfire/.
• Data egress: telemetry does not leave the machine without login/local preview; uploading to the hosted platform needs a token (writes ~/.logfire/).
• Write surface: only ~/.logfire/ (own directory, no shared registration surface); co-install judged all possible-compatible.

Daily usage

Startup and entry

• Instrumentation: logfire.configure in code + instrument_* calls;
• CLI: logfire --help (auth/preview etc.).

Common operations

Operation 1: Code instrumentation smoke (local preview, no token; verified here)

python3 -c "import logfire; logfire.configure; print('logfire configured: OK')"

Expected output: logfire configured: OK (local preview runs without a token) Operation 2: Login to the hosted platform (only needed for uploading)

logfire auth

Expected output: browser/device-code login flow (interactive; token stored in ~/.logfire/) Operation 3: Local preview

logfire preview

Expected output: local preview address (view traces/spans; Ctrl+C to exit)

Data and directories

• Token/config: ~/.logfire/;
• In-code: logfire.instrument_* / logfire.configure calls (project code, not auto-removed).

Uninstall & cleanup

note: pip uninstall + remove ~/.logfire; in-code instrumentation is project code, not auto-deleted

pip uninstall -y logfire logfire-api 2>/dev/null || true
rm -rf ~/.logfire
command -v logfire >/dev/null 2>&1 && echo "残留: logfire 仍存在" || echo "logfire removed: OK"

Expected output: logfire removed: OK Manual checklist (code changes, not auto-deleted):

• logfire.instrument_* / logfire.configure calls in the codebase (OpenTelemetry instrumentation code)
• logfire dependency in pyproject/requirements (pip uninstall handled the local environment; project files need manual removal)

Dependency warnings

• Version: [4.41.0, 4.41.0] locked (verified collection version).
• Environment: Python >= 3.10; opentelemetry family deps (first install 3-5 minutes).
• Network: PyPI official times out, must use the Tsinghua mirror.
• Write surface: ~/.logfire/ (own, no shared registration surface).
• Data egress: only when uploading to the hosted platform (token auth); no login/local preview = no egress.
• Co-install: judged all possible-compatible — logfire only writes ~/.logfire/ (own), no shared registration surface.

FAQ

• Q: Do I have to log in? A: No. Local preview mode runs without a token; only uploading to the hosted platform needs logfire auth.
• Q: Install very slow? A: opentelemetry deps are many, normal (first 3-5 minutes); use the Tsinghua mirror prefix domestically.
• Q: Will telemetry data leave my machine? A: only when uploading to the hosted platform (token auth); no login/local preview = no egress. Watch data compliance in production.
• Q: Conflicts with other plugins? A: judged all possible-compatible — logfire only writes ~/.logfire/ (own), no shared registration surface.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.