Python SDK API Reference

Your LangWatch API key. It’s recommended to set this via an environment variable (e.g., LANGWATCH_API_KEY) and retrieve it using os.getenv("LANGWATCH_API_KEY").

The URL of the LangWatch backend where traces will be sent. Defaults to the LangWatch Cloud service. For self-hosted instances, you’ll need to provide this.

A BaseAttributes object allowing you to set default tags and properties that will be attached to all traces and spans. See BaseAttributes type for more details.

An OpenTelemetry TracerProvider instance. If you have an existing OpenTelemetry setup, you can pass your TracerProvider here. LangWatch will add its exporter to this provider. If not provided, LangWatch will configure its own.

A sequence of OpenTelemetry instrumentor instances. LangWatch can automatically apply these instrumentors. (Note: Specific instrumentor types might need to be defined or linked here).

A list of SpanProcessingExcludeRule objects. These rules allow you to filter out specific spans from being exported to LangWatch, based on span name or attributes. See SpanProcessingExcludeRule for details.

If True, enables debug logging for the LangWatch client, providing more verbose output about its operations.

An instance of the LangWatch Client.

The name for the root span of this trace. If used as a decorator and not provided, it defaults to the name of the decorated function. For context manager usage, a name like “LangWatch Trace” might be used if not specified.

(Deprecated) A specific ID to assign to this trace. If not provided, a new UUID will be generated. It’s generally recommended to let LangWatch auto-generate trace IDs. This will be mapped to deprecated.trace_id in metadata.

A dictionary of metadata to attach to the entire trace. This can include things like user IDs, session IDs, or any other contextual information relevant to the whole operation. TraceMetadata is typically Dict[str, Any].

If you have a known expected output for this trace (e.g., for testing or evaluation), you can provide it here.

Overrides the global API key for this specific trace. Useful if you need to direct traces to different projects or accounts dynamically.

If True, this trace (and its spans) will be processed but not sent to the LangWatch backend. This can be useful for local debugging or conditional tracing.

The maximum length for string values captured in inputs, outputs, and metadata. Longer strings will be truncated.

If True, a root span will not be automatically created for this trace. This is an advanced option, typically used if you intend to manage the root span’s lifecycle manually or if the trace is purely a logical grouping without its own primary operation.

The LangWatchTrace instance. You can use this object to call methods like current_trace.add_evaluation().

Updates attributes of the trace or its root span. This method can take many of the same parameters as the langwatch.trace() decorator/context manager itself, such as metadata, expected_output, or any of the root span parameters like name, input, output, metrics, etc.

with langwatch.trace(name="Initial Trace") as current_trace:
    # ... some operations ...
    current_trace.update(metadata={"step": "one_complete"})
    # ... more operations ...
    root_span_output = "Final output of root operation"
    current_trace.update(output=root_span_output, metrics={"total_items": 10})

Adds an Evaluation object directly to the trace (or a specified span within it).

from langwatch.domain import Evaluation, EvaluationTimestamps

with langwatch.trace(name="MyEvaluatedProcess") as current_trace:
    # ... operation ...
    eval_result = Evaluation(
        name="Accuracy Check",
        status="processed",
        passed=True,
        score=0.95,
        details="All checks passed.",
        timestamps=EvaluationTimestamps(started_at=..., finished_at=...)
    )
    current_trace.add_evaluation(**eval_result) # Pass fields as keyword arguments

(Refer to Evaluation type in Core Data Types and langwatch.evaluations module for more details on parameters.)

Triggers a remote evaluation for this trace using a pre-configured evaluator slug on the LangWatch platform.

with langwatch.trace(name="ProcessWithRemoteEval") as current_trace:
    output_to_evaluate = "Some generated text."
    current_trace.evaluate(
        slug="sentiment-analyzer", 
        output=output_to_evaluate,
        as_guardrail=False
    )

Parameters include slug, name, input, output, expected_output, contexts, conversation, settings, as_guardrail, data. Returns: Result of the evaluation call.

An asynchronous version of evaluate.

Instruments an OpenAI client instance (e.g., openai.OpenAI()) to automatically create spans for any OpenAI API calls made using that client within the current trace.

