Initializes the LangWatch client, enabling data collection and tracing for your LLM application. This is typically the first function you’ll call when integrating LangWatch.
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.
This is the primary way to define the boundaries of a request or a significant operation in your application. It can be used as a decorator around a function or as a context manager.When used, it creates a new trace and a root span for that trace. Any @langwatch.span() or other instrumented calls made within the decorated function or context manager will be nested under this root span.
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 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.
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.
Show Root Span Parameters
The following parameters are used to configure the root span that is automatically created when the trace starts. Refer to @langwatch.span() documentation for more details on these, as they behave similarly.
When langwatch.trace() is used as a context manager, it yields a LangWatchTrace object. This object has several methods to interact with the current trace:
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.
Copy
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})
Triggers a remote evaluation for this trace using a pre-configured evaluator slug on the LangWatch platform.
Copy
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.
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.
Copy
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
Returns a LangChain callback handler (LangChainTracer) associated with the current trace. This handler can be passed to LangChain runs to automatically trace LangChain operations.
Copy
# from langchain_core.llms import FakeLLM (or any LangChain LLM)# from langchain.chains import LLMChainwith 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
(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.
Use this to instrument specific operations or blocks of code within a trace. Spans can be nested to create a hierarchical view of your application’s execution flow.It can be used as a decorator around a function or as a context manager.
Copy
import langwatchlangwatch.setup()@langwatch.trace(name="MainProcess")def main_process(): do_first_step("data for step 1") do_second_step("data for step 2")@langwatch.span(name="StepOne", type="tool")def do_first_step(data: str): # langwatch.get_current_span().set_attributes({"custom_info": "info1"}) return f"Step 1 processed: {data}"@langwatch.span() # Name will be 'do_second_step', type will be 'span'def do_second_step(data: str): # langwatch.get_current_span().update(metrics={"items_processed": 10}) return f"Step 2 processed: {data}"main_process()
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 input for this span. SpanInputType can be a dictionary, a string, or a list of ChatMessage objects. This overrides automatic input capture.
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.
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.
If True, suppresses the warning that is normally emitted if a span is created without an active parent trace.
OpenTelemetry Parameters:
These parameters are passed directly to the underlying OpenTelemetry span creation. Refer to OpenTelemetry documentation for more details.
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.
Copy
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")
Triggers a remote evaluation for this span using a pre-configured evaluator slug on the LangWatch platform.
Copy
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.
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.
Copy
# 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
OpenTelemetry Span Methods:The LangWatchSpan object also directly exposes standard OpenTelemetry trace.Span API methods for more advanced use cases or direct OTel interop. These include:
record_error(exception): Records an exception against the span.
add_event(name, attributes): Adds a timed event to the span.
set_status(status_code, description): Sets the OTel status of the span (e.g., StatusCode.ERROR).
set_attributes(attributes_dict): Sets multiple OTel attributes at once.
update_name(new_name): Changes the name of the span.
is_recording(): Returns True if the span is currently recording information.
get_span_context(): Returns the SpanContext of the underlying OTel span.
Refer to the OpenTelemetry Python documentation for details on these methods.
Copy
from opentelemetry.trace import Status, StatusCodewith langwatch.span(name="MyDetailedSpan") as current_span: current_span.add_event("Checkpoint 1", {"detail": "Reached stage A"}) # ... some work ... try: # risky_operation() pass except Exception as e: current_span.record_error(e) current_span.set_status(Status(StatusCode.ERROR, description="Risky op failed")) current_span.set_attributes({"otel_attribute": "value"})
These functions allow you to access the currently active LangWatch trace or span from anywhere in your code, provided that a trace/span has been started (e.g., via @langwatch.trace or @langwatch.span).
Retrieves the currently active LangWatchTrace object.This is useful if you need to interact with the trace object directly, for example, to add trace-level metadata or evaluations from a helper function called within an active trace.
Copy
import langwatchlangwatch.setup()def some_utility_function(detail: str): current_trace = langwatch.get_current_trace() if current_trace: current_trace.update(metadata={"utility_info": detail})@langwatch.trace(name="MainOperation")def main_operation(): # ... some work ... some_utility_function("Processed step A") # ... more work ...main_operation()
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.
Retrieves the currently active LangWatchSpan object.This allows you to get a reference to the current span to update its attributes, add events, or record information specific to that span from nested function calls.
If no LangWatch-specific span is in context, it will attempt to wrap the current OpenTelemetry span.
Copy
import langwatchlangwatch.setup()def enrich_span_data(key: str, value: any): current_span = langwatch.get_current_span() if current_span: current_span.update(**{key: value}) # Or using the older set_attributes for OpenTelemetry compatible attributes # current_span.set_attributes({key: value})@langwatch.trace(name="UserFlow")def user_flow(): with langwatch.span(name="Step1") as span1: # ... step 1 logic ... enrich_span_data("step1_result", "success") with langwatch.span(name="Step2") as span2: # ... step 2 logic ... enrich_span_data("step2_details", {"info": "more data"})user_flow()
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.
This section describes common data structures used throughout the LangWatch SDK, particularly as parameters to functions like langwatch.setup(), @langwatch.trace(), and @langwatch.span(), or as part of the data captured.
This is a flexible type used for the input and output fields of spans. It’s a Union that can take several forms to represent different kinds of data. LangWatch will store it as a typed value.
Common forms include:
TypedValueText: For simple string inputs/outputs. {"type": "text", "value": "your string"}
TypedValueChatMessages: For conversational inputs/outputs. {"type": "chat_messages", "value": [ChatMessage, ...]}
TypedValueJson: For arbitrary JSON-serializable data. {"type": "json", "value": {"key": "value"}}
TypedValueRaw: For data that should be stored as a raw string, escaping any special interpretation. {"type": "raw", "value": "<xml>data</xml>"}
TypedValueList: For a list of SpanInputOutput objects. {"type": "list", "value": [SpanInputOutput, ...]}
When providing input or output to @langwatch.span() or span.update(), you can often provide the raw Python object (e.g., a string, a list of ChatMessage dicts, a dictionary for JSON), and the SDK will attempt to serialize it correctly. For more control, you can construct the TypedValue dictionaries yourself.
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.
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.
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.
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.
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.