LLM engineering on a real observability database

Quickstart · Deployment · Operations · Architecture · Known limitations · 中文

Openfuse is a fork of Langfuse that swaps the analytics store from ClickHouse to GreptimeDB. The Langfuse product, public APIs, and SDKs stay the same; GreptimeDB becomes the source of truth for traces, observations, scores, and the analytics behind dashboards.

Why GreptimeDB

LLM traces are observability data: timestamped wide events with high-cardinality context. That is exactly GreptimeDB's data model. GreptimeDB is a unified observability database — metrics, logs, and traces in one engine, SQL and PromQL/TQL queryable, OTLP-native, with compute–storage separation over object storage. Running Langfuse on it, instead of on a single-purpose columnar store, buys two things today:

• Start small, scale as you grow. Begin with a single openfuse-standalone container — the GreptimeDB-standalone analogue. GreptimeDB persists to local disk or object storage, and the same engine scales from one node to a cluster as your data grows; scaling down loses no data. Object storage is optional: ingestion needs no S3 or MinIO.
• Cheap long retention. Object-storage-native tiered storage plus a plain-SQL database TTL (LANGFUSE_GREPTIME_TTL) make multi-month or multi-year retention affordable — a sore point for ClickHouse-backed Langfuse, where configurable data retention is an Enterprise feature. The TTL here is deployment-wide, not per-project.

It also opens a direction that a single-purpose store cannot. Because the events already live in a real observability database, GreptimeDB could take Openfuse beyond Langfuse parity: PromQL-native metrics, logs ↔ traces correlation, OTLP-native ingestion, and Flow continuous aggregation for pre-computed rollups. These are directional and not delivered — tracked as ideas in issue #8, not features you can use today.

Screenshots

The full Langfuse UI, served entirely from GreptimeDB.

Home dashboard — traces, model cost, scores, latency analytics	Trace detail — nested observation tree
Traces list	Session view

What works today

• Your Langfuse SDKs work unchanged. Point any existing Langfuse SDK — or any OpenTelemetry tracer — at Openfuse, and your traces, observations, and scores land with zero code changes.
• The full tracing UI. Explore traces and nested observations, sessions, and users, with the same search and filtering you have in Langfuse.
• Dashboards and metrics. Cost, token usage, latency percentiles, and score analytics — filtered and broken down by metadata, tags, and tools. Covered parity cases match upstream Langfuse; intentional differences are documented in the parity report.
• Datasets, experiments, and evals. The evaluation workflow works end to end.
• Edit, delete, and export. UI edits, deletions, and data exports behave as you'd expect, including full project deletion.
• Self-host in one container. The standalone image brings up the whole stack and prepares its storage on first start — no manual database steps.

5-minute quickstart (Docker Compose)

Requirements: Docker and Docker Compose. The quickest path is the published single openfuse-standalone image — web + worker in one process — wired to Postgres, Redis, and GreptimeDB. Both schemas migrate automatically on startup; object storage is off by default.

git clone https://github.com/tma1-ai/openfuse.git
cd openfuse
cp .env.quickstart.example .env
OPENFUSE_STANDALONE_IMAGE=tma1ai/openfuse-standalone:1.0.0-alpha.2 \
  docker compose -f docker-compose.standalone.yml up -d --pull always

Open http://localhost:3000. The quickstart env auto-creates a demo project, so you can log in as demo@example.com / langfuse-dev or point any Langfuse SDK at the bundled keys (pk-lf-1234567890 / sk-lf-1234567890) right away. Those values are insecure dev defaults — for a real deployment start from .env.prod.example and set your own secrets, including a GreptimeDB password (GREPTIME_PASSWORD) to turn on enforced auth on the analytics store. Full guide: deployment.

To build the standalone image from the checkout instead of pulling the published image:

docker compose -f docker-compose.standalone.yml up -d

Split web + worker

To scale web and worker independently, use the default docker-compose.yml (separate openfuse-web and openfuse-worker images) instead:

OPENFUSE_WEB_IMAGE=tma1ai/openfuse-web:1.0.0-alpha.2 \
OPENFUSE_WORKER_IMAGE=tma1ai/openfuse-worker:1.0.0-alpha.2 \
  docker compose up -d --pull always

Project status

Openfuse is in alpha and actively moving toward beta. The ClickHouse → GreptimeDB migration is in place, the read path is parity-checked byte-for-byte against upstream Langfuse, and the full Langfuse product, API, and SDK surface works. Try it, run real workloads against it, and open issues — that feedback is what gets it to beta.

Before you depend on it, skim Known limitations: a short list of real constraints, plus a few intentional differences from upstream where the fork is equal or more correct.

Published images

Release images are published to Docker Hub on each v* tag:

• tma1ai/openfuse-web
• tma1ai/openfuse-worker
• tma1ai/openfuse-standalone — web + worker in one container, for single-node self-hosting

The current preview is 1.0.0-alpha.2. To run the standalone image instead of building locally, pin a tag in .env:

OPENFUSE_STANDALONE_IMAGE=tma1ai/openfuse-standalone:1.0.0-alpha.2

and start with:

docker compose -f docker-compose.standalone.yml up -d --pull always

Full instructions for standalone, split web/worker images, and tag policy: deployment.

Architecture

Postgres holds application and config data (users, projects, prompts, dataset definitions, API keys), unchanged from upstream Langfuse. GreptimeDB is the analytics event store: an append-only raw_events table as the source of truth, plus merged projection tables and indexed EAV side-tables that back metadata, tag, and tool filtering. Redis runs the BullMQ queues. Object storage (S3/MinIO) is optional for the default stack: media uploads, the OTel carrier, and the eval blob store default to local filesystem paths. Opt-in batch/blob exports still need an S3-compatible bucket.

Full write-up: architecture.

Compatibility with Langfuse

Openfuse 1.0.0-alpha.2 is based on upstream Langfuse v3.184.1. Existing Langfuse SDKs and the public ingestion/REST APIs work unchanged. Dashboard and metrics output is checked byte-for-byte against upstream for the covered query surface; the few intentional divergences, all cases where the fork is equal or more correct, are listed in the parity ledger. Postgres migrations are upstream Langfuse's and apply as-is; the GreptimeDB schema is fork-specific and migrates automatically on container startup (idempotent, advisory-lock serialised, fail-closed).

Openfuse is a community fork and is not affiliated with or endorsed by Langfuse. See migration from Langfuse for the full compatibility statement.

Documentation

• Deployment: self-host with Docker Compose, env, data directories, automatic migrations, standalone and published images.
• Operations: monitoring, performance and compaction, capacity, backup and recovery, upgrades.
• Development: local setup, GreptimeDB schema, targeted tests.
• Architecture: what lives where, and why ClickHouse is gone.
• Known limitations: read before deploying.
• Migration from Langfuse: compatibility and what differs.
• Design history: the migration engineering record (design notes, reviews, parity harness).

Contributing and security

See CONTRIBUTING.md to contribute, and SECURITY.md to report a vulnerability.

License

Openfuse is licensed in full under the MIT license — every feature ships unlocked, with no enterprise tier or commercial license key. It is a community fork of Langfuse and retains upstream copyright and attribution. See LICENSE.