Cookbook: Langfuse JS/TS SDK

// Langfuse authentication keys
Deno.env.set("LANGFUSE_PUBLIC_KEY", "pk-lf-***");
Deno.env.set("LANGFUSE_SECRET_KEY", "sk-lf-***");
 
// Langfuse host configuration
// For US data region, set this to "https://us.cloud.langfuse.com"
Deno.env.set("LANGFUSE_HOST", "https://cloud.langfuse.com")
 
// Set environment variables using Deno-specific syntax
Deno.env.set("OPENAI_API_KEY", "sk-proj-***");

// Import required dependencies
import 'npm:dotenv/config';
import { NodeSDK } from "npm:@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "npm:@langfuse/otel";
 
// Export the processor to be able to flush it later
// This is important for ensuring all spans are sent to Langfuse
export const langfuseSpanProcessor = new LangfuseSpanProcessor({
    publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
    secretKey: process.env.LANGFUSE_SECRET_KEY!,
    baseUrl: process.env.LANGFUSE_HOST ?? 'https://cloud.langfuse.com', // Default to cloud if not specified
    environment: process.env.NODE_ENV ?? 'development', // Default to development if not specified
  });
 
// Initialize the OpenTelemetry SDK with our Langfuse processor
const sdk = new NodeSDK({
  spanProcessors: [langfuseSpanProcessor],
});
 
// Start the SDK to begin collecting telemetry
// The warning about crypto module is expected in Deno and doesn't affect basic tracing functionality. Media upload features will be disabled, but all core tracing works normally
sdk.start();

import { LangfuseClient } from "npm:@langfuse/client";
 
const langfuse = new LangfuseClient();

// Import necessary functions from the tracing package
import { startActiveObservation, startObservation, updateActiveTrace, updateActiveObservation } from "npm:@langfuse/tracing";
 
// Start a new span with automatic context management
await startActiveObservation("context-manager", async (span) => {
  // Log the initial user query
  span.update({
    input: { query: "What is the capital of France?" }
  });
 
  // Create a new generation span that will automatically be a child of "context-manager"
  const generation = startObservation(
    "llm-call", 
    {
    model: "gpt-4",
    input: [{ role: "user", content: "What is the capital of France?" }],
    },
    { asType: "generation" },
  );
 
  // ... LLM call logic would go here ...
 
  // Update the generation with token usage statistics
  generation.update({
    usageDetails: {
      input: 10, // Number of input tokens
      output: 5, // Number of output tokens
      cache_read_input_tokens: 2, // Tokens read from cache
      some_other_token_count: 10, // Custom token metric
      total: 17, // Optional: automatically calculated if not provided
    },
  });
 
  // End the generation with the LLM response
  generation.update({
    output: { content: "The capital of France is Paris." },
  }).end();
 
  // Example user information
  const user = { id: "user-5678", name: "Jane Doe", sessionId: "123" };
 
  // Add an optional log level of type warning to the active span
  updateActiveObservation(
    { level: "WARNING", statusMessage: "This is a warning" },
  );
 
  // Update the trace with user context
  updateActiveTrace({
    userId: user.id,
    sessionId: user.sessionId,
    metadata: { userName: user.name },
  });
 
  // Mark the span as complete with final output
  span.update({ output: "Successfully answered." });
});
 
// Ensure all spans are sent to Langfuse
await langfuseSpanProcessor.forceFlush();

import { observe, updateActiveObservation } from "npm:@langfuse/tracing";
 
// An existing function
async function fetchData(source: string) {
  updateActiveObservation({ usageDetails: {
    // usage
    input: 10,
    output: 5,
  }, { asType: 'generation' }
})
  
  // ... logic to fetch data
  return { data: `some data from ${source}` };
}
 
// Wrap the function to trace it
const tracedFetchData = observe(fetchData, {
  name: "observe-wrapper",
  asType: "generation",
});
 
// Now, every time you call tracedFetchData, a span is created.
// Its input and output are automatically populated with the
// function's arguments and return value.
const result = await tracedFetchData("API");
 
await langfuseSpanProcessor.forceFlush();

// Import the startObservation function for manual span creation
import { startObservation } from 'npm:@langfuse/tracing';
 
