- Understand automatic input/output capture.
- Explicitly set inputs and outputs for traces and spans.
- Dynamically update this data on active traces/spans.
- Handle different data formats, especially for chat messages.
Automatic Input and Output Capture
By default, when you usetracer.withActiveSpan()
or tracer.startActiveSpan()
, the SDK attempts to automatically capture:
- Inputs: The arguments passed to the function within the span context.
- Outputs: The value returned by the function within the span context.
Refer to the API reference for
getLangWatchTracer()
and LangWatchTracer
for more details on data capture configuration.Explicitly Setting Inputs and Outputs
You often need more control over what data is recorded. You can explicitly set inputs and outputs using thesetInput()
and setOutput()
methods on span objects.
This is useful for:
- Capturing only specific parts of complex objects.
- Formatting data in a more readable or structured way (e.g., as a list of
ChatMessage
objects). - Redacting sensitive information before it’s sent to LangWatch.
- Providing inputs/outputs when automatic capture is disabled.
At Span Creation
When usingtracer.withActiveSpan()
or tracer.startActiveSpan()
, you can set inputs and outputs directly on the span object.
Dynamically Updating Inputs and Outputs
You can modify the input or output of an active span using itssetInput()
and setOutput()
methods. This is particularly useful when the input/output data is determined or refined during the operation.
The
setInput()
and setOutput()
methods on LangWatchSpan
objects are versatile and support multiple data types. See the reference for LangWatchSpan
methods.Handling Different Data Formats
LangWatch can store various types of input and output data:- Strings: Simple text using
"text"
type. - Objects: Automatically serialized as JSON using
"json"
type. This is useful for structured data. - Chat Messages: Arrays of chat message objects using
"chat_messages"
type. This ensures proper display and analysis in the LangWatch UI. - Raw Data: Any data type using
"raw"
type. - Lists: Arrays of structured data using
"list"
type.
Capturing Chat Messages
For LLM interactions, structure your inputs and outputs as chat messages using the"chat_messages"
type.
For the detailed structure of chat messages and other related types, please refer to the Core Data Types section in the API Reference.
Data Capture Configuration
You can control automatic data capture at different levels:Global Configuration
Set the default data capture behavior for your entire application:Use Cases and Best Practices
- Redacting Sensitive Information: If your function arguments or return values contain sensitive data (PII, API keys), disable automatic capture and explicitly set sanitized versions using
setInput()
andsetOutput()
. - Mapping Complex Objects: If your inputs/outputs are complex JavaScript objects, map them to a simplified object or string representation for clearer display in LangWatch.
- Improving Readability: For long text inputs/outputs (e.g., full documents), consider capturing a summary or metadata instead of the entire content to reduce noise, unless the full content is essential for debugging or evaluating.
- Error Handling: Use try-catch blocks within spans to capture error information and set appropriate outputs.
- Clearing Captured Data: You can set
input
oroutput
tonull
or an empty object via thesetInput()
orsetOutput()
methods to remove previously captured data if it’s no longer relevant.
Error Handling Example
Conclusion
Controlling how inputs and outputs are captured in LangWatch allows you to tailor the observability data to your specific needs. By using data capture configuration, explicitsetInput()
and setOutput()
methods, and appropriate data formatting (especially "chat_messages"
for conversations), you can ensure that your traces provide clear, relevant, and secure insights into your LLM application’s behavior.