@langfuse/otel

Langfuse is the open-source LLM engineering platform: tracing & evaluation for LLM and agent applications, prompt management, datasets & experiments, and evaluation (scores). This package provides the LangfuseSpanProcessor — the OpenTelemetry span processor that exports spans to Langfuse with smart filtering, masking, and media upload. Register it with any OTel setup and spans from @langfuse/tracing, the Vercel AI SDK, or any other GenAI instrumentation are sent to Langfuse. Prompt management, datasets/experiments, and evals/scores live in @langfuse/client.

Install

npm install @langfuse/otel @opentelemetry/sdk-trace-node
Copy

Environment variables

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

The batch byte limit applies to the final serialized OTLP/HTTP JSON request before compression. If a batch exceeds the limit, the entire batch is dropped; it is not split, retried, or truncated. Invalid values fall back to 64 MiB with a warning. Set the limit to a positive decimal safe integer; surrounding whitespace is ignored. Custom exporters passed to LangfuseSpanProcessor bypass this limit because they may use a different wire format or transport. The limit is approximate: it is compared against the batch's character count, which is never larger than the request, so a batch that fits is never dropped, but a sent request can be somewhat larger than the limit.

Span exports are gzip-compressed by default on Node.js and Bun. To send uncompressed requests, set the compression: "none" option, LANGFUSE_OTEL_COMPRESSION="none", or OTEL_EXPORTER_OTLP_TRACES_COMPRESSION / OTEL_EXPORTER_OTLP_COMPRESSION to "none".

Quickstart

import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

export const langfuseSpanProcessor = new LangfuseSpanProcessor();

const tracerProvider = new NodeTracerProvider({
  spanProcessors: [langfuseSpanProcessor],
});

tracerProvider.register();
Copy

By default the processor exports Langfuse SDK spans, spans with gen_ai.*/ai.* attributes, and spans from known LLM instrumentation libraries — pass shouldExportSpan to override.

Serverless / short-lived environments (Vercel, AWS Lambda, Cloudflare Workers, edge): pass exportMode: "immediate" so spans are not held in a batch, and await langfuseSpanProcessor.forceFlush() before the function instance is frozen or terminated (e.g. inside Vercel's after() or the platform's waitUntil()). Spans still buffered when the process exits are lost.

Skills

Attach available skills to spans to display them on generation observations in Langfuse.

import { LangfuseSpanProcessor } from "@langfuse/otel";
import { discoverSkills } from "@langfuse/otel/node";
import { propagateAttributes } from "@langfuse/tracing";

export const langfuseSpanProcessor = new LangfuseSpanProcessor({
  skills: { available: await discoverSkills({ dir: ".agents/skills" }) },
});

await propagateAttributes({ attachSkills: true }, () => runAgent());
Copy

The discovery helper reads langfuse-skills.lock from the configured directory or working directory and supports Node.js, Bun, and Deno through node:fs.

Packages

Package	NPM	Description	Environments
@langfuse/tracing		OpenTelemetry-based tracing instrumentation	Node.js 22+
@langfuse/otel		LangfuseSpanProcessor to export OpenTelemetry spans to Langfuse	Node.js 22+
@langfuse/client		Prompt management, datasets, experiments, scores, full REST API	Universal JS
@langfuse/openai		observeOpenAI wrapper for tracing the OpenAI SDK	Universal JS
@langfuse/langchain		CallbackHandler for LangChain / LangGraph tracing	Universal JS
@langfuse/vercel-ai-sdk		Telemetry integration for Vercel AI SDK v7	Universal JS
@langfuse/browser		Browser score ingestion with public-key auth	Browser
@langfuse/core		Shared core: generated API client, logger, utilities	Universal JS

Documentation

• Docs: https://langfuse.com/docs/observability/sdk/overview
• Vercel AI SDK / Next.js guide: https://langfuse.com/integrations/frameworks/vercel-ai-sdk
• Reference: https://js.reference.langfuse.com
• LLM/agent-readable docs index: https://langfuse.com/llms.txt

License

MIT