文档 / Blob 存储导出字段参考

Blob 存储导出字段参考

本页列出 Langfuse blob 存储集成导出的每个字段,按导出表组织。设置说明和配置参见导出到 Blob 存储。

导出可以写为 Parquet(新集成的默认值)、CSV、JSON 或 JSONL 文件。类型按它们在 JSON/JSONL 导出中出现的方式描述。时间戳在 UTC 中使用 YYYY-MM-DD HH:MM:SS.ffffff 格式(例如 2024-05-29 13:46:19.963000)。关于类型在 CSV 格式中如何映射,参见关于 CSV 导出的说明;关于 Parquet 专属行为,参见关于 Parquet 导出的说明。

关于字段字典的说明: 下方各导出表的字段行(字段名、类型、描述、用法说明)作为机器可读的导出契约保留英文原文,以确保 API/导出字段语义的准确、避免误译;所有说明性文字、章节、表头和说明性表格均已译为中文。

导出源

blob 存储集成支持三种导出源模式(可在 Project Settings > Integrations > Blob Storage 中按项目配置):

模式	写入的 Blob 路径	描述
Enriched observations(推荐)	`observations_v2/`、`scores/`	每个 observation 行直接包含 trace 级字段(`user_id`、`session_id`、`trace_name` 等)。trace 上下文无需仓库端 JOIN。
Traces and observations(旧版)	`traces/`、`observations/`、`scores/`	每个时间窗口三个单独文件。Observations 不包含 trace 级字段;在你的仓库中按 `trace_id` 连接。
Traces and observations(旧版)and enriched observations	以上全部	写入两组 observation 文件,加上 traces 和 scores。

无论模式如何,分数始终被导出。

对于大多数用例,我们推荐 Enriched observations:它产生更少的文件,并避免为 trace 上下文进行跨文件 JOIN。

丰富的 observations(`observations_v2/`)

在 Enriched observations 和 Traces and observations (legacy) and enriched observations 模式下导出。

每行是单个 observation,直接包含 trace 级上下文,因此无需仓库端 JOIN。

下面的列被分组为十一个字段组,其中十个可切换。新集成默认导出所有组。core 组始终包含;其他组可按集成取消选择,以缩小文件或省略敏感列。字段组也适用于旧版 observations/ 文件(每组的列集较小),但不适用于具有固定列集的 traces/ 文件。

