OmniRoute/examples/plugins/langfuse/README.md

Langfuse Plugin

Emits Langfuse generation traces for every LLM completion routed through OmniRoute.

Records prompt, response, model, provider, token usage, latency, and error details to Langfuse cloud (cloud.langfuse.com or us.cloud.langfuse.com) or a self-hosted Langfuse instance.

Install

Copy the examples/plugins/langfuse/ directory to your OmniRoute plugins path, or install directly from the marketplace UI.

Configuration

Fill these fields in the plugin config panel:

Key	Required	Default	Notes
publicKey	Yes	""	Langfuse public key (pk-lf-...)
secretKey	Yes	""	Langfuse secret key (sk-lf-...)
host	No	https://cloud.langfuse.com	Also https://us.cloud.langfuse.com or self-hosted URL
enabled	No	true	Set to false to make the plugin a no-op without uninstalling
sampleRate	No	1.0	0.1 = trace 10% of requests
flushAt	No	15	Events to buffer before flushing
flushInterval	No	10000	Max ms between flushes
redactBody	No	false	Set true to strip prompt + completion from traces (metadata still recorded)

Get keys at cloud.langfuse.com → Settings → API keys.

What gets traced

Each LLM completion emits one Langfuse generation observation inside a per-request trace:

• Trace: omniroute:<model> with userId, provider, requestId metadata
• Generation: chat.completion with:
  • model — full model ID
  • modelParameters — temperature, max_tokens, top_p
  • input — messages array (redacted if redactBody: true)
  • output — assistant message (redacted if redactBody: true)
  • usage.promptTokens, usage.completionTokens, usage.totalTokens
  • startTime, endTime — for latency

Errors emit a generation with level: "ERROR" and statusMessage.

Runtime dependency

The plugin lazy-loads the langfuse npm SDK on first request. Install it in the plugin's own directory so a broken SDK cannot crash the gateway:

cd examples/plugins/langfuse
npm install langfuse

Privacy

• Prompts and completions are sent to Langfuse cloud (or your self-host) in cleartext unless redactBody: true
• API keys are stored in the plugin config, encrypted at rest by OmniRoute
• Set sampleRate < 1.0 to reduce data volume
• Set enabled: false to disable without removing configuration

Related

• Langfuse docs
• Langfuse OpenTelemetry endpoint (alternative path — this plugin uses the native SDK)
• OmniRoute plugin SDK: docs/frameworks/PLUGIN_SDK.md