groundy
Agents & Frameworks

How to Trace LangChain Agents Selectively With LangChainTracer

Selective LangChain tracing isolates specific agent runs for review, but requires correct regional endpoints and explicit submission checks to ensure trace integrity.

Published 7 references
On this page11 sections

For a run you intend to review, use selective capture rather than environment-wide tracing: pass a LangChainTracer instance as a callback in Python or JS/TS, or wrap the relevant Python code in tracing_context. LangChain’s default setup is easier to enable, but it traces every LangChain runnable invocation under that configuration. Selective scope solves only half the verification problem; you also need the right regional endpoint, compatible packages, and confirmation that the trace was submitted before the process exited (LangChain’s tracing documentation).

That last check changes how the record should be interpreted. A captured trace can support review of the run it contains. A missing trace cannot, by itself, establish that the run never happened.

The default is convenient because its scope is broad

With tracing configured, LangChain’s quick start requires no additional instrumentation. In the documentation’s words: “No extra code is needed to log a trace to LangSmith. Just run your LangChain code as you normally would.” The same page describes the resulting scope as tracing all LangChain runnable invocations after tracing and an agent environment are selected (LangChain documentation).

This is a useful starting point. It lets a team establish that LangChain and LangSmith are connected without modifying each invocation. It is less suitable when the question is “what happened in this particular verification run?” Other invocations under the same configuration can also produce traces, leaving the reviewer to identify the intended record after the fact.

The distinction is therefore not instrumentation versus no instrumentation. It is who chooses the capture boundary: the environment configuration or the code around the run being examined.

Select the scope before selecting the tool

LangChain documents three relevant scopes. The recommendations in the final column are editorial synthesis based on those documented mechanisms, not a vendor-prescribed verification protocol.

Capture scopeLanguage supportDocumented mechanismWhen I would use it
Environment-widePython and JS/TSEnable tracing and select the destination; LangChain code then traces all runnable invocationsInitial setup and broad debugging, when isolating one run is not the goal
Selected invocation or agent componentPython and JS/TSManually pass a LangChainTracer instance as a callbackCapturing a particular invocation or part of an agent for inspection
Python code blockPython onlyUse the tracing_context context managerGrouping the runs within a deliberately chosen Python region

The callback is the common option across the two languages. tracing_context provides a second Python mechanism, but the fetched documentation does not describe a JS/TS equivalent. A JS/TS implementation should therefore plan around the callback rather than assume API parity (LangChain’s selective-tracing section).

Scope selection also does not replace record identification. LangChain supports arbitrary metadata and tags through RunnableConfig, customizable run_name and run_id values, and use of a root run_id as the trace_id. JS/TS can access run IDs through a RunCollectorCallbackHandler instance (LangChain documentation). For review, I would attach an identifier for the change or test case and record the resulting trace ID with the review. Otherwise, selective capture can still leave the team searching for a record it cannot confidently match to the change.

Check the regional endpoint before debugging the callback

For an account outside the default US region, LANGSMITH_ENDPOINT is a precondition, not an optional refinement. LangChain says that without the regional API URL, the API key will not be recognized and requests will fail to authenticate. Its EU example is:

LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com

The documented regions are GCP US, which is the default, GCP EU, GCP APAC, and AWS US (LangChain’s endpoint instructions). Match the endpoint to the account’s actual region before investigating whether a callback or context manager is working. An authentication failure prevents the record from reaching its destination regardless of how carefully the invocation was scoped.

Where environment variables cannot be set, the documentation also describes applying the tracing configuration programmatically, including tracing enablement, endpoint, API key, and destination. That is an alternative configuration route, not an exemption from the regional requirement.

Choose where the evidence will live

The destination configuration depends on the workspace:

  • Agent-based selection uses LANGSMITH_AGENT_ID and LANGSMITH_AGENT_ENVIRONMENT. For per-request routing, the documentation supports passing an agent address in code.
  • Project-based workspaces and self-hosted LangSmith use LANGSMITH_PROJECT. The environment’s tracer_session_name serves as a compatibility value for integrations that need project_name (LangChain documentation).

Residency is a separate decision from callback scope. LangChain says LangSmith cloud at smith.langchain.com stores data in GCP us-central-1. It also describes Enterprise deployment in a customer’s Kubernetes cluster on AWS, GCP, or Azure, alongside self-hosted and BYOC options (LangSmith’s observability page).

Self-hosting changes the operational burden as well as the destination. LangChain says self-hosted LangSmith keeps trace and operational data in the customer’s environment. For SmithDB, its documented requirements include LangSmith 0.17 or later, a dedicated PostgreSQL 18 or later metastore, and a dedicated object-storage bucket (self-hosted LangSmith documentation). I would not choose self-hosting merely to isolate a run; a callback can do that. It becomes relevant when trace residency and infrastructure control justify those additional requirements.

Version floors apply to specific interop paths

The documented version numbers should not be flattened into one universal minimum for every selective-tracing use. They concern particular interactions between LangChain, LangSmith, and @traceable:

  • Starting with langchain@0.2.x, LangChain objects used inside @traceable functions are traced automatically and inherit the client, tags, metadata, and tracing destination.
  • Below 0.2.x, the documented path requires manually passing a LangChainTracer created from the @traceable tracing context.
  • Invoking traceable-wrapped functions within RunnableLambda requires LangSmith 0.1.39 or later and @langchain/core 0.2.18 or later (LangChain’s JS interop documentation).

