langchain-agent-tracing — Claude Code skill for LangSmith tracing
langchain-agent-tracing is a Claude Code skill for setting up LangSmith tracing in agents and LLM apps. It helps with instrumentation, destinations, and trace organization.
MIT 298 installs ★ 1,354 updated 2026-11-21
npx skills add langchain-ai/langchain-skills --skill langchain-agent-tracing -a claude-codeWhat langchain-agent-tracing does
The skill guides tracing setup for LangChain, LangGraph, Deep Agents, other agent frameworks, and OpenTelemetry-based code. It covers routing traces to the right workspace, grouping runs into conversation threads, choosing metadata, and keeping sensitive values out of traces.
Agent-based workspaces use settings such as LANGSMITH_AGENT_ID and LANGSMITH_AGENT_ENVIRONMENT; project-based workspaces use LANGSMITH_PROJECT. Sending traces requires a LangSmith API key with write access and the correct LANGSMITH_ENDPOINT. The key must not be printed or logged. Instrumenting the same calls through several tracing methods can create duplicate or disconnected runs.
What it helps with
- route traces to the intended LangSmith workspace
- choose instrumentation for an agent framework or OpenTelemetry pipeline
- group runs from one conversation with
thread_id - keep secrets and personal data out of metadata and tags
Example prompts for the agent
- Set up LangSmith tracing for this agent and choose the required environment variables.
- Show how this app can send traces to LangSmith through OpenTelemetry.
- Add conversation thread grouping and safe trace metadata.
How to install langchain-agent-tracing
1Skills CLI (Vercel)
npx skills add langchain-ai/langchain-skills --skill langchain-agent-tracing -a claude-code2Manually: put the files in place
~/.claude/skills/langchain-agent-tracing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/langchain-agent-tracing/
1Skills CLI (Vercel)
npx skills add langchain-ai/langchain-skills --skill langchain-agent-tracing -a codex2Manually: put the files in place
.agents/skills/langchain-agent-tracing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add langchain-ai/langchain-skills --skill langchain-agent-tracing -a cursor2Manually: put the files in place
.cursor/skills/langchain-agent-tracing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install langchain-ai/langchain-skills skills/langchain-agent-tracing2Manually: put the files in place
.github/skills/langchain-agent-tracing/SKILL.md1Skills CLI (Vercel)
npx skills add langchain-ai/langchain-skills --skill langchain-agent-tracing -a gemini-cli2Platform CLI
gemini skills install https://github.com/langchain-ai/langchain-skills --path skills/langchain-agent-tracingManually: put the files in place
.devin/skills/langchain-agent-tracing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add langchain-ai/langchain-skills --skill langchain-agent-tracing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about langchain-agent-tracing
How do I install langchain-agent-tracing in Claude Code?
Run npx skills add langchain-ai/langchain-skills --skill langchain-agent-tracing -a claude-code. The skill file is at ~/.claude/skills/langchain-agent-tracing/SKILL.md.
What does langchain-agent-tracing do?
It guides LangSmith tracing setup for agents and LLM applications, including instrumentation choices, trace destinations, thread grouping, and metadata.
What does langchain-agent-tracing need to work?
Sending traces requires a LangSmith API key with write permission and the LANGSMITH_ENDPOINT for the organization’s region or self-hosted instance. Set LANGSMITH_WORKSPACE_ID when targeting a specific workspace among several.
Source text
SKILL.md · MIT
--- name: langchain-agent-tracing description: Use when adding, fixing, or reviewing LangSmith tracing for an agent or LLM application, including choosing instrumentation for LangChain, LangGraph, Deep Agents, other agent frameworks, or OpenTelemetry; sending traces to the right agent environment or project; grouping turns into threads; metadata; sampling and conditional tracing; redacting sensitive data; distributed tracing across services; and finding traces after they land. --- # Trace agents with LangSmith Good tracing lands every run in the right place, keeps a request's runs in one trace, keeps sensitive data out, and records what monitoring and evaluation will need later. Decisions made while instrumenting limit what is possible downstream: without a thread ID there are no thread-level evaluators, and without stable metadata there is nothing to filter or alert on. ## Decide where traces go Check how the target workspace organizes traces before configuring a destination. Run `langsmith agents list --workspace <workspace-id> --format json`. If it returns registered agents, the workspace is agent-based. An empty result or an error is not conclusive: confirm in the LangSmith UI, where the top-left control names the workspace in an agent-based workspace and shows the LangSmith logo with an **Application** picker in a project-based one. If it is still unclear, ask the user before choosing a destination. In an agent-based workspace: - Register the application as one agent, once, rather than one agent per tier or script. Reuse an existing agent when it represents the same system. Registration needs permission to create projects; `langsmith agents create` or the docs' programmatic creation flow can do it. - Address traces with `LANGSMITH_AGENT_ID` (the stable ID, not the display name) and `LANGSMITH_AGENT_ENVIRONMENT`: `local` for a developer machine and ad hoc scripts; `development`, `staging`, or `production` for deployed tiers. - Remove `LANGSMITH_PROJECT`, `LANGCHAIN_PROJECT`, and `LANGCHAIN_SESSION` from that runtime. Do not combine legacy destinations with agent addressing. - When an integration only accepts a project name, use the environment's `tracer_session_name`. - To route individual requests, such as per tenant or per feature branch, pass an agent address through the SDK's tracing context instead of changing process-wide variables. In a project-based workspace, set `LANGSMITH_PROJECT` to the tracing project. ### Confirm the region, workspace, and credentials The application's endpoint and API key determine which organization and workspace receive traces before the agent or project is applied. Check them in every runtime that sends traces: local shell, `.env` files, CI, and deployment secrets often differ. - **Region or instance:** `LANGSMITH_ENDPOINT` must be the API URL for the organization's region or self-hosted instance. Without it, the SDK uses the default US URL, and a key from another region (EU, for example) will not authenticate. Look up the region's URL in the docs instead of guessing it. OpenTelemetry exporters use the same base URL with the OTLP path. - **Workspace:** when the API key can access more than one workspace, set `LANGSMITH_WORKSPACE_ID` to the target workspace. Otherwise traces go to the key's default workspace. Direct API calls and OpenTelemetry exports carry the workspace in the `X-Tenant-Id` header. Agent IDs and project names are resolved within that workspace, so the same ID in another workspace is a different agent or none. - **Key:** use a key from the target organization with permission to write traces there. Never print or log its value. - **Legacy names:** `LANGCHAIN_*` equivalents of these variables are still read. Remove stale ones so they cannot point traces at another endpoint, workspace, or project. Compare the application's settings with what the CLI will query: `langsmith auth info --format json` reports the CLI's `api_url` and `workspace_id`. If they differ from the application's endpoint or workspace, pass `--api-url` and `--workspace` explicitly; otherwise verification searches the wrong place and a correctly sent trace looks missing. ## Choose the instrumentation layer Start from what the application already uses: - **LangChain, LangGraph, and Deep Agents** trace automatically once tracing and the destination are configured. Agents running on a LangSmith Agent Server are traced by the server; check its deployment settings rather than adding tracing code. - **Another agent framework or model provider:** use its official LangSmith integration when one exists. Find it on the [integrations page](https://docs.langchain.com/langsmith/integrations) under "Agent frameworks" or "LLM providers", and follow its setup, including how it selects the agent environment. Wrapping the framework's entry point in `traceable` instead records only your wrapper, not the framework's own agent, model, and tool spans. - **Custom Python or TypeScript code:** wrap meaningful units of work with `traceable` and use the SDK's provider client wrappers so model calls nest under them. - **An existing OpenTelemetry pipeline or another language:** export to LangSmith's OTLP endpoint with the agent ID and environment headers, or use the SDK's OpenTelemetry support. Instrument each call once. Combining a framework integration, a wrapper, and an OpenTelemetry exporter on the same calls produces duplicate or disconnected runs. To send the same traces to LangSmith and another backend, use the SDK's tracing modes or replicas rather than parallel instrumentation. Choose the instrumentation first, then propagate context the way it expects: the SDK's `langsmith-trace` and `baggage` headers for `traceable`, and W3C `traceparent` for OpenTelemetry-based integrations. Don't switch to the SDK just to make cross-service propagation easier. ## Make traces useful for monitoring - **Threads:** for multi-turn applications, put a `thread_id` in the metadata of every run, including child runs, using one ID per conversation (the docs recommend UUID v7). Runs without it drop out of thread filters and thread token and cost totals. - **Metadata and tags:** choose a small set of stable metadata keys, such as app version, tenant, feature flag, or model, and use tags for coarse grouping. Keep key names consistent across services so filters and alerts keep working. Never put secrets or raw personal data in metadata or tags. - **Names and boundaries:** give runs names that describe the step, and make the root run's inputs and outputs the user-visible request and response. Evaluators and reviewers read the root run first. For scoring and alerting on these traces, use `langchain-agent-monitoring`. ## Control volume and cost - `LANGSMITH_TRACING_SAMPLING_RATE` (0 to 1) downsamples traces sent through the SDK and LangChain; it does not apply to direct API logging. - Use the SDK's tracing context to disable tracing for low-value requests or tenants with zero-retention requirements, and to enable it for one code path without turning it on globally. - Online evaluators sample the traces that remain, so the effective coverage is the product of both rates. Check how sampling treats multi-turn threads before relying on thread-level evaluation of sampled traffic. ## Keep sensitive data out Decide what may leave the process before enabling tracing in production. Choose the narrowest control that meets the requirement: - Hide all inputs or outputs for a client or process (`LANGSMITH_HIDE_INPUTS`, `LANGSMITH_HIDE_OUTPUTS`) when nothing may be stored. - Use the SDK's anonymizer or input/output processors to redact known patterns while keeping the rest of the trace. - Redact per request with replica updates when only some tenants need it; follow the docs' caveat about setting the replica destination explicitly, or the redaction can be dropped. - Disable tracing for a request when even run structure must not be recorded. - In an OpenTelemetry pipeline, redact span attributes in the collector before export. Confirm the result by reading a real trace's inputs, outputs, and metadata. ## Trace across services When one request crosses services, propagate LangSmith's trace context so the whole request appears as one trace. The caller sends the current run's headers (`langsmith-trace`, plus `baggage` for metadata and tags); the receiving service continues the trace from them through the SDK's tracing context or its tracing middleware. Calls into a deployed Agent Server have their own guide. Only accept these headers from trusted internal services. They control how runs are recorded, so strip them from untrusted inbound requests at the gateway. With OpenTelemetry, every ancestor span must also reach LangSmith. A child whose parent is exported elsewhere or sampled out is dropped without an error, even though the export call succeeds. ## Find traces after they land Resolve the destination to an ID, then query by ID; name-based `--project` lookups can silently use a leftover `LANGSMITH_PROJECT`. ```bash langsmith projects resolve --kind AGENT --id <agent-id> --environment LOCAL --format json langsmith traces list --project-id <session-id> --last-n-minutes 30 --limit 5 --format json langsmith traces get <trace-id> --project-id <session-id> --full --format json ``` In a project-based workspace, find the project ID with `langsmith projects list`. Narrow `traces list` with `--error`, `--tags`, `--metadata key=value`, or `--filter`. Use `langsmith runs list --project-id <session-id> --trace-ids <trace-id>` for the runs in one trace, adding `--metadata thread_id=<thread-id>` to confirm child runs carry the thread. Check grouping with `langsmith threads list` and `langsmith threads get <thread-id>` using the same `--project-id`. ## Verify the instrumentation Exercise the real application path with a realistic request, then use the commands above to confirm: - The trace is in the intended region, workspace, and agent environment or project, and nowhere else. - The run tree has the expected structure, with no duplicate or orphaned runs. - `thread_id` and the chosen metadata appear on child runs, not only the root. LangSmith does not propagate metadata or tags from parent to child runs, so attach them explicitly to each child run that needs them. - Inputs, outputs, and metadata contain no secrets or data that should have been redacted. - Calls across services appear as one trace. Tracing exports in the background. Scripts, tests, serverless functions, and workers must flush or shut down the tracer before exiting, or the last traces are lost; look up the flush call for the SDK and language in use. If no trace appears, check that the CLI is querying the same endpoint and workspace as the application, then the API key, agent ID and environment, and whether a sampling rate or tracing context disabled it, before changing code. ## Use current tools Use `langchain-docs` → `search_docs_by_lang_chain` and `query_docs_filesystem_docs_by_lang_chain` for current setup. Useful searches: "log traces to an agent", "LangSmith integrations", "trace with OpenTelemetry", "distributed tracing", "conditional tracing", "sample traces", "threads", and "prevent logging of sensitive data". Use `langchain-reference` → `search_api`, then `get_symbol`, for exact signatures of `traceable`, `tracing_context`, wrappers, and client options, and reconcile them with the installed SDK version. If MCP is unavailable, start from https://docs.langchain.com/llms.txt and https://reference.langchain.com/llms.txt. Before the first workspace command, check `langsmith --version` and `langsmith auth info`; do not call `langsmith auth token`. Pin the workspace with `--workspace`, request `--format json` when parsing, and check each command's `--help` for current flags.
© langchain-ai · MIT · langchain-ai/langchain-skills