Install & Compatibility
Where this runs
tested against v1.45.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.552s · 141MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 14.1s · import 1.132s · 138MB
141MB installed
● package 141MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize OpenLit for automatic instrumentation of an OpenAI LLM call. Ensure `openlit.init()` is called before any LLM client instantiation. By default, if `OTEL_EXPORTER_OTLP_ENDPOINT` is not set, traces will be printed to the console for development purposes. For production, configure the `OTEL_EXPORTER_OTLP_ENDPOINT` and authentication headers.
import os
import openlit
from openai import OpenAI
# Configure OpenLIT (either via env vars or direct arguments to init)
# For local development, omitting otlp_endpoint will print traces to console.
os.environ['OPENLIT_APPLICATION_NAME'] = os.environ.get('OPENLIT_APPLICATION_NAME', 'my-genai-app')
os.environ['OTEL_EXPORTER_OTLP_ENDPOINT'] = os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://127.0.0.1:4318')
os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY') # Replace with actual key or set env var
# Initialize OpenLIT for auto-instrumentation
# Make sure this call happens *before* importing/instantiating LLM clients
openlit.init()
# Example with OpenAI
client = OpenAI()
try:
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "What is OpenTelemetry?"}]
)
print(response.choices[0].message.content)
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure OPENAI_API_KEY is set and OTLP endpoint is reachable if not using console output.")
Debug
Known issues
gotchaOpenLit's auto-instrumentation requires `openlit.init()` to be called *before* importing or instantiating any AI library clients (e.g., OpenAI, LangChain). Clients initialized prior to `openlit.init()` will not be instrumented.fixPlace `import openlit` and `openlit.init()` at the very beginning of your application's entry point, before any other AI library imports or instantiations.
affects: All versions
breakingThe `application_name` parameter in `openlit.init()` has been deprecated. It is replaced by `service_name` for consistency with OpenTelemetry semantic conventions.fixReplace `application_name='my-app'` with `service_name='my-app'` in your `openlit.init()` calls. The corresponding environment variable is `OTEL_SERVICE_NAME`.
affects: Versions 1.40.0+
gotchaConfiguration parameters are prioritized: environment variables take precedence over CLI arguments, which take precedence over parameters passed directly to `openlit.init()`. Unexpected behavior might occur if conflicting configurations are present.fixBe mindful of where you set your configuration. For production, environment variables (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_SERVICE_NAME`) are generally recommended. For local development, explicit `init` parameters or console output might be preferred.
affects: All versions
gotchaIf `otlp_endpoint` is not provided in `openlit.init()` or via the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable, OpenLit will output traces directly to the console instead of sending them to an external observability backend. This is intended for development but can lead to missing data in production.fixAlways explicitly set `otlp_endpoint` in `openlit.init()` or the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable when deploying to a production or staging environment.
affects: All versions
gotchaLarge prompts, especially in RAG contexts, can lead to high memory usage due to large span events. This can impact performance and resource consumption.fixConsider setting `trace_content=False` in `openlit.init()` to disable capturing the full content of prompts and completions, or implement content truncation for very large inputs if detailed content tracing is still required.
affects: All versions
gotchaOpenLit, being an actively developed library in the rapidly evolving GenAI space, can introduce frequent updates, including changes to OpenTelemetry semantic conventions, which may require attention to maintain consistent observability data.fixMonitor release notes and changelogs for updates. Pinning versions in your `requirements.txt` is advisable to prevent unexpected behavior from automatic updates. Regularly test your instrumentation after upgrading.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opentelemetry.sdk._events'
This error typically occurs when the `opentelemetry-sdk` library, a core dependency for OpenLIT, is either missing, has an incompatible version installed, or the specific module `_events` is not found in the installed version.
fixEnsure you have `opentelemetry-sdk` installed and that its version is compatible with your OpenLIT installation. Often, reinstalling OpenLIT with its `all` extras, or explicitly installing `opentelemetry-sdk`, can resolve this: `pip install openlit[all]` or `pip install opentelemetry-sdk --upgrade`.
AttributeError: 'str' object has no attribute 'role'
This `AttributeError` frequently arises when OpenLIT's instrumentation, particularly for LLM providers like Google Gemini or OpenAI, expects a structured message object (e.g., with a 'role' attribute) but receives a plain string or an unexpected object type as part of the prompt content.
fixEnsure that the input format to your LLM client calls adheres to the expected structured message format, especially when dealing with multi-modal inputs, tool calls, or advanced prompting techniques. Consult the specific LLM provider's SDK documentation and OpenLIT's compatibility guide for the correct input structures.
openlit spans not appearing
Telemetry data (spans, traces) does not appear because `openlit.init()` was not called at the correct time, specifically *before* the AI library clients (e.g., OpenAI, LangChain, LlamaIndex) were imported or instantiated. OpenLIT needs to patch these libraries at initialization time to enable instrumentation.
fixMove `import openlit` and `openlit.init()` to the very top of your application's entry point, before any other imports or instantiations of the AI libraries you intend to instrument.
Failed to export batch code: 401, reason: {"message":"Invalid credentials. Confirm that you've configured the correct host."}
This export error indicates an authentication failure when OpenLIT tries to send telemetry data to your configured OpenTelemetry Protocol (OTLP) endpoint. This is usually due to incorrect API keys, tokens, or an invalid OTLP endpoint URL.
fixVerify that your `OPENLIT_OTLP_ENDPOINT` and `OPENLIT_OTLP_HEADERS` environment variables (or the arguments passed to `openlit.init()`) are correctly configured with the precise OTLP endpoint URL and a valid API key or authorization token for your chosen observability backend (e.g., Langfuse, Middleware, New Relic).
Upgrade
Version history
1.45.0latest on PyPI · released Aug 3, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer, but less than 4.0.0.
nvidia-ml-pyoptionalRequired for GPU monitoring functionality when using the 'gpu' extra.