langwatch/tracing

Add LangWatch Tracing to Your Code

Determine Scope

If the user's request is general ("instrument my code", "add tracing", "set up observability"):

• Read the full codebase to understand the agent's architecture
• Study git history to understand what changed and why — focus on agent behavior changes, prompt tweaks, bug fixes. Read commit messages for context.
• Add comprehensive tracing across all LLM call sites

If the user's request is specific ("add tracing to the payment function", "trace this endpoint"):

• Focus on the specific function or module
• Add tracing only where requested
• Verify the instrumentation works in context

Detect Context

This skill is code-only — there is no platform path for tracing. If the user has no codebase, explain that tracing requires code instrumentation and point them to the LangWatch docs.

Step 1: Set up the LangWatch CLI

See CLI Setup for installation. The CLI is useful for verifying traces:

langwatch trace search --limit 5          # Verify traces arrive
langwatch trace get <traceId>             # Inspect a specific trace
langwatch analytics query --metric trace-count  # Check trace volume

For documentation access, set up the LangWatch MCP: See MCP Setup for installation instructions. If MCP installation fails, see docs fallback.

Step 2: Get the API Key

See API Key Setup.

Add the API key to the project's .env file:

LANGWATCH_API_KEY=your-key-here

Step 3: Read the Integration Docs

Use the LangWatch MCP to fetch the correct integration guide for this project:

• Call fetch_langwatch_docs with no arguments to see the docs index
• Find the integration guide matching the project's framework (OpenAI, LangGraph, Vercel AI, Agno, Mastra, etc.)
• Read the specific integration page for step-by-step instructions

CRITICAL: Do NOT guess how to instrument. Read the actual documentation for the specific framework. Different frameworks have different instrumentation patterns.

Step 4: Install the LangWatch SDK

For Python:

pip install langwatch
# or: uv add langwatch

For TypeScript:

npm install langwatch
# or: pnpm add langwatch

Step 5: Add Instrumentation

Follow the integration guide you read in Step 3. The general pattern is:

Python:

import langwatch
langwatch.setup()

@langwatch.trace()
def my_function():
    # your existing code
    pass

TypeScript:

import { LangWatch } from "langwatch";
const langwatch = new LangWatch();

IMPORTANT: The exact pattern depends on the framework. Always follow the docs, not these examples.

Step 6: Verify

Do NOT consider the instrumentation complete without verifying it works. Follow these steps in order:

1. Install dependencies — run pip install langwatch (or uv add langwatch) / npm install langwatch (or pnpm add langwatch). If the install fails due to peer dependency conflicts, widen the conflicting range and retry — do NOT silently skip this step.
2. Run a quick test — execute the agent with a simple test input to generate at least one trace. For Python, try running the main script. For TypeScript/Mastra, try running with npx tsx or the framework's dev command. Study how the framework starts to find the right approach; only give up if the framework requires infrastructure you cannot spin up (databases, external services, etc.).
3. Check traces arrived — use the CLI to verify: langwatch trace search --limit 5. If the CLI is not available but MCP is, call search_traces. If traces show up, instrumentation is confirmed working.
4. If verification isn't possible (no CLI/MCP, can't run the code, missing external services), tell the user exactly what to check: "Run your agent and verify traces appear in your LangWatch dashboard at https://app.langwatch.ai". Be specific about what you couldn't verify and why.

Common Mistakes

• Do NOT invent instrumentation patterns — always read the docs for the specific framework
• Do NOT skip the langwatch.setup() call in Python
• Do NOT forget to add LANGWATCH_API_KEY to .env
• Do NOT use platform_ MCP tools — this skill is about adding code, not creating platform resources