第 5 课的全链路里,第一段是「SDK 创建事件」。这一课就把镜头对准这第一段:在数据还没离开你的应用之前,它是怎么被「埋点」生成的。 你会看到 Langfuse 接收数据的两个入口——一种是用 Langfuse 自家的 SDK 发「原生事件」,另一种是走业界标准的 OpenTelemetry(OTLP)。理解了「应用这头发出的是什么」,后面第三部分「服务端怎么收、怎么处理」才有的放矢。
web/src/pages/api/public/ingestion.ts),或用 OpenTelemetry OTLP 发标准 span(web/src/pages/api/public/otel/v1/traces,span 会被映射成 observation)。两条路最后汇入同一条服务端摄取链路(第三部分)。generation-create 等对齐摄取 API;值为示例):你只在业务代码旁加几行 @observe/update_current_generation,SDK 就把这次调用打包成一个事件信封({id, type, timestamp, body}),攒批后发往服务端——下游所有存储与查询都从这个信封开始。无论走哪条入口,应用发出的本质都是一批事件(event)。Langfuse 定义了一组事件类型(packages/shared/src/server/ingestion/types.ts 的 eventTypes),
每个事件描述「对哪个对象做了什么」:
| 事件类型 | 含义 |
|---|---|
| TRACE_CREATE | 创建/更新一个 trace(整次交互的外壳) |
| SPAN_CREATE / SPAN_UPDATE | 开始 / 结束一个 span 型 observation(有耗时的一段) |
| GENERATION_CREATE | 记录一次 LLM 调用(generation 型 observation) |
| OBSERVATION_CREATE / OBSERVATION_UPDATE | 通用的 observation 创建 / 更新 |
| EVENT_CREATE | 记录一个瞬时事件 |
| SCORE_CREATE | 提交一个 score(评分) |
注意这里有 CREATE 也有 UPDATE——这正是第 5 课「合并」的来源:一个 span 通常先 SPAN_CREATE(开始时),结束时再 SPAN_UPDATE(补上耗时、输出)。
应用把这些事件攒成一批,一次 HTTP 请求发给摄取 API,服务端再去合并。所以你在 SDK 里写的 langfuse.trace(...)、span.end(),
本质上就是在生成这些事件。
概念上,你在应用里写的埋点代码大致长这样(不同语言 SDK 形态略有差异,这里只示意「调用 → 事件」的对应关系;图中 langfuse.trace()/.generation() 是显式写法,现代 Python SDK 多用 @observe 装饰器,底层产生同样的 CREATE/UPDATE 事件):
# 创建一个 trace(发出 TRACE_CREATE) trace = langfuse.trace(name="chat", user_id="u_42") # 在 trace 下记录一次 LLM 调用(发出 GENERATION_CREATE) gen = trace.generation(name="answer", model="gpt-4o", input=prompt) result = call_llm(prompt) # 调用结束,补上输出与用量(发出 OBSERVATION_UPDATE) gen.end(output=result, usage={"input": 800, "output": 440}) # 给这次回答打个分(发出 SCORE_CREATE) trace.score(name="helpfulness", value=0.9)
关键观察:你只是在原有业务代码旁边「顺手记一笔」,并没有改变 call_llm 本身的逻辑。好的埋点应当尽量不侵入——
它不该决定你的应用怎么跑,只是旁观并记录。这也呼应了第 1 课的定位:Langfuse 站在你应用旁边,而不是里面。
正因为埋点是「旁路」的,它出问题(比如网络抖动发不出去)也不应拖垮你的主流程——SDK 通常会异步、批量、失败可丢地发送,把对应用的影响压到最低。把交互拆成「一串带类型的小事件」而不是「一个大对象」,正是为了让它们能分批、增量、乱序地发送。
那「一串带类型的小事件」到底长什么样?源码里每个事件都是同一个信封:一个 base(id + timestamp + metadata),再 extend 出 type(取值来自 eventTypes 映射)和 body(这种类型特有的字段)。一次 LLM 调用,SDK 可能发 generation-create 起头、generation-update 收尾——同一个信封、不同的 type,分批送达,worker 再按 id 合并(第 5 课已预演过)。
// 每个上报事件都是「同一个信封」:base + type + body const base = z.object({ id: idSchema, // 这条事件的唯一 id timestamp: z.iso.datetime({ offset: true }), // 何时发生(合并冲突以更晚者为准) metadata: jsonSchema.nullish(), }); const generationCreateEvent = base.extend({ type: z.literal(eventTypes.GENERATION_CREATE), // 信封上的「类型」标签 body: CreateGenerationBody, // 这种类型特有的字段 }); // type 的合法取值(节选)——一次交互拆成这些小事件 export const eventTypes = { TRACE_CREATE: "trace-create", SCORE_CREATE: "score-create", GENERATION_CREATE: "generation-create", GENERATION_UPDATE: "generation-update", SPAN_CREATE: "span-create", EVENT_CREATE: "event-create", … } as const;
为什么要同时支持两条入口?因为它们服务两类用户:
Langfuse 官方的 Python/JS SDK,直接发上面那套原生事件。信息最全、最贴合(prompt 关联、用量、成本字段都能精确上报),是大多数人的首选。入口:ingestion.ts。
如果你的系统已经用 OTel 做可观测,不想再引一套 SDK,就可以把 OTel 的 span 直接发到 Langfuse 的 OTLP 端点(otel/v1/traces)。Langfuse 把标准 span 映射成 observation。代价是有些 Langfuse 专有语义要靠约定俗成的属性名传递。
这是一个典型的「拥抱标准 vs 发挥专长」的权衡。OTel 是云原生可观测的事实标准,支持它意味着 Langfuse 能无缝接入已有的 OTel 生态—— 你不必为了用 Langfuse 就把埋点全部重写。但 OTel 的通用模型并不天然懂「prompt 版本」「token 用量」这些 LLM 专有概念,所以原生 SDK 在表达力上仍更强。 Langfuse 的选择是两者都要:用 OTLP 降低接入门槛,用原生 SDK 提供最佳体验。OTel 这条路的服务端处理,单独放在第 18 课讲。
再强调一遍这个对理解整条链路至关重要的点:一个 observation 的信息往往不是一次发齐的。看一次 LLM 调用的典型时间线:
CREATE 与 UPDATE 被 worker 合并成同一条最终 observation。这就是为什么 SDK 那头可以「拆开发」、而你在 UI 里看到的却是完整的一条。为什么要这样「增量」上报,而不是等全部结束再发一条完整的?因为这样应用能更早地把「开始了」这件事记下来——即使后面调用崩了、超时了, 你至少知道「它确实开始过、卡在了这一步」。如果非要等结束才发,那一旦中途挂掉,这一步就彻底消失,反而最该被观测的失败 case 被漏掉了。 增量上报 + 服务端合并,是「边发生边记录」的可观测理念在协议层的体现。
ingestion.ts,表达力最强)或 OpenTelemetry OTLP(otel/v1/traces,无缝接入已有 OTel)。eventTypes):TRACE_CREATE / SPAN_CREATE / GENERATION_CREATE / OBSERVATION_UPDATE / SCORE_CREATE …,描述「对哪个对象做了什么」。In Lesson 5's pipeline, the first leg was "SDK creates events". This lesson focuses on that first leg: how, before data ever leaves your app, it gets instrumented into existence. You'll see Langfuse's two entry points — sending "native events" via the Langfuse SDK, or sending standard OpenTelemetry (OTLP). Understanding "what the app side emits" makes Part 3 ("how the server receives and processes it") land.
web/src/pages/api/public/ingestion.ts), or standard spans via OpenTelemetry OTLP (web/src/pages/api/public/otel/v1/traces, spans mapped to observations). Both converge on the same server-side ingestion path (Part 3).generation-create per the ingestion API; values illustrative): you add a few @observe/update_current_generation lines beside your business code, and the SDK packages the call into an event envelope ({id, type, timestamp, body}), batches it, and sends it server-side — every downstream store and query starts from this envelope.Whichever entry, the app essentially emits a batch of events. Langfuse defines a set of event types
(eventTypes in packages/shared/src/server/ingestion/types.ts), each describing "what was done to which
object":
| Event type | Meaning |
|---|---|
| TRACE_CREATE | create/update a trace (the interaction's shell) |
| SPAN_CREATE / SPAN_UPDATE | start / end a span-type observation (a timed unit) |
| GENERATION_CREATE | record an LLM call (generation-type observation) |
| OBSERVATION_CREATE / OBSERVATION_UPDATE | generic observation create / update |
| EVENT_CREATE | record an instantaneous event |
| SCORE_CREATE | submit a score |
Note there's both CREATE and UPDATE — this is the source of Lesson 5's "merge": a span usually starts with
SPAN_CREATE and ends with SPAN_UPDATE (adding duration, output). The app batches these events
into one HTTP request to the ingestion API, and the server merges them. So your langfuse.trace(...) and
span.end() calls are essentially generating these events.
Conceptually, your instrumentation code looks roughly like this (SDK shapes differ by language; this just shows the "call →
event" mapping; the langfuse.trace()/.generation() calls shown are an explicit illustration — modern Python SDKs use the @observe decorator, which emits the same CREATE/UPDATE events):
# create a trace (emits TRACE_CREATE) trace = langfuse.trace(name="chat", user_id="u_42") # record an LLM call under the trace (emits GENERATION_CREATE) gen = trace.generation(name="answer", model="gpt-4o", input=prompt) result = call_llm(prompt) # call ends; add output and usage (emits OBSERVATION_UPDATE) gen.end(output=result, usage={"input": 800, "output": 440}) # score this answer (emits SCORE_CREATE) trace.score(name="helpfulness", value=0.9)
Key observation: you merely "jot a note alongside" your existing business code — you didn't change
call_llm's logic. Good instrumentation is as non-intrusive as possible — it shouldn't dictate how your app
runs, only observe and record. This echoes Lesson 1: Langfuse sits beside your app, not
inside it. Because instrumentation is "side-channel", its failure (e.g. a network hiccup) shouldn't take down your
main flow — SDKs typically send asynchronously, batched, drop-on-failure, minimizing impact on the app.
So what does "a stream of typed little events" actually look like? In the source, every event is the same envelope: a base (id + timestamp + metadata), then extended with a type (a value from the eventTypes map) and a body (the fields specific to that type). One LLM call may have the SDK send a generation-create to start and a generation-update to finish — same envelope, different type, sent in batches, merged by id by the worker (rehearsed in Lesson 5).
// every reported event is "the same envelope": base + type + body const base = z.object({ id: idSchema, // unique id of this event timestamp: z.iso.datetime({ offset: true }), // when it happened (later wins on merge) metadata: jsonSchema.nullish(), }); const generationCreateEvent = base.extend({ type: z.literal(eventTypes.GENERATION_CREATE), // the "type" tag on the envelope body: CreateGenerationBody, // fields specific to this type }); // the valid values of type (excerpt) — one interaction split into these little events export const eventTypes = { TRACE_CREATE: "trace-create", SCORE_CREATE: "score-create", GENERATION_CREATE: "generation-create", GENERATION_UPDATE: "generation-update", SPAN_CREATE: "span-create", EVENT_CREATE: "event-create", … } as const;
Why support both? Because they serve two kinds of users:
The official Python/JS SDKs emit the native events above. Richest, best-fit signal (prompt linkage, usage, cost reported precisely), the default for most. Entry: ingestion.ts.
If your system already uses OTel for observability and you'd rather not add another SDK, send OTel spans to Langfuse's OTLP endpoint (otel/v1/traces). Langfuse maps standard spans to observations. The cost: some Langfuse-specific semantics ride on convention-based attribute names.
This is a classic "embrace the standard vs play to your strengths" trade-off. OTel is the de-facto standard for cloud-native observability, so supporting it lets Langfuse plug into existing OTel ecosystems — you needn't rewrite all your instrumentation to adopt Langfuse. But OTel's generic model doesn't natively understand LLM-specific concepts like "prompt version" or "token usage", so the native SDK is still more expressive. Langfuse chooses both: OTLP lowers the barrier, the native SDK gives the best experience. The server-side handling of the OTel path is its own Lesson 18.
Once more, a point crucial to understanding the whole path: an observation's info often isn't sent all at once. Look at a typical LLM call timeline:
CREATE and UPDATE arriving at different times are merged by the worker into one final observation. That's why the SDK can "send in pieces" while you see one complete row in the UI.Why report "incrementally" instead of waiting and sending one complete event at the end? So the app can record "it started" earlier — even if the call later crashes or times out, you at least know "it did start and got stuck here". Wait until the end and a mid-flight crash makes that step vanish entirely, losing exactly the failure cases most worth observing. Incremental reporting + server merge is the protocol-level expression of "record as it happens" observability.
ingestion.ts, most expressive) or OpenTelemetry OTLP (otel/v1/traces, plugs into existing OTel).eventTypes): TRACE_CREATE / SPAN_CREATE / GENERATION_CREATE / OBSERVATION_UPDATE / SCORE_CREATE …, describing "what was done to which object".