Langfuse SDKs

Install package

Install the Langfuse Python SDK.

pip install langfuse

Add credentials

Add your Langfuse credentials as environment variables so the SDK knows which project to send your traces to.

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://cloud.langfuse.com" # 🇪🇺 EU region
# LANGFUSE_BASE_URL = "https://us.cloud.langfuse.com" # 🇺🇸 US region

Choose your instrumentation approach

Instrumentation means adding code that records what’s happening in your application so it can be sent to Langfuse.

There are three main ways of instrumenting your code with the Python SDK:

from langfuse import observe, get_client
 
@observe
def my_function():
    return "Hello, world!" # Input/output and timings are automatically captured
 
my_function()
 
# Flush events in short-lived applications
langfuse = get_client()
langfuse.flush()

from langfuse import get_client
 
langfuse = get_client()
 
# Create a span using a context manager
with langfuse.start_as_current_observation(as_type="span", name="process-request") as span:
    # Your processing logic here
    span.update(output="Processing complete")
 
    # Create a nested generation for an LLM call
    with langfuse.start_as_current_observation(as_type="generation", name="llm-response", model="gpt-3.5-turbo") as generation:
        # Your LLM call logic here
        generation.update(output="Generated response")
 
# All spans are automatically closed when exiting their context blocks
 
 
# Flush events in short-lived applications
langfuse.flush()

from langfuse import get_client
 
langfuse = get_client()
 
# Create a span without a context manager
span = langfuse.start_span(name="user-request")
 
# Your processing logic here
span.update(output="Request processed")
 
# Child spans must be created using the parent span object
nested_span = span.start_span(name="nested-span")
nested_span.update(output="Nested span output")
 
# Important: Manually end the span
nested_span.end()
 
# Important: Manually end the parent span
span.end()
 
# Flush events in short-lived applications
langfuse.flush()

Install packages

Install the packages that power tracing with OpenTelemetry:

npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

Learn more about the packages here.

Set environment variables

Add your Langfuse credentials to your environment. Make sure that you have a .env file in your project root and a package like dotenv to load the variables.

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://cloud.langfuse.com" # 🇪🇺 EU region
# LANGFUSE_BASE_URL = "https://us.cloud.langfuse.com" # 🇺🇸 US region

Initialize OpenTelemetry

Create an instrumentation.ts to register the Langfuse span processor so traces reach Langfuse.

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
 
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
 
sdk.start();

Import this file at the top of your app’s entry point (e.g., index.ts).

Instrument your app

Use a Langfuse integration or manual instrumentation. The startActiveObservation helper manages the OpenTelemetry context for you.

import "./instrumentation";
import { startActiveObservation } from "@langfuse/tracing";
 
async function main() {
  await startActiveObservation("my-first-trace", async (span) => {
    span.update({
      input: "Hello, Langfuse!",
      output: "This is my first trace!",
    });
  });
}
 
main();

Run your application

Execute your application and the trace will appear in Langfuse.

npx tsx index.ts

npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

The Langfuse SDK is designed to be modular. Here’s an overview of the available packages:

import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
 
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
 
sdk.start();

Configure tracing via environment variables (see above) and by passing options to LangfuseSpanProcessor, e.g. mask, shouldExportSpan, or exportMode. Advanced options such as sampling, isolated tracer providers, serverless flushing, and multi-project exports are covered in Advanced features.

All key configuration options are listed in the JS/TS SDK reference.

The Langfuse client is a singleton. It can be accessed anywhere in your application using the get_client() function.

Optionally, you can initialize the client via Langfuse() to manually pass in the Langfuse credentials. Otherwise, it is created automatically when you call get_client() based on environment variables.

from langfuse import get_client
 
# Get the default client
client = get_client()

from langfuse import Langfuse
 
langfuse = Langfuse(
  public_key="pk-lf-...", 
  secret_key="sk-lf-...",
  base_url="https://cloud.langfuse.com"
)

Use LangfuseClient for non-tracing APIs (datasets, prompts, scores). Environment variables are picked up automatically.

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

import { LangfuseClient } from "@langfuse/client";
 
const langfuse = new LangfuseClient({
  publicKey: "your-public-key",
  secretKey: "your-secret-key",
  baseUrl: "https://cloud.langfuse.com",
});