🪢 Langfuse 图解教程Langfuse Visual Guide 术语表 · 63 个概念Glossary · 63 concepts
术语表 / 概念索引Glossary / Concept index

核心概念速查Core concepts at a glance

每个核心概念一句话定义,点右侧「课」跳到首次讲解它的那一课。用上方搜索框过滤。A one-line definition for each core concept; click the lesson on the right to jump to where it's introduced. Filter with the search box above.

第一部分 · 宏观全景

术语一句话定义课
宽事件把一次操作的全部上下文(输入/输出/模型/用量/耗时)塞进一行又宽又富的事件,保住高基数以事后任意切片L02
可观测性 2.0以宽事件为唯一分析单位、记录一切,取代 metrics/logs/traces 三件套L02
unknown unknowns事前没想到要问的问题;宽事件+高基数让你事后仍能回答L02
trace一次完整调用的根、关联句柄,挂载多个 observationL03
observationtrace 里的一步(SPAN/EVENT/GENERATION… 共 10 型),真正承载数据L03
score评估的原子单位(name/value/dataType/source),挂在 trace 或 observation 上L03
窄腰依赖web/worker/ee 都依赖 shared,shared 不反向依赖——单向收口L04
异步摄取请求只落 S3 + 入 Redis 队列就返回,重活交给后台 worker——削峰、解耦、可重试L05

第二部分 · 前置基础

术语一句话定义课
事件信封摄取事件的统一外壳(id/type/timestamp/body),body 按类型判别联合L06
OLTP vs OLAP事务型(精确单条+强一致, Postgres) vs 分析型(海量扫描聚合, ClickHouse)L07
控制面 / 数据面Postgres 存配置元数据(控制面),ClickHouse 存遥测洪流(数据面)L07
ReplacingMergeTreeClickHouse 引擎:同主键后写覆盖先写,查询时合并去重保留最新L08
排序键ClickHouse 表的物理排序(project_id 打头),决定查询能少扫多少L08
不可变事件写入后基本不动;改=追加新行 + 查询时去重保留最新(ReplacingMergeTree FINAL),避开高规模更新的隐藏成本L08
多租户每张表/查询/消息都带 projectId;project 硬隔离、environment 软切片L10
project_id贯穿全栈的硬隔离键,焊进 ClickHouse 排序键前缀L10

第三部分 · 摄取链路

术语一句话定义课
摄取队列Redis+BullMQ 队列放 fileKey 指针、本体在 S3,是 web(快)与 worker(慢)的交接点L14
分片按 projectId-eventBodyId 哈希取模把队列摊成 N 条,同实体永远同 shardL14
IngestionService / mergeAndWrite把同一实体的多条事件 merge 成一条记录,再交批写器L15
ClickhouseWriter单例批写器:每表内存队列,攒满或定时批量 INSERTL17
OTLPOpenTelemetry 的传输协议;适配器把 span 映射成原生摄取事件L18
presigned URL服务端签发的有时效直传/下载地址,让大块负载绕过应用层L19
内容寻址去重按 sha256 指纹判同一性,相同字节只存一份L19

第四部分 · 查询链路

术语一句话定义课
tRPC前后端共享类型的内部 API;改后端字段,前端编译即报错L21
RBAC角色→scope 映射;判权限问角色是否含该 scope,前端隐藏+后端强制L21
queryClickhouse统一执行器:给每条查询套 OTel/标签/退避重试/资源错误包装L22
回看时间窗利用观测集中在 trace 之后的有界时间,避免跨表全表扫L22
FilterStateUI 过滤的中间契约,编译成参数化的 ClickHouse/Postgres SQLL23
sessiontraces 按 session_id 分组的派生视图,非新实体、永远一致L26

第五部分 · 评估与评分

术语一句话定义课
dataTypescore 的刻度:NUMERIC / CATEGORICAL / BOOLEAN(锁死的特殊分类)L28
score config某 name 的 schema:声明刻度与约束、强制校验以保证可比L28
LLM-as-a-judge用一个 LLM 给另一个的输出评分,结构化输出 {score,reasoning}L29
JobExecutioneval 工单的状态机 PENDING→COMPLETED/ERROR/CANCELLED/DELAYEDL30
沙箱跑用户评估器代码的隔离环境:禁网络、限大小、限时L31
标注队列绑一组 scoreConfigIds 的人工评审任务,含待评 item 与 5 分钟软锁L32
monitor / severity把质量监测从拉变推:越阈值告警,severity 状态机只在变化时 emitL33

第六部分 · 数据集与实验

术语一句话定义课
数据集一组测试用例(input/expectedOutput/metadata),题可从真实 trace 提拔L34
SCD Type 2数据项用 validFrom/validTo 双时态版本化;改题=关旧版+插新版L34
dataset run某配置在整套题上的一次「考试」,run item 钉住题目版本L35
实验对比prompt×数据集×模型服务端自动跑,靠 baseline+增量做决策L36

