{"id":1296,"library":"logfire-api","title":"Logfire API Shim","description":"The `logfire-api` library is a lightweight shim for the Logfire SDK, designed for packages that want to offer opt-in integration with Logfire without a hard dependency. It provides a clone of the `logfire` package's Python API that performs no-op operations if `logfire` is not installed, but makes real calls when `logfire` is present. This allows users of an integrated package to decide whether to install and configure Logfire for observability. The current version is 4.31.0, with frequent releases aligning with the main Logfire SDK.","status":"active","version":"4.31.0","language":"python","source_language":"en","source_url":"https://github.com/pydantic/logfire","tags":["observability","tracing","logging","metrics","shim","pydantic","opentelemetry"],"install":[{"cmd":"pip install logfire-api","lang":"bash","label":"Install `logfire-api`"}],"dependencies":[{"reason":"The `logfire-api` package functions as a no-op shim unless the main `logfire` SDK is installed, at which point it uses Logfire's functionality.","package":"logfire","optional":true}],"imports":[{"note":"Importing `logfire_api` as `logfire` is the recommended pattern to ensure compatibility with code written for the full `logfire` SDK.","symbol":"logfire","correct":"import logfire_api as logfire"}],"quickstart":{"code":"import os\nimport logfire_api as logfire\n\n# Simulate Logfire being installed (or not) for demonstration\n# In a real scenario, `logfire` would either be in your environment or not.\n# For this example, we'll configure a mock for `logfire.configure` if `logfire` is not installed.\n# In a production environment, users would `pip install logfire` and configure it.\n\ntry:\n    import logfire as _actual_logfire\n    logfire_installed = True\nexcept ImportError:\n    logfire_installed = False\n\nif not logfire_installed:\n    print(\"Logfire (the full SDK) is NOT installed. `logfire_api` will act as a no-op.\")\nelse:\n    print(\"Logfire (the full SDK) IS installed. `logfire_api` will delegate to it.\")\n\n# Configure Logfire (this would typically be done by the end-user of a library using logfire-api)\n# For logfire-api, library authors usually *don't* call configure().\n# The actual `logfire.configure()` would typically read LOGFIRE_TOKEN or other env vars.\nif logfire_installed:\n    # Only configure if the actual logfire SDK is present, otherwise it's a no-op by design\n    os.environ['LOGFIRE_TOKEN'] = os.environ.get('LOGFIRE_TOKEN', 'your-logfire-write-token') # Replace with a real token in production\n    logfire.configure(service_name='my-shimmed-app')\n    print(\"Logfire (actual SDK) configured.\")\nelse:\n    print(\"Skipping logfire.configure() as the actual SDK is not installed.\")\n\n@logfire.instrument(\"my_function\")\ndef my_function(name: str):\n    logfire.info(\"Hello from {name}!\", name=name)\n    with logfire.span(\"inner_operation\"):\n        logfire.debug(\"Performing an inner operation.\")\n    return f\"Processed {name}\"\n\nresult = my_function(\"World\")\nprint(f\"Function returned: {result}\")\n\n# To see output in Logfire, ensure LOGFIRE_TOKEN is set and 'logfire' is installed.\n# The above `logfire.configure()` will only run if `logfire` is installed.\n# Otherwise, all logfire calls above will effectively do nothing.","lang":"python","description":"This quickstart demonstrates how to use `logfire_api` as a shim. When `logfire` (the full SDK) is installed and configured by the end-user, `logfire_api` calls will be delegated to the actual Logfire SDK. If `logfire` is not installed, `logfire_api` methods will gracefully act as no-ops. Library authors typically `import logfire_api as logfire` and use its API, leaving the `logfire.configure()` call to their users. To send data to the Logfire platform, the `LOGFIRE_TOKEN` environment variable must be set."},"warnings":[{"fix":"Library authors using `logfire-api` should only `import logfire_api as logfire` and use its logging/instrumentation methods. The end-user is responsible for installing `pip install logfire` and calling `logfire.configure()` to enable and configure the actual Logfire SDK.","message":"The `logfire-api` package is a shim; its methods are no-ops if the full `logfire` SDK is not installed. Integrators should avoid calling `logfire_api.configure()` directly within their library, as configuration is meant for the end-user who decides whether to enable Logfire.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always consult the release notes for the main `logfire` SDK when updating `logfire`, as `logfire-api` will reflect these changes if `logfire` is present. Adapt your code to new API patterns as required by the `logfire` SDK.","message":"As `logfire-api` mirrors the API of the main `logfire` SDK, any breaking changes introduced in major versions of `logfire` (e.g., changes to method signatures, attribute names, or default behaviors) will implicitly affect users of `logfire-api` when they have the corresponding `logfire` version installed. For example, Logfire v0.51.0 introduced changes to system metrics collection and auto-tracing behavior.","severity":"breaking","affected_versions":"All versions of `logfire-api` in conjunction with `logfire` versions that introduce breaking changes."},{"fix":"Ensure end-users are aware they need to `pip install logfire` and configure it (e.g., by setting `LOGFIRE_TOKEN` and calling `logfire.configure()`) to enable data submission.","message":"For Logfire to send data to the Logfire platform, the `LOGFIRE_TOKEN` environment variable (or other configuration methods) must be correctly set, and the full `logfire` package must be installed and configured. Without proper configuration of the underlying `logfire` SDK, `logfire-api` calls will not result in any observable telemetry.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'4.31.0':85 'align':89 'allow':65 'api':2,7,44 'call':59 'clone':37 'configur':77 'current':82 'decid':72 'depend':33 'design':17 'frequent':87 'hard':32 'instal':55,75 'integr':27,69 'librari':8 'lightweight':11 'log':97 'logfir':1,6,15,29,40,52,61,78,93 'logfire-api':5 'main':92 'make':57 'metric':98 'no-op':47 'observ':80,95 'offer':23 'op':49 'opentelemetri':101 'oper':50 'opt':25 'opt-in':24 'packag':19,41,70 'perform':46 'present':63 'provid':35 'pydant':100 'python':43 'real':58 'releas':88 'sdk':16,94 'shim':3,12,99 'trace':96 'user':66 'version':83 'want':21 'whether':73 'without':30","created_at":"2026-04-08T04:58:03.243548+00:00","updated_at":"2026-04-16T16:21:19.640469+00:00","problems":[{"fix":"Install the full `logfire` SDK (`pip install logfire`) to ensure real `Logfire` objects are used, allowing proper type-based operations.","cause":"This error occurs when the `logfire` package is not installed, and `logfire-api` is providing `MagicMock` objects as no-ops. Subsequent code that expects real numeric values (like `float` for duration calculations) will fail when attempting operations with these mock objects.","error":"TypeError: '<' not supported between instances of 'MagicMock' and 'float'"},{"fix":"Install the `pytest` package (`pip install pytest`) to satisfy the missing dependency.","cause":"This error can occur if an older version of the `logfire` SDK (which `logfire-api` delegates to when installed) has an implicit dependency on `pytest` within certain submodules (e.g., `logfire.testing`), and `pytest` is not installed in the environment.","error":"ModuleNotFoundError: No module named 'pytest'"},{"fix":"Ensure compatibility between your `logfire` and `openai` library versions. You might need to upgrade or downgrade `openai` to a version known to work with your `logfire` SDK version, or check the `logfire` documentation for supported `openai` versions.","cause":"This specific `ModuleNotFoundError` arises when using `logfire.instrument_openai()` with an incompatible version of the `openai` library. The `logfire` SDK's OpenAI instrumentation expects a different internal structure or module path that is not present in the installed `openai` version.","error":"ModuleNotFoundError: No module named 'openai._legacy_response'"},{"fix":"Call `logfire.configure(token='your_project_token_here')` early in your application's lifecycle, or set the `LOGFIRE_TOKEN` environment variable with your valid Logfire project token. Authenticate via `logfire auth` if necessary.","cause":"This is a common warning message (rather than a Python exception) indicating that the `logfire.configure()` method has not been called with a valid project token, or the token is not correctly loaded from environment variables (e.g., `LOGFIRE_TOKEN`). This prevents telemetry data from being sent to the Logfire platform, even if `logfire` is installed and `logfire-api` is delegating calls.","error":"Logfire authentication configuration has not been set up."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.41.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://logfire.pydantic.dev","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/logfire-api/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}