字段	类型	描述	用法说明
`id`	string	Unique observation identifier.	Primary key.
`trace_id`	string	Parent trace identifier.	Use to link with scores or group observations by trace.
`project_id`	string	Langfuse project identifier.	All rows in one export belong to the same project.
`environment`	string	Environment label.	Filter by environment.
`type`	string	Observation type: `SPAN`, `GENERATION`, `EVENT`, `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`, or `GUARDRAIL`.	See observation types. Generations are LLM calls; spans are arbitrary operations; events are point-in-time markers.
`parent_observation_id`	string	Parent observation ID (for nested observations).	Reconstruct the trace tree by walking parent pointers. Empty string for root-level observations.
`start_time`	string (timestamp)	When the observation started.	Primary time axis for observations.
`end_time`	string (timestamp) or null	When the observation ended.	Null for events and in-progress observations.
`name`	string	User-defined observation name.	Group/filter by name (e.g. function name, model call label).
`metadata`	object	User-supplied key-value metadata.	Arbitrary context. Extract keys relevant to your analytics.
`level`	string	Log level: `DEBUG`, `DEFAULT`, `WARNING`, `ERROR`.	Filter for errors or warnings.
`status_message`	string	Status or error message.	Inspect for debugging failed observations.
`version`	string	User-provided version string set via the SDK.	Empty string when not set.
`input`	string	Observation input payload.	For generations: the prompt/messages sent to the LLM. May be plain text or JSON; may be large. Empty string when not set.
`output`	string	Observation output payload.	For generations: the LLM response. May be plain text or JSON; may be large. Empty string when not set.
`provided_model_name`	string	Model name as provided by the user/SDK.	The raw model string (e.g. `gpt-4o`, `claude-sonnet-4-20250514`). Empty string for spans and events.
`model_parameters`	string	Model call parameters as a JSON-encoded string (e.g. `""`).	Parse as JSON. Useful for analyzing how model settings affect quality/cost. Empty string for spans and events.
`usage_details`	object (string → integer)	Token usage breakdown by category.	Extract keys: `input` for input tokens, `output` for output tokens, `total` for total. May contain additional keys like `input_cached_tokens`, `reasoning_tokens`, etc.
`cost_details`	object (string → number)	Cost breakdown by category (USD).	Extract keys: `input` for input cost, `output` for output cost.
`completion_start_time`	string (timestamp) or null	When the first token was generated (for streaming).	Used to compute `time_to_first_token`. Null for non-streaming calls.
`prompt_name`	string	Name of the Langfuse prompt used, if any.	Filter for observations using a specific prompt.
`prompt_version`	integer or null	Version number of the Langfuse prompt used.	Track which prompt version was active.
`total_cost`	number	Total computed cost for this observation (USD).	Observation-level cost. Sum across a trace for trace-level cost.
`latency`	number or null	Duration in seconds (`end_time - start_time`).	Null when `end_time` is null.
`time_to_first_token`	number or null	Time to first token in seconds (`completion_start_time - start_time`).	Null when `completion_start_time` is null. Measures streaming responsiveness.
`model_id`	string	Langfuse model definition ID (resolved from `provided_model_name`).	Used to look up pricing. Empty string if no model definition matched.
`created_at`	string (timestamp)	Row creation time.	System timestamp.
`updated_at`	string (timestamp)	Last update time.	Incremental processing.
`prompt_id`	string	Langfuse prompt definition ID.	Use with `prompt_name`/`prompt_version` for prompt analytics.
`tool_calls`	array of strings	Raw tool/function call payloads from the LLM response.	Parse each element as JSON. Contains the full tool call objects.
`tool_call_names`	array of strings	Names of tools/functions called.	Quick filter/group without parsing full `tool_calls`.
`tool_definitions`	object	Tool/function schemas provided to the LLM.	May be an empty object `` when no tools were provided.
`usage_pricing_tier_id`	string or null	ID of the pricing tier used for cost calculation.	Langfuse pricing tier UUID from the model definition. Null if no tiered pricing applies.
`usage_pricing_tier_name`	string or null	Name of the pricing tier used for cost calculation.	User-defined tier name from the model definition. Null if no tiered pricing applies.
`input_price`	string or null	Per-unit input price from the matched model definition. Decimal string.	Null if no model definition matched. Cast to numeric in your pipeline. Not included in Parquet exports.
`output_price`	string or null	Per-unit output price from the matched model definition. Decimal string.	Null if no model definition matched. Cast to numeric in your pipeline. Not included in Parquet exports.
`total_price`	string or null	Per-unit total price from the matched model definition. Decimal string.	Null if no model definition matched. Used for models with a flat per-call price. Not included in Parquet exports.
`user_id`	string	End-user identifier from the parent trace.	Directly available; no JOIN needed.
`session_id`	string	Session identifier from the parent trace.	Directly available; no JOIN needed.
`trace_name`	string	Name of the parent trace.	Group observations by their parent trace name.
`tags`	array of strings	Tags from the parent trace.	Directly available; no JOIN needed.
`release`	string	Release tag from the parent trace.	Directly available; no JOIN needed.
`bookmarked`	boolean	Bookmark flag from the parent trace.	Directly available.
`public`	boolean	Public flag from the parent trace.	Directly available.

对于 2026-04-01 或之后创建的集成,latency 和 time_to_first_token 以秒为单位(与 observations/ 文件一致)。对于该日期之前创建的集成,这些字段以毫秒为单位,以向后兼容。

从单个文件派生 trace 级聚合

