每个核心概念一句话定义,点右侧「课」跳到首次讲解它的那一课。用上方搜索框过滤。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 | 一次完整调用的根、关联句柄,挂载多个 observation | L03 |
| observation | trace 里的一步(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 |
| ReplacingMergeTree | ClickHouse 引擎:同主键后写覆盖先写,查询时合并去重保留最新 | 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 条,同实体永远同 shard | L14 |
| IngestionService / mergeAndWrite | 把同一实体的多条事件 merge 成一条记录,再交批写器 | L15 |
| ClickhouseWriter | 单例批写器:每表内存队列,攒满或定时批量 INSERT | L17 |
| OTLP | OpenTelemetry 的传输协议;适配器把 span 映射成原生摄取事件 | L18 |
| presigned URL | 服务端签发的有时效直传/下载地址,让大块负载绕过应用层 | L19 |
| 内容寻址去重 | 按 sha256 指纹判同一性,相同字节只存一份 | L19 |
| 术语 | 一句话定义 | 课 |
|---|---|---|
| tRPC | 前后端共享类型的内部 API;改后端字段,前端编译即报错 | L21 |
| RBAC | 角色→scope 映射;判权限问角色是否含该 scope,前端隐藏+后端强制 | L21 |
| queryClickhouse | 统一执行器:给每条查询套 OTel/标签/退避重试/资源错误包装 | L22 |
| 回看时间窗 | 利用观测集中在 trace 之后的有界时间,避免跨表全表扫 | L22 |
| FilterState | UI 过滤的中间契约,编译成参数化的 ClickHouse/Postgres SQL | L23 |
| session | traces 按 session_id 分组的派生视图,非新实体、永远一致 | L26 |
| 术语 | 一句话定义 | 课 |
|---|---|---|
| dataType | score 的刻度:NUMERIC / CATEGORICAL / BOOLEAN(锁死的特殊分类) | L28 |
| score config | 某 name 的 schema:声明刻度与约束、强制校验以保证可比 | L28 |
| LLM-as-a-judge | 用一个 LLM 给另一个的输出评分,结构化输出 {score,reasoning} | L29 |
| JobExecution | eval 工单的状态机 PENDING→COMPLETED/ERROR/CANCELLED/DELAYED | L30 |
| 沙箱 | 跑用户评估器代码的隔离环境:禁网络、限大小、限时 | L31 |
| 标注队列 | 绑一组 scoreConfigIds 的人工评审任务,含待评 item 与 5 分钟软锁 | L32 |
| monitor / severity | 把质量监测从拉变推:越阈值告警,severity 状态机只在变化时 emit | L33 |
| 术语 | 一句话定义 | 课 |
|---|---|---|
| 数据集 | 一组测试用例(input/expectedOutput/metadata),题可从真实 trace 提拔 | L34 |
| SCD Type 2 | 数据项用 validFrom/validTo 双时态版本化;改题=关旧版+插新版 | L34 |
| dataset run | 某配置在整套题上的一次「考试」,run item 钉住题目版本 | L35 |
| 实验对比 | prompt×数据集×模型服务端自动跑,靠 baseline+增量做决策 | L36 |
| 术语 | 一句话定义 | 课 |
|---|---|---|
| prompt label | 指向某 prompt 版本的可移动指针(production/latest),零部署发布/回滚 | L37 |
| epoch 失效 | 缓存 key 嵌项目级令牌;改动只转令牌、旧 key 按 TTL 过期(O(1) 不漏) | L38 |
| fetchLLMCompletion | Playground、评估、实验共用的统一 LLM 调用引擎 | L39 |
| AES-256-GCM | 认证加密:authTag 防篡改、随机 IV,用于存 provider API key | L39 |
| 术语 | 一句话定义 | 课 |
|---|---|---|
| widget / 查询引擎 | 声明式查询(view+dimensions+metrics+filters),引擎编译成 ClickHouse SQL | L41 |
| 语义层 | 把逻辑名(如 totalCost)映射到真实 SQL 列/表达式的字典 | L41 |
| matchPattern / matchPricingTier | 一条正则统一各家模型命名 + 按用量选中价目档 | L42 |
| exactly-once | 计量必须不重不漏:cronJobs 锁 + 整点对齐 + 20 分钟兜底接管 | L43 |
| 术语 | 一句话定义 | 课 |
|---|---|---|
| 自动化 Trigger→Action | 事件触发器(何时)绑动作(webhook/Slack/GitHub,做什么) | L44 |
| SSRF | 服务器被诱导请求内网/元数据接口;纵深防御+fail-closed+请求时校验真实 IP | L44 |
| 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 / instrumentAsync | Langfuse 用同一套 OTel 观测自己;instrumentAsync 是 span 包装器 | L51 |
| 配置即校验 | 所有 env 过 Zod 启动即校验:fail-fast + 类型安全 + server/client 边界 | L51 |
| 数据保留 | 按 retentionDays 自动跨三存储清旧数据(EE) | L52 |
| 后台迁移 | 给亿万行的表在线做手术,state 可断点续传、单 worker 锁 | L52 |
| monorepo / Turbo | 一个仓库 + Turbo 内容哈希缓存,只重建真正改了的包 | L53 |
| Term | One-line definition | Lesson |
|---|---|---|
| wide event | one row holding all of an operation's context (input/output/model/usage/latency), preserving high cardinality to slice any way later | L02 |
| Observability 2.0 | treat wide events as the single analytical unit, recording everything, replacing the metrics/logs/traces trio | L02 |
| unknown unknowns | questions you didn't know to ask; wide events + high cardinality let you answer them later | L02 |
| trace | the root of one full call, a correlation handle holding observations | L03 |
| observation | one step in a trace (SPAN/EVENT/GENERATION…, 10 types), the actual data carrier | L03 |
| score | the atomic unit of evaluation (name/value/dataType/source), attached to a trace or observation | L03 |
| narrow waist | web/worker/ee depend on shared, shared depends on none — a one-way waist | L04 |
| async | the ingestion request just lands in S3 + enqueues to Redis then returns; heavy work goes to a background worker — peak-shaving, decoupling, retryable | L05 |
| Term | One-line definition | Lesson |
|---|---|---|
| event envelope | the unified wrapper of an ingestion event (id/type/timestamp/body); body is a discriminated union | L06 |
| OLTP vs OLAP | transactional (precise single-row + strong consistency, Postgres) vs analytical (massive scan + aggregation, ClickHouse) | L07 |
| control plane / data plane | Postgres holds config metadata (control plane), ClickHouse holds the telemetry flood (data plane) | L07 |
| ReplacingMergeTree | a ClickHouse engine: later write of the same key wins, dedup-merge at query keeping the latest | L08 |
| ordering key | a table's physical sort (project_id first) deciding how little a query scans | L08 |
| immutability | events barely change once written; modify = append a new row + dedup-keep-latest at query (ReplacingMergeTree FINAL), avoiding the hidden cost of updates at scale | L08 |
| multi-tenancy | projectId on every table/query/message; project = hard isolation, environment = soft slice | L10 |
| project_id | the hard isolation key threaded through the stack, welded into the CH ordering-key prefix | L10 |
| Term | One-line definition | Lesson |
|---|---|---|
| ingestion queue | a Redis+BullMQ queue holding a fileKey pointer (body in S3), the handoff between web and worker | L14 |
| sharding | hash-mod splits the queue into N shards; one entity always lands on the same shard | L14 |
| IngestionService / mergeAndWrite | merges an entity's multiple events into one record, then hands it to the batch writer | L15 |
| ClickhouseWriter | a singleton batch writer: per-table memory queue, bulk INSERT on size or timer | L17 |
| OTLP | OpenTelemetry's wire protocol; an adapter maps spans to native ingestion events | L18 |
| presigned URL | a server-signed time-limited upload/download URL letting bulky payloads bypass the app layer | L19 |
| content-addressed dedup | identity by sha256 fingerprint; identical bytes are stored once | L19 |
| Term | One-line definition | Lesson |
|---|---|---|
| tRPC | a type-shared internal API; change a backend field and the front-end compile breaks | L21 |
| RBAC | role→scope mapping; check the role contains the scope, front-end hide + back-end enforce | L21 |
| queryClickhouse | the unified executor wrapping every query with OTel/tags/backoff-retry/error-wrap | L22 |
| look-back window | exploit that observations cluster in a bounded window after the trace, avoiding full scans | L22 |
| FilterState | the intermediate contract for UI filters, compiled to parameterized ClickHouse/Postgres SQL | L23 |
| session | a derived view of traces grouped by session_id, not a new entity, always consistent | L26 |
| Term | One-line definition | Lesson |
|---|---|---|
| dataType | a score's scale: NUMERIC / CATEGORICAL / BOOLEAN (a locked special category) | L28 |
| score config | a name's schema: declares scale & constraints, enforced for comparability | L28 |
| LLM-as-a-judge | use one LLM to score another's output, with structured output {score,reasoning} | L29 |
| JobExecution | the eval ticket's state machine PENDING→COMPLETED/ERROR/CANCELLED/DELAYED | L30 |
| sandbox | the isolated environment running user eval code: no network, size caps, timeout | L31 |
| annotation queue | a human-review task binding scoreConfigIds, with items to review + a 5-minute soft lock | L32 |
| monitor / severity | turn quality monitoring from pull to push: alert on threshold, severity emits only on change | L33 |
| Term | One-line definition | Lesson |
|---|---|---|
| dataset | a set of test cases (input/expectedOutput/metadata), promotable from real traces | L34 |
| SCD Type 2 | bitemporal item versioning via validFrom/validTo; editing = close old + insert new | L34 |
| dataset run | one 'exam' of a config over the whole set; run items pin the question version | L35 |
| experiment comparison | prompt × dataset × model run server-side, decided via baseline + deltas | L36 |
| Term | One-line definition | Lesson |
|---|---|---|
| prompt label | a movable pointer to a prompt version (production/latest), zero-deploy release/rollback | L37 |
| epoch invalidation | the cache key embeds a project epoch token; rotate to invalidate, old keys expire by TTL (O(1)) | L38 |
| fetchLLMCompletion | the one LLM-call engine shared by the Playground, evaluation, and experiments | L39 |
| AES-256-GCM | authenticated encryption (authTag anti-tamper, random IV) used to store provider API keys | L39 |
| Term | One-line definition | Lesson |
|---|---|---|
| widget / query engine | a declarative query (view+dimensions+metrics+filters) the engine compiles to ClickHouse SQL | L41 |
| semantic layer | a dictionary mapping logical names (e.g. totalCost) to real SQL columns/expressions | L41 |
| matchPattern / matchPricingTier | one regex unifies model naming + tier selection picks the price by usage | L42 |
| exactly-once | metering must neither double nor miss: cronJobs lock + hour-align + 20-min takeover | L43 |
| Term | One-line definition | Lesson |
|---|---|---|
| automation Trigger→Action | an event Trigger (when) bound to an Action (webhook/Slack/GitHub, what) | L44 |
| SSRF | the server tricked into hitting internal/metadata endpoints; defended in depth + fail-closed + real-IP check at request time | L44 |
| fan-out | one 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 chunks | L46 |
| idempotency | repeating an operation neither errors nor doubles side effects — the iron rule for batch actions | L47 |
| Term | One-line definition | Lesson |
|---|---|---|
| JWT session | a stateless self-signed session; local verification scales horizontally across instances | L48 |
| API key two-tier hash | fastHashedSecretKey (sha256 for fast lookup) + hashedSecretKey (bcrypt for security) | L49 |
| SCIM | a standard protocol letting Okta/AzureAD auto-provision/deprovision users (EE) | L49 |
| entitlement | runtime feature gating: one entitlementAccess table + one hasEntitlement gate | L50 |
| open core | all code is open (incl. enterprise); free vs paid is runtime enablement, not code presence | L50 |
| dogfooding / instrumentAsync | Langfuse observes itself with the same OTel; instrumentAsync is a span wrapper | L51 |
| config-as-validation | all env validated by Zod at boot: fail-fast + type-safe + server/client boundary | L51 |
| data retention | auto-delete old data across all three stores by retentionDays (EE) | L52 |
| background migration | online schema surgery on billions of rows; state is resumable, single-worker lock | L52 |
| monorepo / Turbo | one repo + Turbo content-hash cache rebuilding only the packages that actually changed | L53 |