第七部分 · Prompt 与 Playground

术语一句话定义课
prompt label指向某 prompt 版本的可移动指针(production/latest),零部署发布/回滚L37
epoch 失效缓存 key 嵌项目级令牌;改动只转令牌、旧 key 按 TTL 过期(O(1) 不漏)L38
fetchLLMCompletionPlayground、评估、实验共用的统一 LLM 调用引擎L39
AES-256-GCM认证加密:authTag 防篡改、随机 IV,用于存 provider API keyL39

第八部分 · 仪表盘·指标·成本

术语一句话定义课
widget / 查询引擎声明式查询(view+dimensions+metrics+filters),引擎编译成 ClickHouse SQLL41
语义层把逻辑名(如 totalCost)映射到真实 SQL 列/表达式的字典L41
matchPattern / matchPricingTier一条正则统一各家模型命名 + 按用量选中价目档L42
exactly-once计量必须不重不漏:cronJobs 锁 + 整点对齐 + 20 分钟兜底接管L43

第九部分 · 自动化与集成

术语一句话定义课
自动化 Trigger→Action事件触发器(何时)绑动作(webhook/Slack/GitHub,做什么)L44
SSRF服务器被诱导请求内网/元数据接口;纵深防御+fail-closed+请求时校验真实 IPL44
fan-out一个调度员按项目扇出 N 个处理任务(评估/集成/删除)L46
增量水位只同步上次之后的新数据,带缓冲与按日切块L46
幂等同一操作重复执行不出错、不翻倍副作用——批量操作的铁律L47

第十部分 · 平台与运维

术语一句话定义课
JWT session无状态自带签名身份的会话,本地验签利于多实例水平扩展L48
API key 两层哈希fastHashedSecretKey(sha256 快查) + hashedSecretKey(bcrypt 安全)L49
SCIM让 Okta/AzureAD 自动开通/注销 Langfuse 用户的标准协议(EE)L49
entitlement运行时功能门控:entitlementAccess 总表 + hasEntitlement 一道闸L50
开源核全代码开放(含企业功能),免费/付费的区别在运行时能否启用L50
dogfooding / instrumentAsyncLangfuse 用同一套 OTel 观测自己;instrumentAsync 是 span 包装器L51
配置即校验所有 env 过 Zod 启动即校验:fail-fast + 类型安全 + server/client 边界L51
数据保留按 retentionDays 自动跨三存储清旧数据(EE)L52
后台迁移给亿万行的表在线做手术,state 可断点续传、单 worker 锁L52
monorepo / Turbo一个仓库 + Turbo 内容哈希缓存,只重建真正改了的包L53
没有匹配的术语,换个关键词。

Part 1 · The Big Picture

TermOne-line definitionLesson
wide eventone row holding all of an operation's context (input/output/model/usage/latency), preserving high cardinality to slice any way laterL02
Observability 2.0treat wide events as the single analytical unit, recording everything, replacing the metrics/logs/traces trioL02
unknown unknownsquestions you didn't know to ask; wide events + high cardinality let you answer them laterL02
tracethe root of one full call, a correlation handle holding observationsL03
observationone step in a trace (SPAN/EVENT/GENERATION…, 10 types), the actual data carrierL03
scorethe atomic unit of evaluation (name/value/dataType/source), attached to a trace or observationL03
narrow waistweb/worker/ee depend on shared, shared depends on none — a one-way waistL04
asyncthe ingestion request just lands in S3 + enqueues to Redis then returns; heavy work goes to a background worker — peak-shaving, decoupling, retryableL05

Part 2 · Foundations

TermOne-line definitionLesson
event envelopethe unified wrapper of an ingestion event (id/type/timestamp/body); body is a discriminated unionL06
OLTP vs OLAPtransactional (precise single-row + strong consistency, Postgres) vs analytical (massive scan + aggregation, ClickHouse)L07
control plane / data planePostgres holds config metadata (control plane), ClickHouse holds the telemetry flood (data plane)L07
ReplacingMergeTreea ClickHouse engine: later write of the same key wins, dedup-merge at query keeping the latestL08
ordering keya table's physical sort (project_id first) deciding how little a query scansL08
immutabilityevents barely change once written; modify = append a new row + dedup-keep-latest at query (ReplacingMergeTree FINAL), avoiding the hidden cost of updates at scaleL08
multi-tenancyprojectId on every table/query/message; project = hard isolation, environment = soft sliceL10
project_idthe hard isolation key threaded through the stack, welded into the CH ordering-key prefixL10

Part 3 · The Ingestion Path

