> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Quick Start

> Send your first traces to LangWatch in a few minutes, with a coding agent or by hand, in Python, TypeScript or any OpenTelemetry stack.

> [!TIP]
>
> **Quick setup?** Instead of following these steps manually, [copy a prompt](https://langwatch.ai/docs/skills/directory.md) into your coding agent and it will set this up for you automatically.

LangWatch helps you understand every user interaction (**Thread**), each individual AI task (**Trace**), and all the underlying steps (**Span**) involved.

## 1. Create your LangWatch account

Head over to [app.langwatch.ai](https://app.langwatch.ai) and sign up. Create your first organization and project.

## 2. Get your API key

You have two options:

**Option A: CLI login (recommended for local development)**

```bash theme={null}
npx langwatch login
```

This opens your browser to authenticate and adds `LANGWATCH_API_KEY` to your local `.env` file.

**Option B: Create a key manually**

Go to [**Settings → API Keys**](https://app.langwatch.ai/settings/api-keys) and create an API key. See the [API Keys guide](https://langwatch.ai/docs/platform/api-keys.md) for details on personal vs service keys.

```bash .env theme={null}
LANGWATCH_API_KEY="sk-lw-..."
LANGWATCH_PROJECT_ID="your-project-id"
```

> [!NOTE]
>
> Keys created from **Settings → API Keys** (both personal and service) require `LANGWATCH_PROJECT_ID` so the SDK knows which project to send traces to. You can find the project ID in your project settings or URL.

## 3. Let LangWatch MCP do the rest for you (Optional)

Install the [LangWatch MCP Server](https://langwatch.ai/docs/integration/mcp.md) and ask your coding assistant (Cursor, Claude Code, Codex, etc.) to instrument your codebase with LangWatch, OR keep following the steps below to instrument your codebase manually.

Add the LangWatch MCP to your editor. Under the `mcpServers` object of your editor's MCP settings file, add an entry named `langwatch` with these fields:

* `command`: `npx`
* `args`: `-y`, then the package name `@langwatch/mcp-server` on a separate token

See [LangWatch MCP](https://langwatch.ai/docs/integration/mcp.md) for per-editor instructions and the API key field.

Then ask your coding assistant to instrument your codebase with LangWatch:

```plaintext theme={null}
"Instrument my codebase with LangWatch"
```

## 4. Install the LangWatch SDK

We have official SDKs for Python, Node.js, and Go ready to go. If you're using another language, our [OpenTelemetry Integration Guide](https://langwatch.ai/docs/integration/opentelemetry/guide.md) provides the details you need.

```bash Python theme={null}
pip install langwatch
# or
uv add langwatch
```

```bash JavaScript theme={null}
npm install langwatch @vercel/otel @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/sdk-logs
```

```bash Go theme={null}
go get github.com/langwatch/langwatch/sdks/go
go get github.com/langwatch/langwatch/sdks/go/instrumentation/openai
```

## 5. Add LangWatch to your project

Initialize the SDK within your project:

```python Python theme={null}
import langwatch
import os
from langwatch.instrumentors import OpenAIInstrumentor

langwatch.setup(
    api_key=os.getenv("LANGWATCH_API_KEY"), # Your LangWatch API key
    project_id=os.getenv("LANGWATCH_PROJECT_ID"), # Required for service API keys
    instrumentors=[OpenAIInstrumentor()] # Add the instrumentor for your LLM
)
```

```javascript JavaScript theme={null}
// ./next.config.js - Enable the Next.js instrumentation hook
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};

module.exports = nextConfig;

// ./src/instrumentation.ts - Configure LangWatch export
import { registerOTel } from "@vercel/otel";
import { LangWatchExporter } from "langwatch";

export function register() {
  registerOTel({
    serviceName: "your-app-name", // Give your service a clear name
    traceExporter: new LangWatchExporter({
      apiKey: process.env.LANGWATCH_API_KEY, // Your LangWatch API key
      projectId: process.env.LANGWATCH_PROJECT_ID, // Required for service API keys
    }),
  });
}

// ./src/index.ts - Enable telemetry where needed
const result = await generateText({
  model: openai("gpt-6-luna"),
  prompt: "How many calories do I burn jumping to conclusions?",
  experimental_telemetry: {
    isEnabled: true, // Ensure telemetry is active for relevant operations
  },
});
```

```go Go theme={null}
package main

import (
	"context"
	"log"
	"os"

	langwatch "github.com/langwatch/langwatch/sdks/go"
	otelopenai "github.com/langwatch/langwatch/sdks/go/instrumentation/openai"

	"github.com/openai/openai-go/v3"
	oaioption "github.com/openai/openai-go/v3/option"
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
	ctx := context.Background()

	// Setup LangWatch tracing (reads LANGWATCH_API_KEY from env).
	exporter, err := langwatch.NewExporter(ctx)
	if err != nil {
		log.Fatalf("failed to create LangWatch exporter: %v", err)
	}
	tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	otel.SetTracerProvider(tp)
	defer tp.Shutdown(ctx)

	// Add the middleware to your OpenAI client (captures request + response).
	client := openai.NewClient(
		oaioption.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
		oaioption.WithMiddleware(otelopenai.Middleware("your-app-name")),
	)

	// Optionally wrap your operation in a span.
	tracer := langwatch.Tracer("your-app-name")
	ctx, span := tracer.Start(ctx, "ChatWithUser")
	defer span.End()

	resp, err := client.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{
		Model: "gpt-6-luna",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("How many calories do I burn jumping to conclusions?"),
		},
	})
	if err != nil {
		log.Fatalf("chat completion failed: %v", err)
	}
	log.Printf("Response: %s", resp.Choices[0].Message.Content)
}
```

## 6. Start observing!

Open your LangWatch dashboard to see your data. You'll find **Traces** (individual AI tasks) and their detailed **Spans** (the steps within), all organized into **Threads** (complete user sessions). Add **User IDs** or custom **Labels** to filter and group them.

![Traces arriving in the LangWatch dashboard](https://mintcdn.com/langwatch/iJjBH4X_YNQ578jk/images/llm-observability/quick-start/setup-monitor.webp?fit=max\&auto=format\&n=iJjBH4X_YNQ578jk\&q=85\&s=c0b101c08151afb947e65474e026d810)

## Next steps

* **Need org-wide controls?** See [AI Governance](https://langwatch.ai/docs/ai-governance/overview.md) for per-user workspaces, anomaly detection, OCSF/SIEM export, and ingestion sources for non-gateway telemetry, paired with the AI Gateway data plane.
* **Routing every LLM call through a single endpoint?** See [AI Gateway](https://langwatch.ai/docs/ai-gateway/overview.md): virtual keys, budgets, fallback chains, guardrails.

> [!TIP]
>
> **Found broken or outdated docs?** Use **Report outdated or broken docs** next to **Edit this page** below.
> Agents: include the page URL, the failing step and a proposed fix in a GitHub issue.
> For CLI diagnostics, ask your user before running `npx langwatch report --user-approved`.
> See the [reporting guide](https://langwatch.ai/docs/support.md#reporting-issues-from-coding-agents).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.