Langfuse tracing

Langfuse is an open-source LLM engineering platform for traces, evaluations and prompt management, offered as Langfuse Cloud or self-hosted. @mayurajs/observability-langfuse presets Mayura's OTLP trace exporter (mayura/exporter-otlp) for Langfuse's OpenTelemetry endpoint: its URL, its authentication and its ingestion version. It sends OTLP/HTTP JSON with fetch: no Langfuse SDK, no dependencies besides mayura, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/observability-langfuse

#Credentials

Langfuse authenticates with a project's key pair: a public key (pk-lf-…) and a secret key (sk-lf-…). Create them in Langfuse under the project's Settings, API Keys. The keys belong to one project, so the traces land in that project. The package reads nothing from the environment: pass the keys in yourself, for example from LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY.

#Use it

Follow a run with an observer, then turn its events into spans with agentRunTraceSpans and give them to the exporter's sink:

import { createObserver } from 'mayura/observability';
import { agentRunTraceSpans } from 'mayura/exporter-otlp';
import { langfuseTraceExporter } from '@mayurajs/observability-langfuse';

const langfuse = langfuseTraceExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY ?? '',
  secretKey: process.env.LANGFUSE_SECRET_KEY ?? '',
  region: 'eu',
  serviceName: 'support-agent',
});
// Keep enough events per run to pair every call's start and completion.
const observer = createObserver({ maxRecentEventsPerRun: 256 });

const handle = runtime.submit(agent, { input: { question: 'Where is order 42?' } });
const observation = observer.observe(handle);
await handle.result();
await observation.done();

const spans = agentRunTraceSpans(observer.inspect(handle.id)?.recent ?? []);
if (spans.length > 0) await langfuse.sink(spans, { signal: AbortSignal.timeout(10_000) });
console.log(langfuse.inspect().metrics.recordsAccepted);

The exporter is not a tool, so a run needs no permission string for it: it runs in your code after the run settles.

For durable workflows, give a second exporter's sink to createWorkflowTraceExport; each export needs its own instance, because an exporter sends one request at a time:

import { createWorkflowTraceExport } from 'mayura/workflows';
import { langfuseTraceExporter } from '@mayurajs/observability-langfuse';

const workflowTraces = createWorkflowTraceExport({
  source: host.runtime,
  store,
  scope,
  exportId: 'langfuse',
  definitions,
  sink: langfuseTraceExporter({ publicKey, secretKey, region: 'eu', serviceName: 'orders' }).sink,
});

See Trace durable workflow runs for the worker unit, track and nesting an agent's spans under the step that ran it.

#Options

#Endpoint and authentication

With baseUrl, the exporter appends /api/public/otel/v1/traces to your URL. The URL must be HTTPS (or loopback HTTP with allowInsecureLoopback) and carry no credentials, query or fragment.

Every request carries Authorization: Basic <base64 of publicKey:secretKey> and x-langfuse-ingestion-version: 4, which makes spans visible in Langfuse at once instead of after a delay.

#What is sent

Each span is metadata from the run's events: names, ids, timing, statuses and integers from a fixed attribute catalog. Langfuse reads the OpenTelemetry GenAI attributes on them, so a run shows as an agent trace with its model and tool calls:

• agent:<agent id> for the run, with gen_ai.operation.name: invoke_agent, gen_ai.agent.id and gen_ai.agent.name.
• model.call for each model call, with gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.input_tokens and gen_ai.usage.output_tokens (when the provider reports them), and the call's mayura.cost.micros.
• tool:<tool id> for each tool call, with gen_ai.tool.name and gen_ai.tool.call.id.

No prompt, message, tool input, tool output or error text is sent: the catalog has no field that could carry them.

#Delivery and limits

• One sink call is one HTTP request of at most maxBatchSize spans. Split a larger run into several calls.
• The exporter sends one request at a time; a second call while one is in flight is refused with CONFLICT.
• It never retries and follows no redirects. A failed batch is dropped and counted.
• inspect() returns { state, inFlight, metrics }. The metrics count batchesAttempted, recordsAttempted, recordsAccepted, recordsDropped, partialResponses, failedRequests, timedOutRequests, cancelledRequests, requestBytes and responseBytes. Headers and keys are never shown.
• close() aborts the request in flight and refuses later calls.

#With your OpenTelemetry SDK

If your application already runs an OpenTelemetry SDK that exports to Langfuse, you can send Mayura's spans through it with createOpenTelemetryTraceBridge instead of this package. The spans carry the same GenAI attributes either way.

#Errors

Failures reach you as a MayuraError with a code. None of them repeats your keys or Langfuse's reply text.

A reply that reports some spans rejected (OTLP partial success) resolves normally and counts them in recordsDropped and partialResponses.

#How it is tested

• Unit tests run the exporter against a fake fetch that checks the endpoint for each region and a self-hosted URL, the Basic authorization and ingestion-version headers, and that the body carries the GenAI attributes.
• They also check refused keys, regions and URLs, a rejected request and a cancelled export, and that no error or inspect() result contains the secret key.
• scripts/live/observability-langfuse.mjs sends one agent run's spans to Langfuse Cloud: Langfuse accepted them on October 6, 2026.

#Related

• Observability: observers, the OTLP exporters and trace projections.
• LangSmith tracing and Arize AX and Phoenix tracing: other AI tracing backends.
• Durable workflows: runs whose traces createWorkflowTraceExport sends.