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