Cookbook: Langfuse JS/TS SDK

JS/TS applications can either be traced via the Langfuse JS/TS SDK, or by using one of the native integrations such as OpenAI, LangChain or Vercel AI SDK.

In this notebook, we will walk you through a simple end-to-end example that:

• Shows how to log any LLM call via the low-level SDK methods
• Uses integrations that are interoperable with low-level SDK
  • LangChain integration
  • OpenAI integration
  • Vercel AI SDK

For this guide, we assume that you are already familiar with the Langfuse data model (traces, spans, generations, etc.). If not, please read the conceptual introduction to tracing.

Set Up Environment

Get your Langfuse API keys by signing up for Langfuse Cloud or self-hosting Langfuse. You’ll also need your OpenAI API key.

Note: This cookbook uses Deno.js for execution, which requires different syntax for importing packages and setting environment variables. For Node.js applications, the setup process is similar but uses standard npm packages and process.env.

With the environment variables set, we can now initialize the langfuseSpanProcessor which is passed to the main OpenTelemetry SDK that orchestrates tracing.

The LangfuseClient provides additional functionality beyond OpenTelemetry tracing, such as scoring, prompt management, and data retrieval. It automatically uses the same environment variables we set earlier.

Log LLM Calls

You can use the SDK to log any LLM call or any of the integrations that are interoperable with it.

In the following, we will demonstrate how to log LLM calls using the SDK, LangChain, Vercel AI SDK, and OpenAI integrations.

Option 1: Context Manager

To simplify nesting and context management, you can use startActiveObservation. These functions take a callback and automatically manage the observation’s lifecycle and the OpenTelemetry context. Any observation created inside the callback will automatically be nested under the active observation, and the observation will be ended when the callback finishes.

This is the recommended approach for most use cases as it prevents context leakage and ensures observations are properly ended.

Public trace in the Langfuse UI

Option 2: observe Decorator

The observe wrapper is a powerful tool for tracing existing functions without modifying their internal logic. It acts as a decorator that automatically creates a span or generation around the function call. You can use the updateActiveObservation function to add attributes to the observation from within the wrapped function.

Public trace in the Langfuse UI

Option 3: Manual Spans

This part shows how to log any LLM call by passing the model in and outputs via the Langfuse SDK.

Steps:

1. Create span to contain this section within the trace
2. Create generation, log input and model name as it is already known
3. Call the LLM SDK and log the output
4. End generation and span

Teams typically wrap their LLM SDK calls in a helper function that manages tracing internally. This implementation occurs once and is then reused for all LLM calls.

Public trace in the Langfuse UI

Native integrations

Besides manual creation of spans using the SDK methods (decorator, context manager and manual creation), you can also use the native instrumentations for OpenAI or Langchain to automatically capture all generation details.

Option 1: Using OpenAI

This step shows how to trace OpenAI applications using the OpenAI integration which is interoperable with the Langfuse SDK.

Since this is a native integration, the model parameters and outputs are automatically captured.

Public trace in the Langfuse UI

Option 2: Using LangChain

This step shows how to trace LangChain applications using the LangChain integration which is fully interoperable with the Langfuse SDK.

Since this is a native integration, the model parameters and outputs are automatically captured.

Public trace in the Langfuse UI

Option 3: Vercel AI SDK

The Vercel AI SDK offers native instrumentation with OpenTelemetry. To send spans to your Langfuse instance, you need to set experimental_telemetry: {isEnabled: true}.

[Public trace in the Langfuse UI](Public trace in the Langfuse UI)

Step 5: View the Traces in Langfuse

After ingesting your spans, you can view them in your Langfuse dashboard.

Example trace in the Langfuse UI.

Learn More

• Langfuse JS/TS SDK Documentation
• Langfuse Integrations