How to beginner · 3 min read

How to add custom metadata to LangSmith traces

Q: How to add custom metadata to LangSmith traces

Use the LangSmith Python SDK's Client to create traces and add custom metadata by passing a metadata dictionary when starting a trace or logging events. This metadata is then attached to the trace for enhanced observability and debugging.

Quick answer

Use the LangSmith Python SDK's Client to create traces and add custom metadata by passing a metadata dictionary when starting a trace or logging events. This metadata is then attached to the trace for enhanced observability and debugging.

PREREQUISITES

Python 3.8+
pip install langsmith
LangSmith API key set in environment variable LANGSMITH_API_KEY

Setup

Install the LangSmith Python SDK and set your API key as an environment variable for authentication.

bash

pip install langsmith

Step by step

This example shows how to create a LangSmith client, start a trace with custom metadata, and log events with additional metadata.

python

import os
from langsmith import Client

# Initialize LangSmith client with API key from environment
client = Client(api_key=os.environ["LANGSMITH_API_KEY"])

# Define custom metadata
custom_metadata = {
    "user_id": "12345",
    "session_id": "abcde-67890",
    "feature_flag": True
}

# Start a trace with custom metadata
with client.trace("example-trace", metadata=custom_metadata) as trace:
    # Log an event with additional metadata
    trace.log("step_1_completed", metadata={"step_duration_ms": 150})
    # Simulate some processing
    result = "Hello, LangSmith!"
    trace.log("result_generated", metadata={"result_length": len(result)})

print("Trace completed with custom metadata attached.")

output

Trace completed with custom metadata attached.

Common variations

You can add metadata at trace start or per event. Async usage is supported by using async with and await for logging. Metadata keys and values can be any JSON-serializable types.

python

import asyncio
import os
from langsmith import Client

async def async_trace_example():
    client = Client(api_key=os.environ["LANGSMITH_API_KEY"])
    custom_metadata = {"request_id": "req-7890", "priority": "high"}

    async with client.trace("async-example-trace", metadata=custom_metadata) as trace:
        await trace.log("async_step", metadata={"step_info": "started"})
        # Simulate async work
        await asyncio.sleep(0.1)
        await trace.log("async_step", metadata={"step_info": "completed"})

    print("Async trace completed with metadata.")

asyncio.run(async_trace_example())

output

Async trace completed with metadata.

Troubleshooting

If you see authentication errors, verify your LANGSMITH_API_KEY environment variable is set correctly.
Ensure metadata values are JSON-serializable; unsupported types will cause errors.
If traces do not appear in the LangSmith dashboard, check network connectivity and API key permissions.

✅

Key Takeaways

Use the metadata parameter when starting a trace to add custom metadata globally.
You can also add metadata to individual trace events for granular observability.
Async tracing is supported with async with and await for logging.
Always ensure metadata is JSON-serializable to avoid runtime errors.
Set your LangSmith API key in LANGSMITH_API_KEY environment variable for authentication.

Verified 2026-04

Verify ↗