TypeScript SDK API Reference

import { getLangWatchTracer } from "langwatch";

const tracer = getLangWatchTracer("my-service", "1.0.0");

import { getLangWatchTracerFromProvider } from "langwatch/observability";

const tracer = getLangWatchTracerFromProvider(
  customTracerProvider,
  "my-service",
  "1.0.0"
);

import { createLangWatchSpan } from "langwatch/observability";

const otelSpan = tracer.startSpan('llm-call');
const span = createLangWatchSpan(otelSpan);
span.setType('llm').setInput('Prompt').setOutput('Completion');

import { LangWatch } from "langwatch";

const langwatch = new LangWatch({
  apiKey: process.env.LANGWATCH_API_KEY,
  endpoint: process.env.LANGWATCH_ENDPOINT_URL
});

// Get a prompt without variables
const prompt = await langwatch.prompts.get("prompt-id");

// Create a basic prompt
const prompt = await langwatch.prompts.create({
  handle: "customer-support-bot",
  name: "Customer Support Bot",
  prompt: "You are a helpful customer support assistant.",
  // ... any other prompt properties
});

// Update prompt content
const updatedPrompt = await langwatch.prompts.update("customer-support-bot", {
  prompt: "You are a helpful and friendly customer support assistant.",
  // ... any other prompt properties
});

// Delete a prompt
const result = await langwatch.prompts.delete("customer-support-bot");

// Compile a prompt with variables
const compiledPrompt = prompt.compile({
  name: "Alice",
  topic: "weather"
});

// Strict compilation with all required variables
const compiledPrompt = prompt.compileStrict({
  name: "Alice",
  topic: "weather"
});

import { LangWatchExporter, FilterableBatchSpanProcessor } from "langwatch";

const processor = new FilterableBatchSpanProcessor(
  new LangWatchExporter(), // Uses environment variables
  [
    {
      fieldName: "span_name",
      matchValue: "health-check",
      matchOperation: "exact_match"
    }
  ]
);

import { LangWatchCallbackHandler } from "langwatch/observability/instrumentation/langchain";
import { ChatOpenAI } from "@langchain/openai";

const handler = new LangWatchCallbackHandler();
const llm = new ChatOpenAI({
  callbacks: [handler]
});

// All operations will now be automatically traced
const response = await llm.invoke("Hello, world!");

import { convertFromLangChainMessages } from "langwatch/observability/instrumentation/langchain";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const messages = [
  new SystemMessage("You are a helpful assistant."),
  new HumanMessage("Hello!"),
];

const convertedMessages = convertFromLangChainMessages(messages);
// Use with span.setInput("chat_messages", convertedMessages)

import { LangWatchExporter } from "langwatch";

// Using environment variables/fallback configuration
const exporter = new LangWatchExporter();

// Using custom API key and endpoint
const exporter = new LangWatchExporter({
  apiKey: process.env.LANGWATCH_API_KEY,
  endpoint: process.env.LANGWATCH_ENDPOINT_URL
});

import { LangWatchTraceExporter } from "langwatch/observability";

const exporter = new LangWatchTraceExporter({
  apiKey: process.env.LANGWATCH_API_KEY,
  endpoint: process.env.LANGWATCH_ENDPOINT_URL
});

import { LangWatchLogsExporter } from "langwatch/observability";

const exporter = new LangWatchLogsExporter({
  apiKey: process.env.LANGWATCH_API_KEY,
  endpoint: process.env.LANGWATCH_ENDPOINT_URL
});

// Simple mode
dataCapture: "all" | "input" | "output" | "none"

// Configuration object
dataCapture: {
  mode: "all" | "input" | "output" | "none"
}

import { DataCapturePresets } from "langwatch/observability";

// Use predefined configurations
dataCapture: DataCapturePresets.CAPTURE_ALL // Captures everything
dataCapture: DataCapturePresets.CAPTURE_NONE // Captures nothing
dataCapture: DataCapturePresets.INPUT_ONLY // Captures only inputs
dataCapture: DataCapturePresets.OUTPUT_ONLY // Captures only outputs

import { getLangWatchLogger } from "langwatch";

const logger = getLangWatchLogger("my-service");

import { getLangWatchLoggerFromProvider } from "langwatch/observability";

const logger = getLangWatchLoggerFromProvider(
  customLoggerProvider,
  "my-service"
);

import { logger } from "langwatch";

const logger = new logger.ConsoleLogger({
  level: "info",
  prefix: "MyApp"
});

logger.info("Application started");
logger.warn("Deprecated feature used");
logger.error("An error occurred");

import { logger } from "langwatch";

const logger = new logger.NoOpLogger();
// All log calls are ignored

# Login to LangWatch
langwatch login

# Initialize a new prompts project
langwatch prompt init

