事实事件字段说明

更新时间:
复制 MD 格式

事实事件字段说明面向需要编写自定义查询、理解审计数据结构或对接外部分析系统的用户。本文说明应用侧事件表 agent-event / agent-event-webtracking 和运行时事件表 ebpf-event 的字段含义及常见取值。

说明

本文中的示例值均为脱敏、合成或文档化占位内容,用于说明字段形态和数据语义,不代表真实用户数据。实际事件中的敏感值可能经过采集侧脱敏、截断或摘要化处理。

表概述

审计事实事件是审计模块的数据基础,记录 AI Agent 运行过程中的原始行为事件,包括模型请求与响应、工具调用与结果、会话生命周期和运行时观测数据。风险检测、审计事实浏览、实体调查和 Token 分析均基于这些事件表工作。

表名

说明

agent-event

存储应用侧 AI Agent 会话日志的标准化事件,由 Agent 应用通过服务端写入链路上报。

agent-event-webtracking

与 agent-event 字段契约完全一致,区别仅在于写入链路为 WebTracking 端上报。查询时两表需合并读取。

ebpf-event

存储 AI 节点运行时 eBPF 采集的观测事件,包括运行时层面观察到的模型调用、工具执行、进程、文件和网络行为。

通用字段说明

以下字段在 agent-event、agent-event-webtracking 和 ebpf-event 中通用。

事件标识

字段

类型

说明

event.id

string

事件唯一标识,全局唯一。

event.name

string

事件类型,表示该条记录描述的行为类别。取值见本文"事件类型枚举"章节。

time_unix_nano

int64

事件发生时间,单位为纳秒级 Unix 时间戳。

主机与服务

字段

类型

说明

__tag__:__hostname__

string

SLS LogGroup 主机名元数据。host.name 为空或缺失时,用作主机名的兼容值。

__source__

string

SLS 写入来源元数据。host.ip 为空或缺失时,用作 Agent 主机 IP 的兼容值;不表示网络对端或外联目标。

host.id

string

主机或执行环境的稳定标识。

host.name

string

Agent 运行所在的主机、Pod、容器或执行环境名称。

host.ip

string

Agent 运行所在主机的 IP 地址。审计结果表将该值平铺为 source_ip。

用户与 Agent 标识

字段

类型

说明

user.id

string

发起请求的用户标识。

gen_ai.agent.type

string

Agent 类型标识,例如 qoder、cursor、claude-code。

gen_ai.agent.id

string

Agent 实例唯一标识。

gen_ai.agent.name

string

Agent 实例的可读名称。

会话层次结构

Agent 事件按 Session → Turn → Step 三层组织,分别表示一次会话、一轮用户交互和一个推理-动作循环。

字段

类型

说明

gen_ai.session.id

string

会话唯一标识,对应一次完整的 Agent 对话或任务。

gen_ai.turn.id

string

Turn 唯一标识,对应一次用户输入到 Agent 最终响应的完整交互。

gen_ai.turn.start

boolean

是否为 Turn 的起始事件。仅在值为 true 时写入。

gen_ai.turn.end

boolean

是否为 Turn 的结束事件。仅在值为 true 时写入。

gen_ai.step.id

string

Step 唯一标识,对应一个 ReAct 循环(思考 → 动作 → 观察)。

模型调用

字段

类型

说明

gen_ai.provider.name

string

模型服务提供方标识,例如 anthropic、openai、qwen、deepseek。

gen_ai.request.model

string

请求模型名称。

gen_ai.response.model

string

实际响应的模型名称,可能与请求模型不同。

gen_ai.response.id

string

模型响应的唯一标识,由模型服务返回。

gen_ai.response.finish_reasons

string[]

模型停止原因,常见取值包括 stop、tool_calls、length、content_filter、error。

模型输入与输出内容

字段

类型

说明

gen_ai.input.messages_delta

json

增量输入消息,记录自上次可重建输入以来新增的消息内容。是审计分析和 Session 浏览中使用的主要输入内容字段。

gen_ai.input.messages

json

发送给模型的完整消息历史。该字段可能包含敏感信息,按需启用采集。

gen_ai.output.messages

json

模型输出消息,包含角色、文本、工具调用和推理内容。

gen_ai.system_instructions

json

系统指令或开发者指令,与对话消息分离的提示词内容。

gen_ai.tool.definitions

json

模型请求时可用的工具定义列表。

Token 用量

字段

类型

说明

gen_ai.usage.input_tokens

int

输入 Token 数量(包含缓存读取)。

gen_ai.usage.output_tokens

int

输出 Token 数量。

gen_ai.usage.cache_read.input_tokens

int

从缓存中读取的输入 Token 数量,已包含在 input_tokens 中。

gen_ai.usage.cache_creation.input_tokens

int

写入缓存的输入 Token 数量,已包含在 input_tokens 中。

gen_ai.usage.total_tokens

int

总 Token 数量,等于 input_tokens + output_tokens。

工具调用

字段

类型

说明

gen_ai.tool.name

string

工具名称,与模型调用中的 function/tool name 一致。

gen_ai.tool.call.id

string

工具调用标识,由模型生成,用于关联调用与结果。

gen_ai.tool.call.arguments

json