For these paths, meeting the stated floors is a pre-flight check, not a compatibility guarantee for every package combination. Pinning and testing the selected versions is my operational recommendation. The floors come from living documentation fetched on November 20, 2026 and may lag current releases, so they should be rechecked during upgrades rather than treated as permanent compatibility facts.

The same documentation supports distributed tracing with LangChain Python to link spans across services, and describes LangChain objects invoked inside traceable functions as child runs. Those features can help establish run boundaries, but they do not establish how every selective callback behaves under arbitrary nested or asynchronous agent designs.

A finished run is not necessarily a submitted trace

Python tracing posts records from a background thread to avoid obstructing the production agent. LangChain warns that the process may exit before all traces reach LangSmith, with serverless environments particularly exposed because the VM may be terminated as soon as the chain or agent completes (LangChain’s tracing documentation).

Two documented remedies are available:

  1. Set LANGCHAIN_CALLBACKS_BACKGROUND="false" to make callbacks synchronous.
  2. Keep background submission and use the documented method for the language to wait for trace submission before exit.

The choice belongs in process lifecycle design. A short-lived job that exits immediately after producing an answer needs an explicit submission boundary. If the process cannot wait, its trace record is not a dependable account of which runs executed.

This also qualifies LangChain’s broader performance claim. Its observability FAQ states: “No. The LangSmith SDK uses an async callback handler that sends traces to a distributed collector. Your application performance is never impacted.” (LangSmith FAQ). Application latency and trace completeness are different properties. The supplied sources contain no independent measurement of either the performance effect of synchronous callbacks or the rate of trace loss, so the absolute performance statement should not be read as a delivery guarantee.

For verification, absence of a trace is inconclusive until submission and retention have been checked. Even a present trace establishes only that a record arrived; it does not establish that the agent’s output was correct.

What makes a trace useful for review?

IBM describes LangSmith as infrastructure for monitoring, debugging, and evaluating LLM applications (IBM’s LangSmith explainer). Those functions overlap, but a debugging trace does not automatically become an evaluation result. The reviewer still needs to know which run was captured, whether its boundaries cover the event being assessed, and what standard the output must meet.

The Claude Code team’s November 16, 2026 verification post argues for running a change end to end and giving agents ways to check their output. Its reported improvement of up to 10 points comes from self-reported internal testing on structured file generation, comparing a standard prompting loop with a separate grader checking work against a rubric; the largest gains were reported on the hardest problems. It is not a LangSmith benchmark or an independently replicated result (Claude Code verification post). The transferable principle is the separation between producing a run and grading it, not the numeric gain.

Agent-evaluation research gives trace scope a similarly concrete role. Async-RBench records the main agent’s trace from event presentation through run end, together with the pre-event state, as evidence for scoring verification decisions. Its agent must determine the result’s validity and scope before deciding what to revise or rerun (Async-RBench). This does not show that LangSmith automatically supplies an equivalent record. It shows why a reviewer needs the right interval and context, rather than whichever invocation happened to be easiest to capture.

My review rule follows from that distinction: link the trace ID to the change, check that the captured scope covers the decision being graded, and apply the correctness rubric separately. If a required child run or service span is absent, investigate capture before drawing a conclusion about agent behavior.

Where the current evidence stops

The fetched LangChain documentation establishes the basic scope choices and the process-exit failure mode. It does not settle LangChainTracer behavior under async or nested agents, sampling, redaction, LangSmith retention windows, or most other failure modes. No independent operational report on selective tracing was supplied, and none of the paths described here was independently tested for this article.

Retention deserves an explicit check rather than an assumed default. A synthetic study of generic cloud logs, not LangSmith traces, found that reducing retention from 90 days to 14 days could cut storage costs by up to 78 percent while preserving more than 97 percent of operationally useful logs (Cost-Aware Logging study). Those figures cannot be transferred to LangSmith. They support only the narrower conclusion that retention is a cost-versus-usefulness decision; they do not justify choosing 14 days for verification evidence.

Until current documentation or an operational trial resolves sampling, redaction, nesting, and retention for your setup, keep those limitations visible. Use environment-wide tracing to establish the plumbing, selective capture to isolate the run, and synchronous callbacks or an explicit wait to establish delivery. If those checks cannot be made, the trace can remain useful for debugging, but it should not be the sole evidence behind a release or customer review.

Frequently Asked Questions

What endpoint setting is required for LangSmith accounts outside the US region?

For an account outside the default US region, LANGSMITH_ENDPOINT is a precondition, not an optional refinement. LangChain says that without the regional API URL, the API key will not be recognized and requests will fail to authenticate.

Which Python version is required for self-hosted LangSmith SmithDB?

For SmithDB, its documented requirements include LangSmith 0.17 or later, a dedicated PostgreSQL 18 or later metastore, and a dedicated object-storage bucket (self-hosted LangSmith documentation).

References

Follow the links in the article for context. The supporting material is collected here for further reading.

  1. LangChain’s tracing documentationdocs.langchain.comAccessed
  2. LangSmith’s observability pagelangchain.comAccessed
  3. self-hosted LangSmith documentationdocs.langchain.comAccessed
  4. IBM’s LangSmith explaineribm.comAccessed
  5. Claude Code verification postclaude.devAccessed
  6. Async-RBencharxiv.orgAccessed
  7. Cost-Aware Logging studyarxiv.orgAccessed

Join the discussion

Share a useful perspective or ask a question about this article.

Discussion guidelinesComments privacy