# Create a new prompt
langwatch prompt create my-prompt

# Add a prompt from the registry
langwatch prompt add sentiment-analyzer

# List installed prompts
langwatch prompt list

# Sync prompts with the registry
langwatch prompt sync

# Remove a prompt
langwatch prompt remove my-prompt

type SpanType =
  | "span"
  | "llm"
  | "chain"
  | "tool"
  | "agent"
  | "guardrail"
  | "evaluation"
  | "rag"
  | "prompt"
  | "workflow"
  | "component"
  | "module"
  | "server"
  | "client"
  | "producer"
  | "consumer"
  | "task"
  | "unknown";

type InputOutputType =
  | "text"
  | "raw"
  | "chat_messages"
  | "list"
  | "json"
  | "guardrail_result"
  | "evaluation_result";

type PromptResponse = NonNullable<
  paths["/api/prompts/{id}"]["get"]["responses"]["200"]["content"]["application/json"]
>;

type TemplateVariables = Record<string, string | number | boolean | object | null>;

import { setupObservability } from "langwatch/observability/node";
import { getLangWatchTracer } from "langwatch";

setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY
  },
  serviceName: "my-service"
});

const tracer = getLangWatchTracer("my-service");

await tracer.withActiveSpan("process-request", async (span) => {
  span.setType("llm");
  span.setRequestModel("gpt-5");

  // Your LLM call here
  const response = await openai.chat.completions.create({
    model: "gpt-5",
    messages: [{ role: "user", content: "Hello!" }]
  });

  span.setOutput(response.choices[0].message.content);
  span.setMetrics({
    promptTokens: response.usage?.prompt_tokens,
    completionTokens: response.usage?.completion_tokens
  });
});

await tracer.withActiveSpan("rag-query", async (span) => {
  span.setType("rag");

  // Retrieve documents
  const documents = await vectorStore.similaritySearch("query", 5);

  // Set RAG contexts
  span.setRAGContexts(documents.map(doc => ({
    document_id: doc.metadata.id,
    chunk_id: doc.metadata.chunk_id,
    content: doc.pageContent
  })));

  // Generate response
  const response = await llm.generate([documents, "query"]);
  span.setOutput(response);
});

import { attributes, VAL_GEN_AI_SYSTEM_OPENAI } from "langwatch/observability";
import { getLangWatchTracer } from "langwatch";

const tracer = getLangWatchTracer("my-service");

await tracer.withActiveSpan("llm-call", async (span) => {
  // Use semantic convention attributes for consistency
  span.setType("llm");
  span.setAttribute("langwatch.streaming", false);

  // Set input/output with proper typing
  span.setInput("chat_messages", [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" }
  ]);

  // Set output
  span.setOutput("text", "Hello! How can I help you today?");
});

import { LangWatch } from "langwatch";

const langwatch = new LangWatch({
  apiKey: process.env.LANGWATCH_API_KEY
});

const prompt = await langwatch.prompts.get("customer-support");

const compiledPrompt = prompt.compile({
  name: "John Doe",
  product: "LangWatch"
});

console.log(compiledPrompt.content);
// Output: "Hello John Doe! How can I help you with LangWatch today?"

import { LangWatchCallbackHandler } from "langwatch/observability/instrumentation/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { setupObservability } from "langwatch/observability/node";

setupObservability();

const handler = new LangWatchCallbackHandler();
const llm = new ChatOpenAI({
  callbacks: [handler],
  model: "gpt-5-mini"
});

// All operations are automatically traced
const response = await llm.invoke("What is the capital of France?");

import { LangWatchExporter, FilterableBatchSpanProcessor } from "langwatch";
import { setupObservability } from "langwatch/observability/node";

const processor = new FilterableBatchSpanProcessor(
  new LangWatchExporter(),
  [
    {
      fieldName: "span_name",
      matchValue: "health-check",
      matchOperation: "exact_match"
    }
  ]
);

setupObservability({
  langwatch: 'disabled', // Prevent double exporting to LangWatch
  spanProcessors: [processor]
});

import { setupObservability } from "langwatch/observability/node";

setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY,
    processorType: "batch"
  },
  serviceName: "my-service",
  attributes: {
    "service.version": "1.0.0",
    "deployment.environment.name": "production"
  },
  dataCapture: (context) => {
    // Don't capture sensitive data in production
    if (context.environment === "production" &&
        context.operationName.includes("password")) {
      return "none";
    }
    return "all";
  },
  debug: {
    consoleTracing: true,
    logLevel: "debug"
  }
});

import { setupObservability } from "langwatch/observability/node";

const { shutdown } = setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY
  }
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  console.log('Shutting down observability...');
  await shutdown();
  console.log('Observability shutdown complete');
  process.exit(0);
});