The Problem

Teams building LLM‑based products need a single place to capture traces, compute metrics, run evaluations, and manage prompts – without stitching together separate observability, prompt‑management and dataset tools. Langfuse addresses this by bundling observability, evals, prompt‑registry and dataset handling in one open‑source platform.

What This Does

  • web/ (1540 files, 1484 code files) – Next.js/React UI for viewing traces, running the playground, managing datasets and billing (EE). Key UI modules live under web/src/components, web/src/features/dashboard and web/src/ee/features/billing.
  • packages/ (875 files, 840 code files) – Shared TypeScript library containing the core domain model, DB schema, encryption, and Zod validation. Entry points such as packages/shared/src/domain/index.ts and packages/shared/src/encryption/index.ts are imported by both the worker and the web front‑end.
  • worker/ (232 files, 219 code files) – Background job processor (Redis‑queued) that handles migrations, secret encryption and LLM‑request routing. Notable file worker/src/backgroundMigrations/encryptBlobStorageSecrets.ts performs the secret‑shaped path audit mentioned in the heuristic issues.
  • ee/ (8 files, 3 code files) – Enterprise‑only licensing and feature‑flag gate kept at ee/src/index.ts and ee/src/ee-license-check/index.ts.
  • .claude/ (30 files, 2 code files) – Claude‑hook configuration used by the internal assistant tooling.

The platform integrates with OpenTelemetry, LangChain, the OpenAI SDK and LiteLLM, exposing a unified API surface that the UI and worker consume.

How It Is Wired

The internal import graph resolves 1490 modules with 922 edges; 55 modules live inside circular dependencies.

  • Hub modules (52 modules depend on each):
  • packages/shared/src/server/logger.ts – central logging abstraction.
  • packages/shared/src/utils/zod.ts – Zod schema definitions used across the codebase.
  • packages/shared/src/db.ts – database client and query builders.
  • Import cycles (51 modules): the cycle includes packages/shared/src/db.ts, packages/shared/src/domain/index.ts, and packages/shared/src/tableDefinitions/index.ts. Changing any of these requires careful re‑wiring because many downstream modules rely on the mutual reachability.
  • Entry point: ee/src/index.ts bootstraps the server, which then mounts the Express/Next app (packages/shared/src/server/index.ts). The worker starts from worker/src/index.ts (implied by the worker directory) and processes Redis‑queued jobs.
  • External touches: the platform emits OpenTelemetry spans, writes to PostgreSQL (via packages/shared/src/db), caches results in Redis (packages/shared/src/server/redis/getQueue), and serves API requests from web/src/pages/api/....

A change to the hub logger or DB schema ripples through 52+ dependent modules, illustrating the “blast radius” risk highlighted in the analysis.

How To Use It

Setup

# Install dependencies (pnpm is the declared package manager)
pnpm install

# Start the full stack (Docker Compose file present)
docker compose -f docker-compose.dev.yml up -d

The docker-compose.dev.yml file provisions Redis, PostgreSQL and the worker; the web UI becomes reachable at http://localhost:3000.

Configuration Copy .env.dev.example to .env.dev and set the following variables (the file lists the required keys):

  • DATABASE_URL – PostgreSQL connection string used by packages/shared/src/db.ts.
  • REDIS_URL – Redis endpoint for the worker queue.
  • OPENAI_API_KEY / ANTHROPIC_API_KEY – credentials for LLM providers.

Running it

  • To start just the API and UI: pnpm dev (as defined in the root package.json scripts).
  • To run only the background worker: pnpm worker:start (script references worker/src/index.ts).

Real‑World Use

A machine‑learning team instrumenting a RAG pipeline can instrument calls with the Langfuse SDK, which automatically creates traces stored in the platform’s PostgreSQL backend. The team then:

  1. Create a dataset via the UI (web/src/features/datasets) – a CSV of input/prompt pairs.
  2. Run an evaluation that queries the dataset, invokes the LLM through the SDK, and records cost, latency and correctness metrics.
  3. Inspect results in the playground (web/src/playground) and iterate on prompt templates stored under packages/shared/src/utils/chatml.

The same workflow works for both Langfuse Cloud (SaaS) and a self‑hosted instance (Docker compose).

Code Health & Issues

Measured static‑analysis findings (159 total)

  • [HIGH/clarity] Hub module x3 – packages/shared/src/server/logger.ts, packages/shared/src/utils/zod.ts, packages/shared/src/db.ts; 52 modules depend on each, high‑blast‑radius churn.
  • [HIGH/soundness] Import cycle member x51 – modules packages/shared/src/db.ts, packages/shared/src/domain/index.ts, packages/shared/src/tableDefinitions/index.ts participate in a circular import dependency.
  • [MEDIUM/cognitive_load] High branching density x4 – web/src/components/trace2/lib/types.ts, web/src/ee/features/billing/components/useBillingInformation.tsx, web/src/features/score-analytics/lib/ScoreChartTooltip.tsx each have 15 branch points over ~41 lines.
  • [HIGH/clarity] Duplicated code blocks – 128 repeated 6‑line blocks across 93 files, including web/src/utils/chatml/adapters/index.ts and packages/shared/src/utils/chatml/index.ts.
  • [MEDIUM/cognitive_load] Deep nesting – web/src/ee/features/billing/components/SpendAlerts/SpendAlertDialog.tsx max indentation depth 6.

SDLC / repository‑level observations (derived from file‑structure checks)

  • Secret‑shaped paths present: worker/src/backgroundMigrations/encryptBlobStorageSecrets.ts (flagged in the audit).
  • CI/CD runs GitHub Actions; Dockerfiles exist for dev and production.
  • Committed secrets confirmed (the audit flagged secret‑shaped paths).
  • Licensing: MIT license file present at root.

The Bottom Line

Langfuse delivers a rare all‑in‑one open‑source stack for LLM observability, prompt management and evaluation, with a solid TypeScript foundation and Docker‑based dev experience. The main risks are the tightly‑coupled hub modules and circular imports in the shared package, which raise the cost of any schema or logging change; the CORS wildcard in worker/src/app.ts and the unpinned GitHub Actions also merit immediate attention. It is well‑suited for teams that need integrated tracing + evals without managing separate SaaS contracts, provided they invest in decoupling the shared core before scaling.