Use the Langfuse data model correctly: traces vs observations vs spans vs generations vs events, client-generated IDs, and async ingestion

Documented steps

1. A Trace groups one logical request or operation (for example a single chatbot turn), identified by `trace_id`. It carries attributes such as user_id, session_id, tags, metadata, and name that propagate to its child observations.
2. An Observation is one step inside a trace: an LLM call, tool call, retrieval, or business-logic step. Observations nest via `parent_observation_id` to mirror your application's call structure.
3. Observation type matters: SPAN is a generic timed step or container, GENERATION is an LLM call carrying model, usage, and cost fields, and EVENT is a point-in-time occurrence with no duration. Only GENERATION observations receive token and cost tracking.
4. Storage is denormalized: Langfuse keeps a single Observations table in ClickHouse where trace-level attributes (user_id, session_id, tags, metadata) are already copied onto every observation row, so filtering and aggregation need no join against a separate traces table.
5. IDs are client-generated strings (SDKs default to UUIDs). Reuse the same `trace_id` across multiple spans and generations to group them into one trace, and set `parent_observation_id` to nest them.
6. Ingestion is asynchronous and batched client-side. The recommended write path is native OpenTelemetry ingestion at POST https://<region>/api/public/otel with Basic auth. The older batched /api/public/ingestion endpoint is officially marked deprecated, with the docs strongly recommending switching to the OpenTelemetry endpoint.
7. Always call `flush()`/`force_flush()` in Python, or shut down the tracer provider in JS/TS, before a short-lived process exits (Lambda, CLI, CI), or buffered observations are lost silently.
8. To read data back, prefer SDK query methods such as `langfuse.api.observations.get_many(trace_id=..., type="GENERATION", fields="core,basic,usage")`, or the Observations API v2, Scores API v3, and Metrics API v2, rather than the deprecated GET /api/public/traces.
9. Know the v4 direction: Langfuse v4 (Cloud preview) collapses the model further. Traces become pure correlation IDs, trace-level input/output fields are removed in favor of setting input/output on observations, and `update_current_trace()` is replaced by `propagate_attributes()`. Self-hosted OSS remains on the v3 model.
10. Verified against current official docs on 2026-07-29: https://langfuse.com/docs/observability/data-model , https://langfuse.com/docs/api-and-data-platform/features/public-api