npm.io
6.0.1 • Published 3d ago

@langfuse/otel

Licence
MIT
Version
6.0.1
Deps
1
Size
196 kB
Vulns
0
Weekly
0
Stars
169
SummaryDependencyVersions

GitHub Banner

@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.

This is the current SDK generation (@langfuse/* scoped packages). The unscoped langfuse npm package is the legacy v3 SDK — for new integrations use @langfuse/tracing + @langfuse/otel. Migration guides: v3 → v4, v4 → v5.

Install

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

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

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();

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.

Packages

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

Documentation

License

MIT