极狐 GitLab

AI 事件检测指南

本指南描述了检测 AI 和极狐GitLab Duo Agentic Platform (DAP) 事件所需的所有字段。 AI 事件使用两种上下文模式：

  • 标准上下文 - 包含所有极狐GitLab 事件中使用的通用字段。 请参阅 标准上下文 字段文档。
  • AI 上下文 - 包含 DAP 特定的字段，用于工作流和会话管理、模型信息以及令牌跟踪

概述#

在检测 AI 事件时，除了标准上下文字段，还需包含 DAP 特定的字段。 这些字段是 AI 上下文模式的一部分，且特定于 DAP（Duo Agentic Platform）和 AI Gateway 事件。

何时使用本指南#

在以下情况下使用本指南：

  • 检测极狐GitLab Duo 功能（Duo Chat、Duo Workflow、AI 驱动建议）
  • 跟踪 DAP (Duo Agentic Platform) 事件
  • 记录 AI 模型交互和令牌使用
  • 监控 AI 会话和工作流执行
  • 事件定义中包含 classification: duo 的事件

AI 上下文字段#

会话和工作流标识符#

字段类型描述示例
session_idstring, null实例中的会话标识符（非全局唯一）。"session_abc123"
workflow_idstring, null全局唯一的会话标识符。"workflow_xyz789"

工作流和代理信息#

字段类型描述示例
flow_typestring, nullDAP 流程类型（未来将包含更多自定义流程）。"chat", "software_development", "convert_to_gitlab_ci"
flow_versionstring, null流程的 AI 功能实现版本（最大长度：64 字符）。"2.1.0", "3.0.1"
flow_registry_versionstring, null用于构建流程的 Flow Registry 框架版本（最大长度：64 字符）。"1.0.0", "1.1.0"
agent_namestring, null流程内正在执行的代理。"duo_chat", "code_agent", "planning_agent"
agent_typestring, null流程内正在执行的代理类型。"foundational", "custom"

模型信息#

字段类型描述示例
model_providerstring, nullAI 请求使用的模型提供商（最大长度：64 字符）。"国内 SOTA 模型", "国内 SOTA 模型"
model_enginestring, nullAI 请求使用的模型引擎（最大长度：64 字符）。"国内 SOTA 模型", "国内 SOTA 模型"
model_namestring, nullAI 请求使用的模型名称（最大长度：64 字符）。"国内 SOTA 模型", "国内 SOTA 模型"

令牌跟踪#

令牌跟踪字段捕获 AI 模型令牌的使用情况，用于成本和性能监控。

字段类型描述示例
input_tokensinteger, null用户输入的令牌。1500, 3200
output_tokensinteger, null系统生成的令牌。500, 1200
total_tokensinteger, null输入 + 输出令牌总和。2000, 4400
ephemeral_5m_input_tokensinteger, null5 分钟缓存输入令牌。100, 250
ephemeral_1h_input_tokensinteger, null1 小时缓存输入令牌。500, 1000
cache_readinteger, null缓存读取操作。2, 5

完整检测示例#

以下是一个完整的示例，展示如何使用标准上下文和 AI 上下文字段来检测 DAP 事件：

ruby
1track_internal_event(
2  "request_duo_workflow_success",
3  user: user,
4  project: project,
5  namespace: namespace,
6
7  additional_properties: {
8    # AI 上下文字段
9    # 会话和工作流标识符
10    session_id: session.id,
11    workflow_id: session.id + instance.id,
12
13    # 流程和代理信息
14    flow_type: "software_development",
15    flow_version: "2.1.0",
16    flow_registry_version: "1.0.0",
17    agent_name: "code_generator",
18    agent_type: "code_agent",
19
20    # 模型信息 (AI 上下文)
21    model_provider: "国内 SOTA 模型",
22    model_engine: "国内 SOTA 模型",
23    model_name: "国内 SOTA 模型",
24    # 令牌跟踪 (AI 上下文)
25    input_tokens: 1500,
26    output_tokens: 800,
27    total_tokens: 2300,
28    ephemeral_5m_input_tokens: 500,
29    ephemeral_1h_input_tokens: 1000,
30    cache_read: 200
31  }
32)

有关 AI Gateway 触发事件和检测模式的更多信息，请参阅 AI Gateway 检测文档。

会话级事件#

以下事件展示了 DAP 会话的生命周期，对于大多数流程应进行跟踪：

事件操作目的触发时间所需上下文
request_duo_workflow AND receive_start_duo_workflow会话启动用户启动新流程会话标准 + AI 上下文
request_duo_workflow_success成功完成流程成功完成标准 + AI 上下文
request_duo_workflow_failure致命错误系统故障标准 + AI 上下文
request_duo_workflow_aborted连接失败连接问题标准 + AI 上下文
cleanup_stuck_agent_platform_session清理卡住的会话会话需要清理标准 + AI 上下文
pause_duo_workflow流程暂停因输入暂停标准 + AI 上下文
resume_duo_workflow流程恢复暂停的流程在批准/输入后恢复标准 + AI 上下文
duo_workflow_tool_success工具执行成功单个工具完成标准 + AI 上下文
duo_workflow_tool_failure工具执行失败单个工具失败标准 + AI 上下文
token_usage_*令牌消耗大型语言模型交互AI 上下文（令牌字段）
request_'unit_primitive'用户访问管理用户获得 AI 服务访问权限标准上下文

字段详情与最佳实践#

会话和工作流标识符#

session_id

  • 特定极狐GitLab 实例中用户会话的本地标识符
  • 由实例生成
  • 在不同实例之间非全局唯一
  • 用于本地会话跟踪和关联

令牌跟踪最佳实践#

在 AI 上下文中跟踪令牌使用时：

  1. 当跟踪 AI 模型交互时，始终包含 total_tokens
  2. 分别跟踪输入和输出令牌以进行准确计费
  3. 记录缓存使用情况（cache_read、ephemeral_5m_input_tokens、ephemeral_1h_input_tokens）以监控缓存有效性
  4. 在 AI 上下文中包含模型信息（model_provider、model_engine、model_name）以启用特定模型分析

计费和归属#

为了正确计费和客户归属：

  1. 包含 correlation_id（标准上下文） - 对于将 DAP 事件关联到计费事件至关重要
  2. 包含 billing_event_id（标准上下文） - 链接到计费使用事件
  3. 包含 ultimate_parent_namespace_id（标准上下文） - 确保客户归属与使用计费一致
  4. 包含 feature_enabled_by_namespace_ids（标准上下文） - 当前 AI 数据模型中客户归属的方法

向 AI 上下文添加字段#

您可以向 AI 上下文中添加新字段，以跟踪大多数 AI 事件共有的新属性。

要向 AI 上下文中添加新字段：

  1. 在 iglu 仓库中创建一个合并请求以更新模式。
  2. 如果新字段需要假名化，请将其添加到 snowplow-pseudonymization 项目中适当的假名化配置中。
  3. 更新极狐GitLab 代码库中的 AI 上下文实现以支持新字段。
  4. 开始发送包含新字段的 AI 上下文事件。
  5. 更新本文档以描述新字段。

相关文档#