使用 Enriched observations 导出,你可以仅从 observations_v2/ 文件计算 trace 级指标,无需跨文件 JOIN。按 trace_id 分组,并计算 SUM(total_cost) 得到 trace 成本,计算 MAX(end_time) - MIN(start_time) 得到 trace 延迟。

分数(`scores/`)

无论导出源模式如何,始终导出。包含数据类型为 NUMERIC、BOOLEAN、CATEGORICAL 和 TEXT 的分数。

字段	类型	描述	用法说明
`id`	string	Unique score identifier.	Primary key.
`timestamp`	string (timestamp)	Score creation timestamp (event time).	Primary time axis for scores.
`project_id`	string	Langfuse project identifier.	All rows in one export belong to the same project.
`environment`	string	Environment label.	Filter by environment.
`trace_id`	string or null	Associated trace identifier.	Null for standalone scores not linked to a trace. Join to get trace or observation context.
`observation_id`	string or null	Associated observation identifier (optional).	Null if the score is trace-level. Non-null if the score targets a specific observation.
`session_id`	string or null	Associated session identifier.	Null when not set. Direct access to session context without joining traces.
`dataset_run_id`	string or null	Associated dataset run identifier (if score came from an evaluation run).	Links scores to experiment/evaluation runs. Null for ad-hoc or annotation scores.
`name`	string	Score name (e.g. `accuracy`, `helpfulness`, `hallucination`).	Group/filter by score metric name.
`value`	number	Numeric score value.	For `BOOLEAN`: 0 or 1. For `CATEGORICAL`: index of the category. For `NUMERIC`: the raw value. For `TEXT`: always 0 (not meaningful; use `string_value` instead).
`source`	string	Score source: `API`, `ANNOTATION`, `EVAL`.	`API` = programmatic via SDK, `ANNOTATION` = human annotation in UI, `EVAL` = LLM-as-judge evaluator.
`comment`	string or null	Optional human comment or evaluator reasoning.	Context for the score. Useful for annotation workflows.
`data_type`	string	Score data type: `NUMERIC`, `BOOLEAN`, `CATEGORICAL`, or `TEXT`.	Determines how to interpret `value` and `string_value`.
`string_value`	string or null	String representation for categorical and text scores.	For `CATEGORICAL`: the category label (e.g. `"positive"`, `"neutral"`). For `TEXT`: the free-text content (1–500 characters). Null for numeric scores.
`created_at`	string (timestamp)	Row creation time.	System timestamp.
`updated_at`	string (timestamp)	Last update time.	Incremental processing.

用 trace/observation 上下文丰富分数

分数不内联包含 trace 级字段。要丰富:

导出模式	如何获取 trace 上下文
Enriched observations	按 `trace_id` 将分数连接到 `observations_v2/` 文件。由于多个 observations 共享同一 `trace_id`,请先去重(例如每个 `trace_id` 选一行)以避免分数行倍增。每个 observation 行已包含 `user_id`、`session_id`、`trace_name`、`tags`、`release`、`environment`。
Traces and observations(旧版)	按 `trace_id` 将分数连接到 `traces/` 文件以获取 `user_id`、`environment`、`name` 等。

旧版导出路径

以下各节涵盖 Traces and observations (legacy) 导出模式。如果你正在设置新集成,我们建议改用 Enriched observations。

Traces(`traces/`)

仅在 Traces and observations (legacy) 和 Traces and observations (legacy) and enriched observations 模式下导出。

traces/ 文件具有固定列集;字段组不适用于它。对于旧版导出,此文件也是 trace 级上下文(tags、release、trace name)所在之处;这些字段不会在旧版 observations/ 行上重复。将 observations/ 文件的 trace_id 与此处的 id 连接以组合它们。

