Registry / observability / openinference-instrumentation-langchain

openinference-instrumentation-langchain

JSON →
library0.1.73pypypi✓ verified 22d ago

The `openinference-instrumentation-langchain` library provides automatic instrumentation for LangChain applications, enabling detailed observability for AI workflows. It implements OpenInference semantic conventions on top of OpenTelemetry, standardizing traces for LLM calls, agent reasoning, tool invocations, and retrieval operations. This allows for seamless integration with any OpenTelemetry-compatible backend, such as Arize Phoenix, to visualize and analyze your AI application's performance. The library is actively maintained, with a current version of 0.1.62, and receives regular updates.

pip install openinference-instrumentation-langchain langchain langchain-openai opentelemetry-sdk opentelemetry-exporter-otlp arize-phoenix
INSTALL
IMPORT
SIG · OPENINFERENCE-INST
O
openinference-instrumentation-langchain
observabilitypythonv0.1.73
Install
50.7s avg
Import
674ms
Disk
957MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.73 · 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
musl
glibc
py 3.10
✕ build_error
✓ 55.85s
py 3.11
✕ build_error
✓ 54.85s
py 3.12
✕ build_error
✓ 46.6s
py 3.13
✕ build_error
✓ 45.65s
py 3.9
✕ build_error
✕ build_error
957MB installed
● package 957MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LangChainInstrumentor
from openinference.instrumentation.langchain import LangChainInstrumentor
The primary class to enable LangChain auto-instrumentation.

This quickstart demonstrates how to instrument a simple LangChain agent with `openinference-instrumentation-langchain`. It sets up a basic OpenTelemetry `TracerProvider` to export traces to a local OTLP collector (like Arize Phoenix, typically running on `http://localhost:6006/v1/traces`). The `LangChainInstrumentor().instrument()` call enables automatic tracing of LangChain operations. An `OPENAI_API_KEY` environment variable is required to run the example successfully.

import os from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import SimpleSpanProcessor from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from openinference.instrumentation.langchain import LangChainInstrumentor from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from langchain_core.tools import tool from langchain_openai import ChatOpenAI # Set up OpenTelemetry resource = Resource.create({"service.name": "my-langchain-app"}) tracer_provider = TracerProvider(resource=resource) span_exporter = OTLPSpanExporter(endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:6006/v1/traces')) tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter)) trace.set_tracer_provider(tracer_provider) # Instrument LangChain LangChainInstrumentor().instrument() # Ensure OpenAI API key is set for the example os.environ["OPENAI_API_KEY"] = os.environ.get('OPENAI_API_KEY', 'sk-YOUR_OPENAI_KEY_HERE') # Replace with actual key or ensure env var is set @tool def multiply(a: int, b: int) -> int: """Multiply two numbers together.""" return a * b @tool def add(a: int, b: int) -> int: """Add two numbers together.""" return a + b llm = ChatOpenAI(temperature=0, model="gpt-4o-mini") tools = [multiply, add] prompt = ChatPromptTemplate.from_messages([ ("system", "You are a helpful assistant."), ("human", "{input}"), ]) agent = create_tool_calling_agent(llm, tools, prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) if __name__ == "__main__": print("Running agent...") response = agent_executor.invoke({"input": "What is 123 multiplied by 456?"}) print(f"Agent Response: {response['output']}") print("Traces should be visible in your configured OpenTelemetry collector (e.g., Phoenix at http://localhost:6006).")
Debug
Known issues
gotchaDirect `model.invoke()` calls in LangChain may result in unstructured trace output in some UI backends. While traces are captured, the detailed message-by-message history might not be rendered in the expected structured format, appearing as raw JSON.
fix
This is a backend display issue or a limitation in how certain `invoke` patterns are interpreted. Using higher-level LangChain constructs like agents often yields better-formatted traces. Verify your observability backend's display capabilities for raw OpenTelemetry spans.
affects: All versions
gotchaWhen using `openinference-instrumentation-langchain` with `langgraph_swarm`, an `AssertionError` can occur due to the tracer expecting message IDs to be lists but receiving `None` instead. This can disrupt logging, though trace data might still be sent.
fix
Monitor for updates to `openinference-instrumentation-langchain` or `langgraph_swarm` that address this. If encountering this, check the official GitHub issues for workarounds or specific version recommendations. The issue has been observed with Python 3.13.
affects: Potentially all versions with `langgraph_swarm` integration.
gotchaComplex asynchronous flows in LangChain applications may prevent OpenTelemetry's context from propagating automatically across async boundaries, leading to fragmented or orphaned spans. This is a common challenge with OpenTelemetry in highly concurrent Python applications.
fix
Manually manage context propagation in complex async scenarios using `context.attach()` and `context.detach()` or by passing the current `Context` explicitly. Consider using `contextvars` for async-aware context management if not already handled by OpenTelemetry's integration with your async framework.
affects: All versions, due to nature of async context propagation in OpenTelemetry.
Upgrade
Version history
0.1.73latest on PyPI · released Aug 28, 2026
Audit
Dependencies
pythonrequiredRequires Python versions >=3.10, <3.15.
langchainrequiredCore dependency for instrumenting LangChain 1.x applications.
langchain-classicoptionalCore dependency for instrumenting legacy LangChain 0.x applications.
opentelemetry-sdkrequiredRequired for OpenTelemetry tracing functionality.
opentelemetry-exporter-otlprequiredRequired for exporting OpenTelemetry traces.
arize-phoenixoptionalRecommended for local visualization and analysis of traces.
Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
2
Amazon
1
Resources