import openai
# client = openai.OpenAI() # or AzureOpenAI, etc.

with langwatch.trace(name="OpenAICallsDemo") as current_trace:
    # current_trace.autotrack_openai_calls(client)
    # response = client.chat.completions.create(...)
    # The above call will now be automatically traced as a span.
    pass

Takes the OpenAI client instance as an argument.

Enables automatic tracing for DSPy operations within the current trace. Requires DSPy to be installed and properly configured.

with langwatch.trace(name="DSPyPipeline") as current_trace:
    # current_trace.autotrack_dspy()
    # ... your DSPy calls ...
    pass

Returns a LangChain callback handler (LangChainTracer) associated with the current trace. This handler can be passed to LangChain runs to automatically trace LangChain operations.

# from langchain_core.llms import FakeLLM (or any LangChain LLM)
# from langchain.chains import LLMChain

with langwatch.trace(name="LangChainFlow") as current_trace:
    # handler = current_trace.get_langchain_callback()
    # llm = FakeLLM()
    # chain = LLMChain(llm=llm, prompt=...)
    # chain.run("some input", callbacks=[handler])
    pass

Returns: LangChainTracer instance.

(Potentially) Generates a shareable link or identifier for this trace. The exact behavior might depend on backend support and configuration. Returns: A string, possibly a URL or an ID.

(Potentially) Revokes sharing for this trace if it was previously shared.

The name for the span. If used as a decorator and not provided, it defaults to the name of the decorated function. For context manager usage, a default name like “LangWatch Span” might be used if not specified.

The semantic type of the span, which helps categorize the operation. Common types include 'llm', 'rag', 'agent', 'tool', 'embedding', or a generic 'span'. SpanType is typically a string literal from langwatch.domain.SpanTypes.

(Deprecated) A specific ID to assign to this span. It’s generally recommended to let LangWatch auto-generate span IDs. This will be mapped to deprecated.span_id in the span’s attributes.

Explicitly sets the parent for this span. If not provided, the span will be nested under the currently active LangWatchSpan or OpenTelemetry span.

If True (and used as a decorator), automatically captures the arguments of the decorated function as the span’s input.

If True (and used as a decorator), automatically captures the return value of the decorated function as the span’s output.

Explicitly sets the input for this span. SpanInputType can be a dictionary, a string, or a list of ChatMessage objects. This overrides automatic input capture.

Explicitly sets the output for this span. SpanInputType has the same flexibility as for input. This overrides automatic output capture.

Records an error for this span. If an exception occurs within a decorated function or context manager, it’s often automatically recorded.

A SpanTimestamps object to explicitly set the start_time and end_time for the span. Useful for instrumenting operations where the duration is known or externally managed.

Relevant contextual information for this span, especially for RAG operations. ContextsType can be a list of RAGChunk objects or a list of strings.

The name or identifier of the model used in this operation (e.g., 'gpt-4o-mini', 'text-embedding-ada-002').

A dictionary or SpanParams object containing parameters relevant to the operation (e.g., temperature for an LLM call, k for a vector search).

A SpanMetrics object or dictionary to record quantitative measurements for this span, such as token counts (input_tokens, output_tokens), cost, or other custom metrics.

A list of Evaluation objects to directly associate with this span.

If True, suppresses the warning that is normally emitted if a span is created without an active parent trace.

The OpenTelemetry SpanKind (e.g., INTERNAL, CLIENT, SERVER, PRODUCER, CONSUMER).

An OpenTelemetry Context object to use for creating the span.

Additional custom attributes (key-value pairs) to attach to the span.

A list of OpenTelemetry Link objects to associate with this span.

An explicit start time for the span (in nanoseconds since epoch).

Whether OpenTelemetry should automatically record exceptions for this span.

Whether OpenTelemetry should automatically set the span status to error when an exception is recorded.

The LangWatchSpan instance. You can use this object to call methods like current_span.update() or current_span.add_evaluation().

Updates attributes of the span. This is the primary method for adding or changing information on an active span. It accepts most of the same parameters as the @langwatch.span() decorator itself, such as name, type, input, output, error, timestamps, contexts, model, params, metrics, and arbitrary key-value pairs for custom attributes.

