# Langfuse Setup

> Orchestrates Langfuse adoption decisions and production-readiness — the planning the official `langfuse` skill doesn't cover. Use whenever the user is deciding HOW to adopt Langfuse or whether their setup is ready: "set up Langfuse", "Langfuse Cloud or self-host", "which Langfuse region", "configure Langfuse keys/env", "is my Langfuse setup production ready", "Langfuse prod checklist", "my traces aren't showing up", or planning a Langfuse rollout. Defers instrumentation CODE to the vendored `langfuse` skill — this skill owns the decisions, order, and verification around it.

- Skill: `jbaham2/langfuse-setup` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add jbaham2/langfuse-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jbaham2/langfuse-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: jbaham2 (https://skillmd.com/u/jbaham2)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jbaham2/langfuse-setup

---


# Langfuse Setup & Onboarding

This skill orchestrates *getting onto Langfuse well*: choosing a deployment, sequencing onboarding
so the irreversible decisions are made first, verifying the first trace, and confirming
production-readiness. It is the planning layer around the official `langfuse` skill, which owns the
instrumentation code itself.

## Operating principles

1. **Distill judgment, fetch facts.** This skill carries the durable *decisions and ordering*. For
   anything that goes stale — exact SDK code, config flags, version numbers — fetch the live docs by
   appending `.md` to any page URL (e.g. `https://langfuse.com/docs/observability/get-started.md`)
   or use `https://langfuse.com/api/search-docs?query=...`. Never instrument from memory.
2. **Defer code to the `langfuse` skill.** For instrumentation, CLI usage, prompt migration, and SDK
   upgrades, use the vendored `langfuse` skill (`skills/langfuse/`). Do not duplicate or rewrite that
   guidance here — hand off to it at the right step.
3. **Protect the irreversible decisions.** Deployment + region (data residency) and project/
   environment partitioning are painful to change after data exists. Settle them before ingesting
   real traffic.

## Workflow

### 1. Frame the goal
Determine which case applies:
- **Greenfield / "how should I adopt Langfuse?"** → run the full sequence below.
- **Existing app, just wants tracing in** → fast path: decisions + keys, then hand to the `langfuse`
  skill for instrumentation, then verify + readiness.
- **"Is my setup production-ready?"** → go straight to `references/production-readiness.md`.
- **"Traces aren't showing up"** → verification/troubleshooting in `references/onboarding-sequence.md`
  (step 6); if unresolved, `search-docs` for the specific symptom.

### 2. Decide deployment + region
Use `references/cloud-vs-self-host.md`. Default to Langfuse Cloud unless a hard requirement (data
residency, VPC/air-gap, compliance, very-high-scale cost, EE-on-own-infra) forces self-hosting.
Region is permanent per project — decide before creating anything.

### 3. Walk the onboarding sequence
Follow `references/onboarding-sequence.md` in order: account → project → API keys (into env, never
chat) → instrumentation (hand off to the `langfuse` skill) → first trace → verify → organize
(environments, releases, user/session tagging).

For credentials, give the user `assets/.env.example` to fill in (it lists every region URL and the
required variables) and have them set keys in their shell or `.env` — never paste secret keys into
chat. For the exact env-var semantics (`LANGFUSE_HOST` vs `LANGFUSE_BASE_URL`, etc.), defer to the
vendored `langfuse` skill, which documents them.

### 4. Verify the first trace
Confirm the trace appears in the UI and the SDK auth check passes; ensure short-lived processes flush
before exit. Details in `references/onboarding-sequence.md` (step 6).

### 5. Production-readiness
Before real traffic, walk `references/production-readiness.md` — data retention, PII masking, RBAC,
environment separation, sampling, cost tracking, spend alerts, flush-on-shutdown, and (self-host)
UTC, backups, encryption, health checks, upgrade path.

## Bundled resources

- **`references/cloud-vs-self-host.md`** — deployment decision: when Cloud, when self-host, region
  table, self-host deployment tiers and the architecture/UTC requirement you commit to operating.
- **`references/onboarding-sequence.md`** — the ordered onboarding flow and first-trace verification
  / troubleshooting; explains why the order matters.
- **`references/production-readiness.md`** — pre-production checklist (governance, access, signal
  quality, reliability, self-host specifics), each item linking the live doc for exact config.
- **`assets/.env.example`** — credentials template with all region URLs.

## Hand-off map

| Need | Where |
|------|-------|
| Instrumentation code, CLI, prompt migration, SDK upgrade | vendored `langfuse` skill (`skills/langfuse/`) |
| Exact config for any setting | live docs via `.md`-append or `search-docs` |
| Deployment decision, onboarding order, prod checklist | this skill |