字段	类型	描述	用法说明
`id`	string	Unique trace identifier.	Primary key. Use to join with observations and scores via `trace_id`.
`timestamp`	string (timestamp)	Trace creation timestamp (event time).	Primary time axis for traces. Use for partitioning, filtering, and time-series analysis.
`name`	string	User-defined trace name (e.g. the top-level operation).	Useful for grouping and filtering traces by operation type.
`environment`	string	Environment label (e.g. `production`, `staging`).	Filter or partition by environment.
`project_id`	string	Langfuse project identifier.	All rows in one export belong to the same project.
`metadata`	object	User-supplied key-value metadata attached to the trace.	Arbitrary context. Extract keys relevant to your analytics.
`user_id`	string or null	End-user identifier associated with the trace.	Null when not set. Group by user for per-user analytics.
`session_id`	string or null	Session identifier grouping related traces.	Null when not set. Group traces into sessions for conversation-level analysis.
`release`	string or null	Application release/version tag.	Null when not set. Filter or compare across releases.
`version`	string or null	User-provided version string set via the SDK.	Null when not set. Track how changes to your application affect metrics over time.
`public`	boolean	Whether the trace is publicly shareable.	Filter for public/private traces.
`bookmarked`	boolean	Whether the trace is bookmarked in the Langfuse UI.	Filter for bookmarked items.
`tags`	array of strings	User-defined tags on the trace.	Multi-value filtering and grouping.
`input`	string or null	Trace input payload.	The top-level input to the traced operation. May be plain text or JSON; may be large. Null when not set.
`output`	string or null	Trace output payload.	The top-level output. May be plain text or JSON; may be large. Null when not set.
`created_at`	string (timestamp)	Row creation time.	System timestamp. Typically close to `timestamp` but may differ for late-arriving data.
`updated_at`	string (timestamp)	Last update time.	Useful for incremental processing: re-process rows where `updated_at` > last sync.

不在 trace 导出中的字段

这些字段不直接导出。在你的仓库中派生它们:

字段	如何派生
`total_cost`	Sum observation-level `total_cost` grouped by `trace_id` from the observations file.
`latency`	Compute `MAX(end_time) - MIN(start_time)` across observations per `trace_id`.
`observations`	Join the observations file on `trace_id` for the full list.
`scores`	Join the scores file on `trace_id` for the full list.
`html_path`	Construct as `/project//traces/`.

Observations(`observations/`)

在 Traces and observations (legacy) 和 Traces and observations (legacy) and enriched observations 模式下导出。

这些行仅包含 observation 级数据。像 user_id、session_id 和 tags 这样的 trace 级字段不包含在内。在你的仓库中按 trace_id 连接 traces/ 文件,或切换到 Enriched observations 导出模式。

字段组也适用于此文件,每组的列集比丰富导出小。trace_context 组在此无效;其字段位于 traces/ 文件中。下表列出选择每个组时的所有列。

