Instrument a Python app end-to-end with the Langfuse Python SDK v4 (install, env vars, client init, auth check, @observe, nesting, flush)

Documented steps

1. Install the SDK: `pip install langfuse`. The current GA major version is Python SDK v4; v3 and v2 are marked Deprecated on Langfuse Cloud v4 per the compatibility matrix. Do not follow v2/v3-only tutorials without checking method names against v4.
2. Set credentials as environment variables (e.g. in `.env`): `LANGFUSE_PUBLIC_KEY=pk-lf-...`, `LANGFUSE_SECRET_KEY=sk-lf-...`, `LANGFUSE_BASE_URL=https://cloud.langfuse.com`. Regional alternatives: us.cloud.langfuse.com, jp.cloud.langfuse.com, hipaa.cloud.langfuse.com. The host MUST match the region your project was created in.
3. Initialize the singleton client from env vars: `from langfuse import get_client` then `langfuse = get_client()`. Or construct explicitly: `Langfuse(public_key=..., secret_key=..., base_url=...)`. Repeated `get_client()`/`Langfuse()` calls with the same public key reuse one singleton instance.
4. Verify credentials before relying on tracing: `if langfuse.auth_check(): print('Langfuse client is authenticated and ready!')`. `auth_check()` returns a bool.
5. Decorate functions to auto-capture input/output/timing/errors: `from langfuse import observe` then `@observe()` on a function, or `@observe(name="llm-call", as_type="generation")` to mark it as a generation-type observation (only GENERATION observations get token/cost tracking).
6. Nest traces automatically: calling one `@observe`-decorated function from inside another (or from inside a `with langfuse.start_as_current_observation(as_type="span", name="...") as span:` block) makes the inner call a child span via OpenTelemetry context propagation. No manual parent/child wiring needed.
7. For manual control, use `span = langfuse.start_observation(name="manual-span")`, `span.update(input=...)`, then `span.end()` explicitly. This does not shift the active OTel context, so the original parent stays active for surrounding code.
8. Before your process exits (scripts, batch jobs, serverless handlers), call `langfuse.flush()` to force delivery of buffered spans. The SDK batches and exports asynchronously in the background; unflushed data is silently lost on exit with no error raised.
9. Filter what gets exported with `should_export_span=` on the `Langfuse()` constructor, e.g. `Langfuse(should_export_span=lambda span: True)` to restore export-everything behavior. The older `blocked_instrumentation_scopes` parameter is deprecated in favor of this.
10. Verified against current official docs on 2026-07-29: https://langfuse.com/docs/observability/sdk/python/overview , https://langfuse.com/docs/observability/sdk/python/instrumentation , https://langfuse.com/docs/compatibility , https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4