{"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":"en","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,"last_verified":"2026-04-08T00:00:00.000Z","next_check":"2026-07-07T00:00:00.000Z"}