with langwatch.span(name="MySpan", type="tool") as current_span:
    # ... some operation ...
    current_span.update(output={"result": "success"}, metrics={"items_processed": 5})
    # Add a custom attribute
    current_span.update(custom_tool_version="1.2.3")

Adds an Evaluation object directly to this span.

from langwatch.domain import Evaluation

with langwatch.span(name="SubOperation") as current_span:
    # ... operation ...
    eval_data = {
        "name": "Correctness Check", 
        "status": "processed", 
        "passed": False, 
        "score": 0.2, 
        "label": "Incorrect"
    } # Example, more fields available
    current_span.add_evaluation(**eval_data)

(Refer to Evaluation type in Core Data Types and langwatch.evaluations module for more details on parameters.)

Triggers a remote evaluation for this span using a pre-configured evaluator slug on the LangWatch platform.

with langwatch.span(name="LLM Generation", type="llm") as llm_span:
    llm_output = "Some text generated by an LLM."
    llm_span.update(output=llm_output)
    llm_span.evaluate(slug="toxicity-check", output=llm_output, as_guardrail=True)

Parameters include slug, name, input, output, expected_output, contexts, conversation, settings, as_guardrail, data. Returns: Result of the evaluation call.

An asynchronous version of evaluate for spans.

Explicitly ends the span. If you provide arguments (like output, metrics, etc.), it will call update() with those arguments before ending. Usually not needed when using the span as a context manager, as __exit__ handles this.

# Manual span management example
# current_span = langwatch.span(name="ManualSpan").__enter__() # Start span manually
# try:
#     # ... operations ...
#     result = "some result"
#     current_span.end(output=result) # Update and end
# except Exception as e:
#     current_span.end(error=e) # Record error and end
#     raise

If True, suppresses the warning that is normally emitted if this function is called when no LangWatch trace is currently in context.

The current LangWatchTrace object. If no trace is active and suppress_warning is False, a warning is issued and a new (detached) LangWatchTrace instance might be returned.

The current LangWatchSpan object. This could be a span initiated by @langwatch.span, the root span of a @langwatch.trace, or a LangWatchSpan wrapping an existing OpenTelemetry span if no LangWatch span is directly in context.

The field of the span to match against. Currently, only "span_name" is supported.

The value to match for the specified field_name.

The operation to use for matching (e.g., "exact_match", "starts_with").

The role of the message sender. ChatRole is a Literal: "system", "user", "assistant", "function", "tool", "guardrail", "evaluation", "unknown".

The textual content of the message.

For assistant messages that involve a function call (legacy OpenAI format).

For assistant messages that involve tool calls (current OpenAI format).

For messages that are responses from a tool, this is the ID of the tool call that this message is a response to.

The name of the function whose result is in the content (if role is "function"), or the name of the tool/participant (if role is "tool").

An identifier for the source document of this chunk.

An identifier for this specific chunk within the document.

The actual content of the RAG chunk. Can be a simple string or a more complex structured object.

Timestamp when the span started (nanoseconds since epoch).

For LLM operations, timestamp when the first token was received (nanoseconds since epoch).

Timestamp when the span finished (nanoseconds since epoch).

Number of tokens in the input/prompt to an LLM.

Number of tokens in the output/completion from an LLM.

Estimated or actual monetary cost of the operation (e.g., LLM API call cost).

Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim.

Modify the likelihood of specified tokens appearing in the completion. Accepts a dictionary mapping token IDs (or tokens, depending on the model) to a bias value from -100 to 100.

Whether to return log probabilities of the output tokens.

An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with log probability. logprobs must be True if this is used.

The maximum number of tokens to generate in the completion.

How many completions to generate for each prompt.

Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics.

If specified, the system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.

Up to 4 sequences where the API will stop generating further tokens.

If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only server-sent events as they become available.

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.

A list of tools the model may call. Currently, only functions are supported as a tool.

Controls which (if any) tool is called by the model. none means the model will not call any tool. auto means the model can pick between generating a message or calling a tool.

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.