| name | langfuse |
| description | Premortem Langfuse integration for managed prompts, traces, and eval scores. Use when wiring LLM observability, prompt versioning, or post-eval scoring in agent pipelines. |
Langfuse (Premortem)
Langfuse is the repo's optional LLM observability layer for managed prompts and eval scores. Sentry and PostHog remain the primary product observability stack.
Canonical code paths
- Client and helpers:
packages/observability/src/langfuse.ts
- Exports:
packages/observability/src/index.ts
- Env vars:
.env.example (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL)
When to use
- Fetch a versioned prompt from Langfuse with a local fallback
- Record eval or human-review scores against a trace after promptfoo or manual QA
- Confirm Langfuse is configured before enabling managed-prompt paths
When Langfuse is off
If keys are unset, getLangfuseClient() returns null and getManagedPrompt() falls back to repo-local prompt files under .agents/prompts/. Do not block builds or runtime on Langfuse availability.
Managed prompt pattern
import { getManagedPrompt } from '@premortem/observability';
const prompt = await getManagedPrompt('finding-synthesizer', {
label: 'production',
fallback: localPromptText
});
Scoring pattern
import { createLangfuseScore } from '@premortem/observability';
await createLangfuseScore({
traceId,
name: 'promptfoo_regression',
value: 1,
comment: 'Passed canonical finding synthesizer eval'
});
Rules
- Prefer repo-local prompts as the source of truth until a prompt is explicitly promoted in Langfuse.
- Do not store secrets or PII in Langfuse prompt metadata.
- Keep prompt names aligned with
.agents/prompts/ filenames and @premortem/evals fixtures.
- Use
shutdownLangfuse() / flushAsync() on graceful shutdown in long-running workers when tracing is enabled.
Verification
node scripts/canonical/verify-stack.mjs
pnpm --filter @premortem/observability build
Upstream
