DS DevShelfHub Projects · AI tools
Tutorials / LangChain / Reference / Decorators / @traceable
Decorator langsmith

@traceable: Reference Guide

By DevShelfHub

Manually trace non-LangChain functions to LangSmith.

What is @traceable?

@traceable is LangSmith's decorator for instrumenting arbitrary Python functions — anything outside the LangChain Runnable ecosystem that you want to appear in your LangSmith trace tree. LangChain Runnables (ChatModels, chains, retrievers, agents) are auto-traced when LANGSMITH_TRACING=true is set. Custom preprocessing functions, third-party API calls, database queries, and business logic are not — @traceable bridges that gap.

When a @traceable function is called inside a LangChain trace context (e.g., during a model.invoke() call), LangSmith automatically nests the function's trace as a child run under the parent LangChain run. This gives you a single unified trace tree spanning both LangChain and non-LangChain code. If called outside a LangChain context, @traceable creates a top-level run. In both cases, LangSmith records the function's input arguments (serialized to JSON), its return value, any raised exception, and wall-clock timing.

The decorator accepts several keyword arguments for richer observability: name overrides the display name in LangSmith (default is the function's __name__); run_type can be "chain", "retriever", "llm", "tool", or "parser" (affects the icon in the UI); metadata is a dict attached to the run for filtering; tags is a list of searchable strings. For async functions, @traceable wraps the coroutine and propagates the trace context correctly — await still works as expected. To add metadata dynamically inside the function, call langsmith.get_current_run_tree() and set attributes on the returned RunTree object.

Use Cases

  • • Trace custom functions
  • • Monitor APIs
  • • Debug flows
  • • Profile performance
  • • Test integration
  • • Monitor production

Key Features

  • ✓ Any Python function
  • ✓ Hierarchical traces
  • ✓ Error tracking
  • ✓ Performance metrics
  • ✓ Metadata tagging
  • ✓ LangSmith integration

When NOT to Use

For LangChain Runnables—auto-traced already.

Notes

LANGSMITH_TRACING=true and LANGSMITH_API_KEY are both required

Without LANGSMITH_TRACING=true in the environment, @traceable is a no-op — it runs the function normally without recording anything. Without LANGSMITH_API_KEY, trace submission fails silently (or raises depending on the SDK version). Set both environment variables before any import of langsmith.

Traces are sent asynchronously — the function returns before the trace is flushed

LangSmith's SDK batches trace submissions in a background thread. If your process exits immediately after a @traceable call (e.g., in a short script or test), the trace may not reach LangSmith. Add langsmith.utils.get_client().flush() at process exit, or use the @traceable context manager form in tests.

run_type affects the icon and filtering in LangSmith UI

The run_type parameter controls how the run appears in LangSmith's trace viewer: "llm" shows a model icon, "retriever" shows a search icon, "tool" shows a wrench, "chain" shows a chain icon, "parser" shows a doc icon. Choose the type that matches the function's role to make traces easier to read at a glance.

Nested @traceable calls automatically form a parent-child trace tree

If one @traceable function calls another @traceable function, LangSmith nests the inner run as a child of the outer run automatically — no manual context propagation needed. The same nesting works inside LangChain Runnable traces: a @traceable call made inside model.invoke() appears as a child run of the LangChain model run.

Import

python 
from langsmith import traceable

How to Apply

python 
@traceable(name='my_fn')
def process(data):
    return result

Parameters

Parameter Type Default Purpose
name str function name Trace name

What It Enables

  • ✓ Trace custom functions
  • ✓ Monitor non-LangChain code
  • ✓ Performance tracking
  • ✓ Error visibility

Code Examples

Basic traceable function

python 
from langsmith import traceable
@traceable
def process(data):
    return [x * 2 for x in data]

Traceable retrieval with run_type and tags

python 
from langsmith import traceable
@traceable(
    name="vector-retrieval",
    run_type="retriever",
    tags=["production", "rag"]
)
def retrieve_docs(query: str) -> list:
    return vector_store.similarity_search(query, k=5)

Add dynamic metadata to the trace at runtime

python 
from langsmith import traceable, get_current_run_tree
@traceable
def classify(text: str) -> str:
    result = my_classifier(text)
    rt = get_current_run_tree()
    if rt:
        rt.metadata["confidence"] = result.confidence
    return result.label

Integration Patterns

Set LANGSMITH_TRACING=true
Set LANGSMITH_API_KEY

Common Mistakes

❌ No LANGSMITH_API_KEY

✅ export LANGSMITH_API_KEY='...'

Related LangChain References

Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with @traceable and the wider framework.

@traceable FAQ

What does @traceable do in LangChain?

Manually trace non-LangChain functions to LangSmith. @traceable is LangSmith's decorator for instrumenting arbitrary Python functions — anything outside the LangChain Runnable ecosystem that you want to appear in your LangSmith trace tree. LangChain Runnables (ChatModels, chains, retrievers, agents) are auto-traced when LANGSMITH_TRACING=true is set. Custom preprocessing functions, third-party API calls, database queries, and business logic are not — @traceable bridges that gap. When a @traceable function is called inside a La…

Which package provides @traceable?

DevShelfHub documents @traceable from the langsmith package. Pin your installed LangChain version and match imports to the snippet on this page.

When should I use @traceable?

Use @traceable when your LangChain agents, workflows, or pipelines need the behavior described in this guide.

When should I avoid using @traceable?

For LangChain Runnables—auto-traced already.

How do I apply @traceable in Python?

Apply @traceable as a decorator above your function definition. Import it from from langsmith import traceable and annotate the function you want to wrap. See the code examples on this page for a complete working snippet.

Where can I explore more LangChain API reference pages?

Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.