Trace Query Syntax

Overview

LangSmith provides a powerful query language for filtering and searching traces. This syntax is used throughout the platform for filtering traces in the UI, exporting data, and programmatically querying your trace data.

Basic Syntax

The query language supports filtering on various trace attributes using a simple key-value format:

key:value

Examples

run_type:llm
status:error
name:chat_completion

Filter Arguments

Run Type Filters

Filter traces by the type of run:

run_type:llm
run_type:chain
run_type:tool
run_type:retriever
run_type:embedding

Status Filters

Filter by run status:

status:success
status:error
status:in_progress

Name Filters

Filter by run name:

name:chat_completion
name:summarize_document
name:search_database

Time Filters

Filter by timestamp ranges:

start_time:2024-01-01T00:00:00Z
end_time:2024-01-31T23:59:59Z

Metadata Filters

Filter by custom metadata:

metadata.environment:production
metadata.version:v1.2.3
metadata.user_id:12345

Tag Filters

Filter by tags:

tags:production
tags:experiment
tags:debug

Filter Query Language

For more complex queries, you can use the advanced filter query language with logical operators and nested conditions.

Logical Operators

• AND: All conditions must be true
• OR: At least one condition must be true
• NOT: Negate a condition

Examples

run_type:llm AND status:error
run_type:llm OR run_type:chain
NOT status:error

Nested Conditions

Use parentheses for complex logical groupings:

(run_type:llm OR run_type:chain) AND status:error
metadata.environment:production AND (tags:critical OR tags:urgent)

Comparison Operators

For numeric and date fields, you can use comparison operators:

latency_ms:>1000
token_count:>=100
start_time:>2024-01-01T00:00:00Z

Available operators:

• =: Equal to
• !=: Not equal to
• >: Greater than
• >=: Greater than or equal to
• <: Less than
• <=: Less than or equal to

String Matching

For string fields, you can use pattern matching:

name:contains:chat
name:starts_with:summarize
name:ends_with:completion

Available string operators:

• contains: Contains substring
• starts_with: Starts with prefix
• ends_with: Ends with suffix
• regex: Regular expression match

Advanced Examples

Complex Filtering

# Find all LLM runs with errors in production
run_type:llm AND status:error AND metadata.environment:production

# Find runs with high latency
latency_ms:>5000 AND run_type:chain

# Find runs from specific time period with certain tags
start_time:>2024-01-01T00:00:00Z AND start_time:<2024-01-31T23:59:59Z AND tags:experiment

# Find runs with specific metadata patterns
metadata.user_id:regex:^123.* AND metadata.version:starts_with:v1

Performance Considerations

• Use specific filters to reduce query time
• Avoid overly broad date ranges
• Consider using tags for frequently filtered attributes
• Use metadata sparingly for high-cardinality data

API Usage

When using the LangSmith API, you can pass these filters as query parameters:

from langsmith import Client

client = Client()

# Filter traces using the query syntax
traces = client.list_runs(
    project_name="my-project",
    filter="run_type:llm AND status:error"
)

Best Practices

1. Use specific filters: Narrow down your search to improve performance
2. Leverage tags: Use tags for commonly filtered attributes
3. Optimize metadata: Keep metadata keys consistent and meaningful
4. Test queries: Verify your filter syntax before using in production
5. Monitor performance: Complex queries may take longer to execute

Troubleshooting

Common Issues

• No results: Check for typos in filter values
• Slow queries: Simplify complex filters or add time constraints
• Syntax errors: Verify operator usage and parentheses matching

Debugging Tips

• Start with simple filters and build complexity gradually
• Use the UI to test filters before implementing in code
• Check the API documentation for field names and values