LangWatch Python SDK

0.18.0 · active · verified Thu Apr 16

LangWatch is a Python SDK for monitoring, evaluating, and testing LLM-powered applications and AI agents. It provides end-to-end observability by capturing traces and spans for LLM calls, RAG retrievals, and other pipeline steps, helping developers debug, prevent regressions, and optimize their AI systems. The current version is 0.18.0, and the library undergoes active development with regular releases.

Common errors

```
No traces appearing in LangWatch dashboard.
```
cause The `LANGWATCH_API_KEY` environment variable is likely not set, or the API key passed to `langwatch.setup()` is incorrect or missing.

fix Set your LangWatch API key as an environment variable: `export LANGWATCH_API_KEY="your_api_key"` (Linux/macOS) or `$Env:LANGWATCH_API_KEY="your_api_key"` (PowerShell), or pass it directly: `langwatch.setup(api_key="your_api_key")`.
```
ImportError: cannot import name 'OpenAIInstrumentor' from 'langwatch'
```
cause Specific modules like instrumentors are located within subpackages, not directly under the top-level `langwatch` package.

fix Import the symbol from its correct submodule path, e.g., `from langwatch.instrumentors import OpenAIInstrumentor`.
```
Error: Trace not found for current context.
```
cause Attempting to call `langwatch.get_current_trace().error()` or similar trace-specific methods outside of an active trace context (i.e., not within a `@langwatch.trace()` or `@langwatch.span()` decorated function/context block).

fix Ensure all operations that interact with the current trace are performed within a function or block that is decorated with `@langwatch.trace()` or `@langwatch.span()`.

Warnings

gotcha Traces might not appear in the LangWatch dashboard if the `LANGWATCH_API_KEY` environment variable is not set or passed explicitly during `langwatch.setup()`.
Fix: Set `LANGWATCH_API_KEY=your_api_key` in your environment variables or provide it as `api_key='your_api_key'` to `langwatch.setup()`.
gotcha In applications that exit quickly (e.g., short scripts), traces might not be fully sent to the LangWatch backend before termination.
Fix: Ensure `await langwatch.shutdown()` is called before your application exits to flush any pending traces.
gotcha LangWatch uses OpenTelemetry under the hood. Incorrect or conflicting OpenTelemetry configurations can interfere with LangWatch's tracing.
Fix: Consult the LangWatch documentation on OpenTelemetry integration if you have an existing OpenTelemetry setup. Ensure compatible versions and proper exporter configuration.
gotcha The `langwatch` Python SDK is distinct from the `langwatch-scenario` library, which focuses on agent simulations.
Fix: Install `langwatch-scenario` separately if you intend to use the simulation framework (`pip install langwatch-scenario`). Be aware that their functionalities are complementary but distinct.

Install

pip install langwatch Install latest version

Imports

langwatch
```
import langwatch
```
setup
```
langwatch.setup()
```
Initializes the LangWatch client.
trace
```
@langwatch.trace()
```
Decorator to capture an end-to-end operation as a trace.
span
```
@langwatch.span()
```
Decorator to instrument specific parts of a pipeline within a trace.
OpenAIInstrumentor
wrong:
```
from langwatch import OpenAIInstrumentor
```
correct:
```
from langwatch.instrumentors import OpenAIInstrumentor
```
Instrumentors are typically found in the `langwatch.instrumentors` submodule.
LangChainTracer
wrong:
```
from langwatch import LangChainTracer
```
correct:
```
import langwatch.langchain
langWatchCallback = langwatch.langchain.LangChainTracer()
```
LangChain integration is via `langwatch.langchain` submodule and uses a context manager or callback.

Quickstart

This quickstart demonstrates how to initialize LangWatch, enable automatic OpenAI instrumentation, and trace an asynchronous function that interacts with the OpenAI API. It highlights the use of `langwatch.setup()` and the `@langwatch.trace()` decorator, along with handling the `LANGWATCH_API_KEY`.

import os
import langwatch
from langwatch.instrumentors import OpenAIInstrumentor
from openai import OpenAI

# Ensure your API key is set as an environment variable or pass it directly
# os.environ["LANGWATCH_API_KEY"] = "YOUR_LANGWATCH_API_KEY"
api_key = os.environ.get("LANGWATCH_API_KEY", "")

if not api_key:
    print("Warning: LANGWATCH_API_KEY environment variable not set. Traces will not be sent.")
    # For demonstration, we'll proceed but you should set your key.
    # In a real application, you might raise an error or configure LangWatch to only log locally.

# Initialize LangWatch early in your application
# Automatically instruments OpenAI calls within the decorated functions
langwatch.setup(
    api_key=api_key,
    instrumentors=[OpenAIInstrumentor()]
)

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY", "")) # Assume OpenAI API key is also set

@langwatch.trace(name="UserInteraction")
async def handle_user_query(query: str):
    print(f"Processing query: {query}")
    try:
        response = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[
                {"role": "system", "content": "You are a helpful assistant."}, 
                {"role": "user", "content": query}
            ]
        )
        result = response.choices[0].message.content
        print(f"Assistant's response: {result}")
        return result
    except Exception as e:
        langwatch.get_current_trace().error(str(e)) # Record error if something goes wrong
        print(f"An error occurred: {e}")
        raise

async def main():
    await handle_user_query("Tell me a fun fact about Python.")
    # Ensure traces are flushed before the application exits
    await langwatch.shutdown()

import asyncio
asyncio.run(main())

view raw JSON →