工具调用参数。该字段可能包含敏感信息。

gen_ai.tool.call.result

json

工具执行结果。该字段可能包含敏感信息。

gen_ai.tool.call.duration

int

工具执行耗时,单位为毫秒。

gen_ai.skill.name

string

工具加载的 Skill 名称(如适用)。

错误信息

字段

类型

说明

error.type

string

错误类型标识,在操作发生错误时写入。无错误时该字段不存在。

error.message

string

错误详情的可读描述。

链路追踪

字段

类型

说明

trace_id

string

W3C Trace ID(32 位十六进制),用于分布式链路关联。

span_id

string

Span ID(16 位十六进制)。

parent_span_id

string

父 Span ID(16 位十六进制)。

应用侧事件补充字段

以下字段仅在 agent-event / agent-event-webtracking 中使用。

字段

类型

说明

__tag__:__service_name__

string

Agent 应用或服务名称,用于按应用维度筛选和归因。

service.name

string

应用名称(备用),当 __tag__:__service_name__ 缺失时作为补充。

运行时事件补充字段

以下字段仅在 ebpf-event 中使用,用于记录运行时层面观察到的进程、文件和网络行为。

事件类型枚举

event.name 表示事件的行为类别,是查询和分析时最常用的筛选字段。

应用侧事件类型

应用侧事件类型以 gen_ai. 为前缀,描述 Agent 的语义行为。

event.name

说明

gen_ai.model.request

模型请求,Agent 向模型服务发送推理请求。

gen_ai.model.response

模型响应,Agent 收到模型服务的推理结果。

gen_ai.tool.call

工具调用,Agent 执行工具或函数。

gen_ai.tool.result

工具结果,工具执行完成并返回结果。

gen_ai.agent.invoke

子 Agent 调用,当前 Agent 调用另一个 Agent。

gen_ai.agent.result

子 Agent 结果,被调用的 Agent 返回结果。

运行时事件类型

运行时事件类型当前仅包括 gen_ai.*(运行时观察到的模型和工具行为)。

event.name

说明

gen_ai.model.request

运行时观察到的模型请求。

gen_ai.model.response

运行时观察到的模型响应。

gen_ai.tool.call

运行时观察到的工具调用。

gen_ai.tool.result

运行时观察到的工具结果。

常见字段示例

字段

示例值

说明

event.id

evt-7f3a8b2c-1d4e-4f5a-9b6c-2e8d3f4a5b6c

具体格式由系统生成,外部系统只需作为稳定 ID 使用。

event.name

gen_ai.tool.call、runtime.file.write

表示事件描述的行为类别。

time_unix_nano

1719763200000000000

纳秒时间戳,对应 2024-06-30T12:00:00Z。

user.id

alice

用户标识,具体形式取决于接入方式。

gen_ai.agent.type

qoder、cursor、claude-code

Agent 产品类型。

gen_ai.session.id

sess-20240630-demo

用于关联同一会话内的所有事件。

gen_ai.provider.name

anthropic、openai、qwen

模型服务提供方。

gen_ai.request.model

claude-sonnet-4-20250514、gpt-4o

请求的模型名称。

gen_ai.tool.name

bash、read_file、WebFetch

被调用的工具名称。

gen_ai.tool.call.arguments

{"command":"git status"}

工具调用参数,格式为 JSON。

gen_ai.usage.input_tokens

12500

单次模型请求的输入 Token 数。

gen_ai.usage.output_tokens

3200

单次模型请求的输出 Token 数。

字段使用建议

场景

建议使用的字段

说明

还原会话完整交互

gen_ai.session.id + event.name + time_unix_nano

按 Session 聚合事件并按时间排序,可还原 Agent 的完整行为时间线。

分析单轮交互

gen_ai.turn.id + gen_ai.step.id

Turn 对应一次用户交互,Step 对应一个推理-动作循环;结合使用可理解 Agent 的决策链路。

Token 消耗统计

gen_ai.usage.input_tokens + gen_ai.usage.output_tokens + gen_ai.provider.name

按模型提供方和应用维度统计 Token 用量。

工具使用分析

gen_ai.tool.name + gen_ai.tool.call.duration + error.type

统计工具调用频次、耗时分布和失败率。

从风险事件回溯原始上下文

event.id + 风险事件的 evidence_event_ids

高保真安全事件通过 evidence_event_ids 引用原始事实事件 ID,可据此定位证据上下文。

按应用或主机维度筛选

__tag__:__service_name__(应用侧)/ __tag__:__hostname__

分别用于按应用和按主机维度聚合或筛选事件。

与其他审计数据的关系

数据

关系

security-event

风险检测规则从事实事件中识别出的低保真安全发现,引用事实事件作为证据来源。

incident-event

从低保真发现进一步提升的高保真安全事件,通过 evidence_event_ids 回溯到原始事实事件。

audit-event

从应用侧事实事件中按用户和 Session 生成的意图识别结果,通过 evidence_event_id 和 evidence_session_id 回溯到原始用户输入与会话。

审计事实页面

直接浏览和查询事实事件,支持 Session 浏览、Token 分析和行为分析。

风险审计页面

基于事实事件产生的高保真风险和用户意图结果进行展示和排序。