// Create the root span for this operation
const span = startObservation('manual-observation', {
    input: { query: 'What is the capital of France?' },
  });
  
// Create a child span for a tool call (e.g., weather API)
const toolCall = span.startObservation(
  'fetch-weather',
  { input: { city: 'Paris' } },
  { asType: "tool" },
);
// Simulate API call with timeout
 
await new Promise((r) => setTimeout(r, 100));
// End the tool call with its output
toolCall.update({ output: { temperature: '15°C' } }).end();
 
// Create a generation span for the LLM call
const generation = span.startObservation(
  'llm-call', 
  {
  model: 'gpt-4',
  input: [{ role: 'user', content: 'What is the capital of France?' }],
  output: { content: 'The capital of France is Paris.' },
  },
  { asType: "generation" },
);
 
// Update the generation with token usage details
generation.update({
  usageDetails: {
    input: 10,              // Input token count
    output: 5,              // Output token count
    cache_read_input_tokens: 2,  // Cached tokens used
    some_other_token_count: 10,  // Custom metric
    total: 17,              // Total tokens (optional)
  },
});
 
// End the generation with final output
generation.update({
  output: { content: 'The capital of France is Paris.' },
}).end();
 
// End the root span with final status and session ID
span.update({ 
  output: 'Successfully answered user request.', 
  sessionId: '123' 
}).end();
 
// Ensure all spans are flushed to Langfuse
await langfuseSpanProcessor.forceFlush();

// Import required packages
import OpenAI from "npm:openai@^4";
import { observeOpenAI } from "npm:@langfuse/openai";
 
// Initialize the OpenAI client
const openai = new OpenAI();
 
// Wrap the OpenAI client with Langfuse tracing
const tracedOpenAI = observeOpenAI(openai, {
  // Configure trace-level attributes for all API calls
  traceName: "my-openai-trace",      // Name for the trace
  sessionId: "user-session-123",     // Track user session
  userId: "user-abc",                // Track user identity
  tags: ["openai-integration"],      // Add searchable tags
});
 
// Make an API call using the traced client
// All parameters and responses will be automatically captured
const completion = await tracedOpenAI.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "What is OpenTelemetry?" }],
});

// Import required LangChain and Langfuse packages
import { ChatOpenAI } from "npm:@langchain/openai";
import { ChatPromptTemplate } from "npm:@langchain/core/prompts";
import { CallbackHandler } from "npm:@langfuse/langchain";
 
// Initialize the Langfuse callback handler with tracing configuration
const langfuseHandler = new CallbackHandler({
  sessionId: "user-session-123",  // Track user session
  userId: "user-abc",            // Track user identity
  tags: ["langchain-test"],      // Add searchable tags
});
 
// Define the LangChain components
const model = new ChatOpenAI({ model: "gpt-4o" });  // Initialize LLM
const prompt = ChatPromptTemplate.fromTemplate("Tell me a joke about {topic}.");  // Create prompt template
const chain = prompt.pipe(model);  // Combine prompt and model into a chain
 
// Execute the chain with Langfuse tracing
const result = await chain.invoke(
  { topic: "developers" },  // Input variables for the prompt
  {
    callbacks: [langfuseHandler],  // Enable Langfuse tracing
    runName: "joke-generator",     // Name for the trace (if no active span)
  }
);
 
// Output the result
console.log(result.content);

// Import Vercel AI SDK components
import { generateText } from "npm:ai"
import { openai } from "npm:@ai-sdk/openai"
 
// Generate text with OpenTelemetry tracing enabled
const result_3 = await generateText({
    model: openai('gpt-4.1'),                // Specify the OpenAI model
    prompt: 'Write a short story about a cat.',  // The prompt for generation
    experimental_telemetry: {
      isEnabled: true,                       // Enable OpenTelemetry tracing
      functionId: 'my-awesome-function',     // Identify the function being traced
      metadata: {
        something: 'custom',                 // Custom metadata fields
        someOtherThing: 'other-value',
        sessionId: '123',                    // Track user session
        userId: '456',                       // Track user identity
        tags: ['test', 'langfuse'],         // Add searchable tags
      },
    },
  });