The logfire-api Shim Package
Relevant source files
The following files were used as context for generating this wiki page:
The logfire-api package is a no-op shim package designed for library authors. Its primary purpose is to allow third-party libraries to include Logfire instrumentation without forcing a hard dependency on the full logfire SDK, which contains heavy dependencies like OpenTelemetry and Pydantic. By depending on logfire-api, a library can provide out-of-the-box observability that only becomes active if the end-user explicitly installs the full logfire package.
At runtime, logfire-api provides minimal "dummy" implementations of the Logfire API. If the full logfire package is present in the environment, the shim effectively stays out of the way or redirects to the real implementation, ensuring that instrumentation calls do not fail even if Logfire is not configured or installed.
Sources: CLAUDE.md:61-65, logfire-api/pyproject.toml:1-15
Architecture and Design
The shim package is structured to mirror the public API of the main logfire module. This ensures that any code written against logfire-api is functionally compatible with the full SDK.
The No-Op Mechanism
The core logic resides in logfire_api/__init__.py. It provides minimal implementations of functions like span, log, and various instrument_ methods. These implementations are designed to perform no operations (no-op) and return dummy objects like a LogfireSpan that does not actually record any data.
Interaction with the Full SDK
The following diagram illustrates how logfire-api behaves depending on the presence of the full logfire package:
The package contains .pyi stubs which are autogenerated during the release process to ensure type-checking parity with the main SDK.
Sources: CLAUDE.md:61-65, tests/test_logfire_api.py:32-45
Key Components and API Coverage
The shim package must keep its API in sync with the public interface of the main logfire module. This includes logging methods, span management, and instrumentation wrappers.
Supported API Members
Based on runtime tests, logfire-api provides the following components:
| Category | Members |
|---|---|
| Core | Logfire, LogfireSpan, configure, shutdown, with_settings, with_tags |
| Logging | log, trace, debug, info, notice, warn, warning, error, exception, fatal |
| Instrumentation | instrument, instrument_fastapi, instrument_pydantic, instrument_openai, instrument_aws_lambda, etc. |
| Context | get_context, attach_context, get_baggage, set_baggage |
| Configuration | ConsoleOptions, SamplingOptions, ScrubbingOptions, AdvancedOptions |
Managed Variables Exception
Notably, Managed Variables APIs (e.g., var, variables_get, variables_push) are intentionally excluded from logfire-api. Users requiring remote configuration or managed variables must use the full Logfire SDK.
Sources: tests/test_logfire_api.py:108-115, tests/test_logfire_api.py:46-100
Release and Synchronization
Maintaining the shim requires strict version parity and API synchronization with the main logfire package.
Version Parity
The project enforces that the version in logfire-api/pyproject.toml matches the version in the root pyproject.toml. This is validated during testing and automated during the release preparation phase.
Sources: tests/test_logfire_api.py:230-240, release/prepare.py:11-20
Automated Stub Generation
Because the shim is a manual implementation of a large API, the project uses a make generate-stubs command to update the __init__.pyi files. This automation ensures that static type checkers (like Pyright or Mypy) see the same signatures in the shim as they do in the full SDK.
Usage in Libraries
For a library developer, using the shim involves adding logfire-api to the project's dependencies instead of logfire.
# In a library file
try:
import logfire_api as logfire
except ImportError:
# Fallback if even the shim isn't there, though usually
# the library would list logfire-api in its requirements.
import logging as logfire
def my_library_function():
with logfire.span("library_operation"):
# This call is safe even if the user hasn't installed logfire
logfire.info("Doing work")
...
The test_logfire_api.py suite verifies this "without logfire" scenario by mocking sys.modules to ensure that logfire_api remains functional and error-free when the main SDK is missing.
Sources: tests/test_logfire_api.py:21-30, logfire-api/pyproject.toml:17-25
Conclusion
The logfire-api shim package is a critical component for the ecosystem, enabling "pluggable" observability. It provides a stable, zero-dependency interface for instrumentation, ensuring that the Pydantic Logfire ecosystem can expand through third-party libraries without imposing significant dependency overhead on end-users.