TermOne-line definitionLesson
ingestion queuea Redis+BullMQ queue holding a fileKey pointer (body in S3), the handoff between web and workerL14
shardinghash-mod splits the queue into N shards; one entity always lands on the same shardL14
IngestionService / mergeAndWritemerges an entity's multiple events into one record, then hands it to the batch writerL15
ClickhouseWritera singleton batch writer: per-table memory queue, bulk INSERT on size or timerL17
OTLPOpenTelemetry's wire protocol; an adapter maps spans to native ingestion eventsL18
presigned URLa server-signed time-limited upload/download URL letting bulky payloads bypass the app layerL19
content-addressed dedupidentity by sha256 fingerprint; identical bytes are stored onceL19

Part 4 · The Read Path

TermOne-line definitionLesson
tRPCa type-shared internal API; change a backend field and the front-end compile breaksL21
RBACrole→scope mapping; check the role contains the scope, front-end hide + back-end enforceL21
queryClickhousethe unified executor wrapping every query with OTel/tags/backoff-retry/error-wrapL22
look-back windowexploit that observations cluster in a bounded window after the trace, avoiding full scansL22
FilterStatethe intermediate contract for UI filters, compiled to parameterized ClickHouse/Postgres SQLL23
sessiona derived view of traces grouped by session_id, not a new entity, always consistentL26

Part 5 · Evaluation & Scoring

TermOne-line definitionLesson
dataTypea score's scale: NUMERIC / CATEGORICAL / BOOLEAN (a locked special category)L28
score configa name's schema: declares scale & constraints, enforced for comparabilityL28
LLM-as-a-judgeuse one LLM to score another's output, with structured output {score,reasoning}L29
JobExecutionthe eval ticket's state machine PENDING→COMPLETED/ERROR/CANCELLED/DELAYEDL30
sandboxthe isolated environment running user eval code: no network, size caps, timeoutL31
annotation queuea human-review task binding scoreConfigIds, with items to review + a 5-minute soft lockL32
monitor / severityturn quality monitoring from pull to push: alert on threshold, severity emits only on changeL33

Part 6 · Datasets & Experiments

TermOne-line definitionLesson
dataseta set of test cases (input/expectedOutput/metadata), promotable from real tracesL34
SCD Type 2bitemporal item versioning via validFrom/validTo; editing = close old + insert newL34
dataset runone 'exam' of a config over the whole set; run items pin the question versionL35
experiment comparisonprompt × dataset × model run server-side, decided via baseline + deltasL36

Part 7 · Prompts & Playground

TermOne-line definitionLesson
prompt labela movable pointer to a prompt version (production/latest), zero-deploy release/rollbackL37
epoch invalidationthe cache key embeds a project epoch token; rotate to invalidate, old keys expire by TTL (O(1))L38
fetchLLMCompletionthe one LLM-call engine shared by the Playground, evaluation, and experimentsL39
AES-256-GCMauthenticated encryption (authTag anti-tamper, random IV) used to store provider API keysL39

Part 8 · Dashboards, Metrics & Cost

TermOne-line definitionLesson
widget / query enginea declarative query (view+dimensions+metrics+filters) the engine compiles to ClickHouse SQLL41
semantic layera dictionary mapping logical names (e.g. totalCost) to real SQL columns/expressionsL41
matchPattern / matchPricingTierone regex unifies model naming + tier selection picks the price by usageL42
exactly-oncemetering must neither double nor miss: cronJobs lock + hour-align + 20-min takeoverL43

Part 9 · Automation & Integrations

TermOne-line definitionLesson
automation Trigger→Actionan event Trigger (when) bound to an Action (webhook/Slack/GitHub, what)L44
SSRFthe server tricked into hitting internal/metadata endpoints; defended in depth + fail-closed + real-IP check at request timeL44
fan-outone scheduler fans out N per-project processing jobs (eval/integration/deletion)L46
watermark (lastSyncAt)sync only data since last time, with a buffer and day-sized chunksL46
idempotencyrepeating an operation neither errors nor doubles side effects — the iron rule for batch actionsL47

Part 10 · Platform & Operations

TermOne-line definitionLesson
JWT sessiona stateless self-signed session; local verification scales horizontally across instancesL48
API key two-tier hashfastHashedSecretKey (sha256 for fast lookup) + hashedSecretKey (bcrypt for security)L49
SCIMa standard protocol letting Okta/AzureAD auto-provision/deprovision users (EE)L49
entitlementruntime feature gating: one entitlementAccess table + one hasEntitlement gateL50
open coreall code is open (incl. enterprise); free vs paid is runtime enablement, not code presenceL50
dogfooding / instrumentAsyncLangfuse observes itself with the same OTel; instrumentAsync is a span wrapperL51
config-as-validationall env validated by Zod at boot: fail-fast + type-safe + server/client boundaryL51
data retentionauto-delete old data across all three stores by retentionDays (EE)L52
background migrationonline schema surgery on billions of rows; state is resumable, single-worker lockL52
monorepo / Turboone repo + Turbo content-hash cache rebuilding only the packages that actually changedL53
No matching term, try another keyword.