Logfire API Shim

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• pip install logfire-api Install `logfire-api`

Imports

• logfire

  import logfire_api as logfire

  Importing `logfire_api` as `logfire` is the recommended pattern to ensure compatibility with code written for the full `logfire` SDK.

Quickstart

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.

import os
import logfire_api as logfire

# Simulate Logfire being installed (or not) for demonstration
# In a real scenario, `logfire` would either be in your environment or not.
# For this example, we'll configure a mock for `logfire.configure` if `logfire` is not installed.
# In a production environment, users would `pip install logfire` and configure it.

try:
    import logfire as _actual_logfire
    logfire_installed = True
except ImportError:
    logfire_installed = False

if not logfire_installed:
    print("Logfire (the full SDK) is NOT installed. `logfire_api` will act as a no-op.")
else:
    print("Logfire (the full SDK) IS installed. `logfire_api` will delegate to it.")

# Configure Logfire (this would typically be done by the end-user of a library using logfire-api)
# For logfire-api, library authors usually *don't* call configure().
# The actual `logfire.configure()` would typically read LOGFIRE_TOKEN or other env vars.
if logfire_installed:
    # Only configure if the actual logfire SDK is present, otherwise it's a no-op by design
    os.environ['LOGFIRE_TOKEN'] = os.environ.get('LOGFIRE_TOKEN', 'your-logfire-write-token') # Replace with a real token in production
    logfire.configure(service_name='my-shimmed-app')
    print("Logfire (actual SDK) configured.")
else:
    print("Skipping logfire.configure() as the actual SDK is not installed.")

@logfire.instrument("my_function")
def my_function(name: str):
    logfire.info("Hello from {name}!", name=name)
    with logfire.span("inner_operation"):
        logfire.debug("Performing an inner operation.")
    return f"Processed {name}"

result = my_function("World")
print(f"Function returned: {result}")

# To see output in Logfire, ensure LOGFIRE_TOKEN is set and 'logfire' is installed.
# The above `logfire.configure()` will only run if `logfire` is installed.
# Otherwise, all logfire calls above will effectively do nothing.