字段	类型	描述	用法说明
`id`	string	Unique observation identifier.	Primary key.
`trace_id`	string	Parent trace identifier.	Join on this to get trace-level fields, or to link with scores.
`project_id`	string	Langfuse project identifier.	All rows in one export belong to the same project.
`environment`	string	Environment label.	Filter by environment.
`type`	string	Observation type: `SPAN`, `GENERATION`, `EVENT`, `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`, or `GUARDRAIL`.	See observation types. Generations are LLM calls; spans are arbitrary operations; events are point-in-time markers.
`parent_observation_id`	string or null	Parent observation ID (for nested observations).	Reconstruct the trace tree by walking parent pointers. Null for root-level observations.
`start_time`	string (timestamp)	When the observation started.	Primary time axis for observations.
`end_time`	string (timestamp) or null	When the observation ended.	Null for events and in-progress observations.
`name`	string	User-defined observation name.	Group/filter by name (e.g. function name, model call label).
`metadata`	object	User-supplied key-value metadata.	Arbitrary context. Extract keys relevant to your analytics.
`level`	string	Log level: `DEBUG`, `DEFAULT`, `WARNING`, `ERROR`.	Filter for errors or warnings.
`status_message`	string or null	Status or error message.	Null when not set. Inspect for debugging failed observations.
`version`	string or null	User-provided version string set via the SDK.	Null when not set.
`input`	string or null	Observation input payload.	For generations: the prompt/messages sent to the LLM. May be plain text or JSON; may be large. Null when not set.
`output`	string or null	Observation output payload.	For generations: the LLM response. May be plain text or JSON; may be large. Null when not set.
`provided_model_name`	string or null	Model name as provided by the user/SDK.	The raw model string (e.g. `gpt-4o`, `claude-sonnet-4-20250514`). Null for spans and events.
`model_parameters`	string or null	Model call parameters as a JSON-encoded string (e.g. `""`).	Parse as JSON. Useful for analyzing how model settings affect quality/cost. Null for spans and events.
`usage_details`	object (string → integer)	Token usage breakdown by category.	Extract keys: `input` for input tokens, `output` for output tokens, `total` for total. May contain additional keys like `input_cached_tokens`, `reasoning_tokens`, etc.
`cost_details`	object (string → number)	Cost breakdown by category (USD).	Extract keys: `input` for input cost, `output` for output cost.
`completion_start_time`	string (timestamp) or null	When the first token was generated (for streaming).	Used to compute `time_to_first_token`. Null for non-streaming calls.
`prompt_name`	string or null	Name of the Langfuse prompt used, if any.	Null when no prompt was used. Filter for observations using a specific prompt.
`prompt_version`	integer or null	Version number of the Langfuse prompt used.	Track which prompt version was active.
`total_cost`	number or null	Total computed cost for this observation (USD).	Null when cost could not be computed. Observation-level cost. Sum across a trace for trace-level cost.
`latency`	number or null	Duration in seconds (`end_time - start_time`).	Null when `end_time` is null.
`time_to_first_token`	number or null	Time to first token in seconds (`completion_start_time - start_time`).	Null when `completion_start_time` is null. Measures streaming responsiveness.
`model_id`	string or null	Langfuse model definition ID (resolved from `provided_model_name`).	Used to look up pricing. Null if no model definition matched.
`created_at`	string (timestamp)	Row creation time.	System timestamp.
`updated_at`	string (timestamp)	Last update time.	Incremental processing.
`prompt_id`	string or null	Langfuse prompt definition ID.	Null when no prompt was used. Use with `prompt_name`/`prompt_version` for prompt analytics.
`tool_calls`	array of strings	Raw tool/function call payloads from the LLM response.	Parse each element as JSON. Contains the full tool call objects.
`tool_call_names`	array of strings	Names of tools/functions called.	Quick filter/group without parsing full `tool_calls`.
`tool_definitions`	object	Tool/function schemas provided to the LLM.	May be an empty object `` when no tools were provided.
`usage_pricing_tier_name`	string or null	Name of the pricing tier used for cost calculation.	User-defined tier name from the model definition. Null if no tiered pricing applies. Unlike the enriched export, `usage_pricing_tier_id` is not included in this file.
`input_price`	string or null	Per-unit input price from the matched model definition. Decimal string.	Null if no model definition matched. Cast to numeric in your pipeline. Not included in Parquet exports.
`output_price`	string or null	Per-unit output price from the matched model definition. Decimal string.	Null if no model definition matched. Cast to numeric in your pipeline. Not included in Parquet exports.
`total_price`	string or null	Per-unit total price from the matched model definition. Decimal string.	Null if no model definition matched. Used for models with a flat per-call price. Not included in Parquet exports.

丰富导出与旧版导出之间的差异

组合旧版 traces/ 和 observations/ 文件产生的数据几乎与丰富 observations_v2/ 文件相同。净差异:

方向	字段	说明
仅在丰富导出中	`usage_pricing_tier_id`	旧版 `observations/` 文件仅包含 `usage_pricing_tier_name`。
仅在旧版中(通过 `traces/` 文件)	Trace 级 `input`、`output`、`metadata`、`timestamp`、`version`	`timestamp` 被可靠设置(根 span 开始时间)。Trace 级 `input`/`output` 仅在使用 Langfuse SDK 或受支持的框架(例如 Vercel AI SDK、Genkit、Pydantic AI)时填充;对于纯 OTEL 自动埋点它们为 null。Trace 级 `metadata` 通常包含埋点属性而非业务数据。Trace 级 `version` 独立于 `basic` 组中的 observation 级 `version` 字段设置。
相同数据,不同结构	`bookmarked`、`public`、`release`、`session_id`、`tags`、`trace_name`、`user_id`	在丰富导出中反规范化到每个 observation 行;在旧版中,仅在 `traces/` 文件中可用(其中 `trace_name` 称为 `name`),并通过 `trace_id` 连接。

关于 CSV 导出的说明

在 CSV 格式中,所有值都表示为文本。与 JSON/JSONL 的主要差异:

JSON 类型	CSV 表示
string	纯文本值。
number	数值文本(例如 `1.23`)。在你的流水线中解析为 float。
integer	无小数点的数值文本(例如 `1024`)。
boolean	`true` 或 `false`。
null	空字段。
array of strings	JSON 编码的字符串(例如 `["tag1","tag2"]`)。将该字段解析为 JSON。
object	JSON 编码的字符串(例如 ``)。将该字段解析为 JSON。
string (timestamp)	UTC 中的 `YYYY-MM-DD HH:MM:SS.ffffff`(例如 `2024-05-29 13:46:19.963000`)。在你的流水线中解析为时间戳。

价格字段: input_price、output_price 和 total_price 在 JSON/JSONL 中作为带引号的字符串导出(例如 "0.03")以保留小数精度。在 CSV 中它们显示为纯文本。在你的仓库中将它们转换为数值或 decimal 类型。其他成本字段(total_cost、cost_details 值)作为 JSON 数字导出。价格字段不包含在 Parquet 导出中。

将 CSV 加载到仓库时,将时间戳字段转换为仓库的时间戳类型,数值字段转换为 float/decimal,如果仓库支持,将 JSON 编码的字段(对象、数组)解析为原生 map/array 类型。

关于 Parquet 导出的说明

Apache Parquet 是新集成的默认文件类型。它是一种列式二进制格式,由存储引擎编码和压缩,因此 gzip 压缩不适用;Parquet 文件始终以纯 .parquet 扩展名写入。

Parquet observation 导出(observations_v2/ 和旧版 observations/)不包含每单位模型价格列 input_price、output_price 和 total_price。这些列在导出时快照匹配模型定义的价格(而非记录 observation 时生效的价格),这限制了它们的历史价值,并且它们未来可能弃用。对于成本数据,请使用 cost_details 和 total_cost,它们捕获每个 observation 的计算成本,并包含在每种文件类型中。

Trace 和分数导出在所有文件类型中包含相同的字段。

blob 存储中的文件组织

{project_id}/
├── observations_v2/          # Enriched observations mode (recommended)
│   └── {timestamp}.{parquet|json|jsonl|csv}[.gz]
├── scores/                   # Always exported
│   └── {timestamp}.{parquet|json|jsonl|csv}[.gz]
├── traces/                   # Traces and observations (legacy) mode only
│   └── {timestamp}.{parquet|json|jsonl|csv}[.gz]
├── observations/             # Traces and observations (legacy) mode only
│   └── {timestamp}.{parquet|json|jsonl|csv}[.gz]
└── manifests/                # Run completion manifest, written last
    └── {timestamp}.json

文件按配置的导出频率(每 20 分钟、每小时、每天或每周)分区。每个文件覆盖一个时间窗口。.gz 后缀仅适用于 gzip 压缩的文本格式;Parquet 文件从不 gzip 压缩。

manifests/ 文件夹每个完成的导出运行包含一个 JSON 文件,列出该运行写入的每个文件。参见运行完成清单。