logfire-api review
logfire-api 4.41.0 is a compatibility shim for Python packages that want optional Pydantic Logfire instrumentation. Importing logfire_api loads the real logfire module when it exists; without that SDK, the package supplies matching names whose logging, span, decorator, and integration calls do nothing. It sends no telemetry, owns no backend, and configures no project. Version 4.41.0 updates the cloned declarations for current SDK behavior, including Claude Agent SDK state, expiring read tokens, unknown token-region warnings, and the system.cpu.load_average.1m and system.process.count metric names. The fallback's silent contract is unchanged.
logfire-api 4.41.0 installed in 0.3 seconds as 1 package using 1 MB, imported in 0.28 seconds, and produced 0 audit findings in our sandbox. That tiny footprint suits library authors offering optional Logfire hooks, but applications expecting telemetry should install and configure logfire itself.
We installed it
| Install | ✓ · 0.3s | 1 package on disk · 1 MB |
| Import | ✓ | import logfire_api in 0.28s · pure Python · py.typed · requires Python >=3.10 |
| Known vulns | 0 | (pip-audit) |
Answers from our run
Does logfire-api install cleanly?
Yes. In a fresh container with an empty cache, pip install logfire-api finished in 0.3s, leaving 1 package and 1 MB on disk. pip-audit reported no known vulnerabilities.
What does logfire-api need to run?
Python >=3.10, and nothing compiled: it is pure Python. In our run import logfire_api succeeded in 0.28s, and the package ships py.typed for type checkers.
logfire-api or logfire: which should you use?
logfire: Install it in an application that needs real Logfire configuration, exporters, integrations, and recorded events. logfire-api 4.41.0 installed in 0.3 seconds as 1 package using 1 MB, imported in 0.28 seconds, and produced 0 audit findings in our sandbox.
When should you not use logfire-api?
You own the application and expect events to appear. With only logfire-api installed, info(), span(), configure(), and force_flush() intentionally produce no telemetry.
Use it if
- You publish a reusable Python package and want application owners to opt into Logfire without making the full SDK a required dependency.
- Library control flow must stay identical when telemetry is absent, including context managers and decorators around real work.
- A py.typed API clone is preferable to repeated try and except ImportError blocks throughout the package.
- Your tests cover both the one-package no-op install and an environment containing the matching real Logfire SDK.
- You own the application and expect events to appear. With only logfire-api installed, info(), span(), configure(), and force_flush() intentionally produce no telemetry.
- A missing observability SDK must fail loudly. This package accepts the missing import and supplies permissive no-op objects, so startup can look healthy while nothing is exported.
- You need vendor-neutral instrumentation. opentelemetry-api defines a provider boundary without cloning Logfire's SDK names and integration methods.
- Runtime checking must catch misspelled instrumentation attributes. The fallback Logfire and span objects can return MagicMock for unknown attributes, leaving type checking as the main guard.
- The project supports Python 3.9. Version 4.41.0 requires Python 3.10 or newer.
Setup reality
We installed logfire-api 4.41.0 in a fresh Python 3.12 Bookworm sandbox in 0.3 seconds. It left 1 package and 1 MB on disk, declares 0 direct dependencies, and pip-audit found 0 known vulnerabilities. The pure-Python package requires Python 3.10 or newer and ships py.typed metadata. import logfire_api worked in 0.28 seconds in our sandbox.
No token, project name, exporter, or config file is needed for the shim, because the one-package fallback sends nothing. At import, it tries to load logfire and replaces its own sys.modules entry with that module if successful. Otherwise it defines no-op methods, context managers, decorators, and placeholder option classes. Install and configure the real logfire package in the host application when events must leave the process.
The fallback is deliberately forgiving. span() yields an object whose is_recording() is false; instrument() returns the original callable; ASGI and WSGI helpers return the original app; get_context() has no propagated trace data; unknown object attributes may become MagicMock values. Keep business behavior independent of all those return values. Static type checking matters because a runtime typo may not fail in the 1 MB no-SDK environment.
Test two environments. The first should contain only logfire-api 4.41.0 and prove every feature still works with silent instrumentation. The second should install a compatible logfire release, configure its test exporter or SDK test facilities, and assert that expected spans are recorded. Import logfire_api consistently inside the library; importing logfire directly makes telemetry mandatory, while mixing both names makes import order part of the test result.
Patterns
Add an event that may be silent emit-optional-event
import logfire_api
def parse_document(document_id: str) -> None:
logfire_api.info(
'Parsing document {document_id}',
document_id=document_id,
)
parse_bytes(document_id)With the 1-package shim alone, info() returns without recording an event. parse_bytes must behave the same in that mode.
Wrap work in a no-op-safe span wrap-optional-span
import logfire_api
def rebuild_index(name: str) -> None:
with logfire_api.span('Rebuild {name}', name=name):
perform_rebuild(name)The fallback span supports the context-manager protocol and reports is_recording() as false. The with block still runs normally.
Decorate a function without requiring the SDK instrument-function
import logfire_api
@logfire_api.instrument('Resolve customer')
def resolve_customer(customer_id: str):
return repository.get(customer_id)Without logfire installed, instrument() returns the original function and adds no timing or exception record.
Use the bare instrument decorator use-bare-decorator
import logfire_api
@logfire_api.instrument
def calculate_total(lines: list[int]) -> int:
return sum(lines)Bare @instrument support was fixed in the 4.38 line and is present in 4.41.0. The fallback leaves calculate_total unchanged.
Reuse an optionally tagged instance attach-tags
import logfire_api
telemetry = logfire_api.with_tags('payments')
def charge(order_id: str) -> None:
telemetry.info('Charging {order_id}', order_id=order_id)The fallback returns its same no-op Logfire object. Do not read tags back as business state or branch on them.
Record an error and preserve failure record-exception
import logfire_api
def load_record(record_id: str):
try:
return backend.load(record_id)
except Exception:
logfire_api.exception('Load failed for {record_id}', record_id=record_id)
raiseThe explicit raise preserves the failure when telemetry is absent. exception() alone does not raise or persist anything in fallback mode.
Suppress instrumentation around an exporter suppress-internal-telemetry
import logfire_api
def send_internal_batch(batch) -> None:
with logfire_api.suppress_instrumentation():
transport.send(batch)The shim supplies a null context manager. Suppression changes behavior only after the real SDK replaces logfire_api.
Keep optional ASGI wrapping transparent wrap-asgi-app
import logfire_api
def instrument_app(app):
return logfire_api.instrument_asgi(app)Fallback instrument_asgi() returns the original app object. Do not assume the returned application carries tracing middleware.
Check for Logfire before importing the shim detect-real-sdk
from importlib.util import find_spec
LOGFIRE_INSTALLED = find_spec('logfire') is not None
import logfire_apiRun find_spec('logfire') first. After the import, logfire_api may refer to the real logfire module through sys.modules replacement.
Ignore optional instrumentation results avoid-return-value-dependency
import logfire_api
def publish(message: bytes) -> None:
logfire_api.info('Publishing {size} bytes', size=len(message))
broker.publish(message)No-op calls may return None, empty values, or placeholder objects. Use the broker result, not the telemetry call, to decide whether publishing succeeded.
Prove business output survives silent telemetry test-no-sdk-mode
def test_total_without_telemetry(monkeypatch):
import logfire_api
monkeypatch.setattr(logfire_api, 'info', lambda *args, **kwargs: None)
assert calculate_total([2, 3, 5]) == 10Run this in an environment that installs logfire-api but omits logfire. The 10 result proves the business path does not depend on an SDK response.
Keep a separate SDK integration test test-real-sdk-mode
def test_real_logfire_is_selected():
import logfire
import logfire_api
assert logfire_api is logfireRun this in a second environment with compatible 4.41.0 packages. Add exporter assertions using Logfire's test facilities to prove spans are recorded.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| logfire | PyPI | Install it in an application that needs real Logfire configuration, exporters, integrations, and recorded events. |
| opentelemetry-api | PyPI | Use it when a library needs a vendor-neutral tracing and metrics API with the provider selected by the application. |
| structlog | PyPI | Use it when the requirement is structured application logs with explicit processors and output configuration. |
More utils guides
lru-cache · ajv · type-fest · p-limit · find-up · js-yaml · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.