用OpenTelemetry监控Codex使用情况

随着组织从试验 coding agent 转向在工程团队中全面采用，管理层关注的问题也随之发生变化。不再只是“这个工具能帮助开发者吗？”，而是变成了：“我们该如何了解采用情况、管理使用量、维持可靠性，并以负责任的方式扩大访问范围？”Codex 可以发送与其活动相关的 OpenTelemetry（OTel）指标。当本地 Codex 客户端通过 Amazon Bedrock 使用 OpenAI 模型，并通过 AWS IAM Identity Center 进行身份验证时，你可以借助本地 OTel collector，将这些指标传送到 Amazon CloudWatch。最终，你将获得一个 AWS 原生的 Codex 使用情况视图，并可按用户、团队、部门、组织或成本中心进行整理。

这种方案不会在模型请求路径中添加集中式代理。开发者仍然在本地使用 Codex。每台开发者工作站上运行一个 collector，在本地主机上接收指标，并为其补充组织上下文。随后，collector 使用 AWS Signature Version 4（SigV4），将指标发送到所在 Region 的 CloudWatch OpenTelemetry Protocol（OTLP）端点。参考部署创建的是 CloudWatch dashboard，而不是 Amazon Elastic Container Service（Amazon ECS）服务、负载均衡器、virtual private cloud（VPC）或公共数据接收端点。

本文将介绍这一模式如何支持受治理的推广采用，分析其架构，并概述 Codex on AWS 指导仓库中的具体实现。

将遥测数据转化为业务决策

当遥测数据能够回答一个决策问题，而不只是再生成一个 dashboard 时，它才最有价值。内置的 CodexOnBedrock dashboard 提供过去 24 小时滚动统计的活跃用户数、对话轮次、API 请求数和 token 使用量。它还支持按模型、token 类型、用户、部门、团队、成本中心、组织及 session 来源查看数据。

这些信号可以帮助技术管理者区分广泛采用与局部试验。例如，多个团队的活跃用户数同时增长，与大量使用集中在少数人身上，意味着需要采取不同的赋能方式。工具调用活动可以帮助团队了解 agentic workflow 正在哪些场景中落地。请求量和耗时指标则有助于排查体验下降的问题。

最后一项中的区别非常重要。CloudWatch OTel 指标反映的是使用规模和运行行为。Token 数量可以用于趋势分析，但不能充当计费账本。由于价格调整、折扣、抵扣额度和账单修正，按照标价估算的费用可能与实际收费存在差异。如需了解实际支出，请使用 AWS Cost and Usage Reports（CUR）2.0 中基于 IAM principal 的成本分配数据，或适用的 Amazon Bedrock 成本管理报告。

该架构使用同一个 AWS identity 完成模型访问和遥测数据发布。开发者通过 IAM Identity Center 登录，并将 Amazon Bedrock 作为模型提供方运行 Codex。Codex 将指标发送到一个仅监听 127.0.0.1 的 collector。collector 会添加身份和组织属性，对指标进行批处理，并使用临时 AWS 凭证为发往 CloudWatch 的请求签名。

本地 Codex 遥测数据通过本地 collector 流向 Amazon CloudWatch；该 collector 使用 SigV4 身份验证发布指标，并且不进入 Amazon Bedrock 的推理路径。

Codex 会发送 codex.api_request、codex.api_request.duration_ms、codex.turn.e2e_duration_ms、codex.turn.token_usage、codex.turn.tool.call、codex.thread.started 和 codex.conversation.turn.count 等指标。当前 Codex 配置文档说明，OTel 需要主动选择启用，并为日志、指标和 trace 分别提供了独立的 exporter。

本地 collector 会添加 user.id 和 user.email 作为必需的 resource attributes。可选属性包括 department、team.id、cost_center、organization、location、role 和 manager。参考 collector 还会将这些属性复制到每个指标 datapoint 上。通过这种方式，无论使用本地 sidecar 还是其他受支持的数据接入模式，dashboard 都能获得一致的 Prometheus Query Language（PromQL）分组。

实现参考模式

完整的命令和模板都包含在 AWS 原生访问 quickstart 中。下面通过五个阶段概述其实现过程。

1. 启用 CloudWatch OTel 功能

参考 runbook 首先在目标 Region 中启用遥测数据的 OTel enrichment 和 resource tags：

aws cloudwatch start-otel-enrichment --region us-west-2
aws observabilityadmin start-telemetry-enrichment --region us-west-2
aws cloudwatch get-otel-enrichment --region us-west-2

当前 CloudWatch OTel 文档介绍了原生 OTLP 数据接入和 PromQL 查询能力。start-otel-enrichment 操作会为受支持的 AWS vended metrics 启用 enrichment 和 PromQL 访问能力。start-telemetry-enrichment 操作会启用 resource-tag enrichment。在更改这些设置之前，请先确认哪些账户级设置已经启用。

2. 部署 dashboard 并构建 collector

克隆仓库，然后部署 dashboard 并获取 collector 二进制文件：

deployment/scripts/deploy-otel-stack.sh --region us-west-2
deployment/scripts/build-local-collector.sh --all

AWS CloudFormation stack 会部署 CodexOnBedrock dashboard。collector 运行在开发者工作站上，因此这一步不会创建集中式 collector 计算资源或网络基础设施。

3. 为每位开发者生成配置

根据开发者已经完成身份验证的 AWS profile 生成 collector 配置：

deployment/scripts/generate-sidecar-config.sh \
  --region us-west-2 \
  --profile codex-bedrock \
  --auto-lookup

使用 --auto-lookup 时，脚本可以从 IAM Identity Center identity store 中读取组织属性。通过命令行显式提供的值可以覆盖自动发现的值。如果某个可选属性不可用，请省略其整个配置块。不要将占位字符串作为 dimension 发送。这样做会产生价值很低的 time series，并降低报告质量。

对于大规模终端部署，请通过现有的 endpoint management 流程生成并分发此配置。应将组织元数据视为受治理的数据：在将其用于管理层报告之前，先确定允许使用的值、数据负责人以及更新流程。

4. 配置 Codex 并授予最小权限

将 Codex metrics exporter 指向本地 collector。必须包含完整的 /v1/metrics 路径，因为 Codex 不会自动追加该路径：

[otel]
environment = "production"
log_user_prompt = false

[otel.metrics_exporter]
otlp-http = { endpoint = "http://127.0.0.1:4318/v1/metrics", protocol = "binary" }

collector 会将指标转发到所在 Region 的 CloudWatch OTLP metrics endpoint，例如 https://monitoring.us-west-2.amazonaws.com/v1/metrics。对于短期 AWS 凭证，SigV4 是推荐的身份验证方式。用于发布指标的 identity 需要 cloudwatch:PutMetricData 权限。这条指标传输路径不需要 log group 或 ECS 权限。

请保留 log_user_prompt = false。该设计旨在衡量运行状态和采用情况，而不是收集源代码或 prompt 内容。

5. 验证完整链路

使用生成的配置启动该服务专用的 collector，运行一个 Codex 任务，然后在 CloudWatch 控制台中打开 CodexOnBedrock dashboard。你也可以使用 CloudWatch Query Studio 或仓库中的 check-otel-pipeline.sh 脚本，确认 codex.turn.token_usage 已经到达。

Codex 指标会定期刷新，并在进程正常退出时刷新。参考 runbook 记录的刷新间隔为 60 秒，并建议将 OTEL_METRIC_EXPORT_INTERVAL=1000 作为可选的保护措施，以应对某些错误路径可能跳过退出时刷新的情况。如果始终没有出现指标，还应确认托管配置中没有设置 [analytics] enabled = false，因为该设置会禁用 Codex metrics pipeline。

在治理框架下运营

让 dashboard 变得有用的这些 dimension，如果暴露范围过大，也可能带来隐私和治理问题。面向管理层的报告应使用聚合后的团队、部门和成本中心视图。每用户 dashboard 应仅限经过批准的系统、运营、安全或财务角色访问，并确保访问方式符合员工监控和数据保留政策。

随着规模扩大，需要控制 metric cardinality。统一属性名称和值；省略无法支撑明确决策的字段；如果没有制定保留与查询计划，就不要添加项目名称或临时 identifier。CloudWatch OTel 指标按每 GB 数据接入量计费，PromQL 查询则根据扫描的 sample 数量计费。在大规模推广之前，请查看最新的 CloudWatch OTel 定价文档和 Amazon CloudWatch Pricing。

这种模式提供的是可见性和软性控制。你可以使用 CloudWatch alarms 和 Amazon Simple Notification Service（Amazon SNS）通知，在某位用户或某个团队超过预设的使用阈值时发出提醒。不过，IAM Identity Center 会直接签发临时凭证。这条本地遥测路径无法根据 token 预算同步阻止 Amazon Bedrock 请求。如果需要强制执行硬性限制，请使用位于请求路径中的 gateway 实施预算控制，并评估它在运维和身份归因方面的权衡。

首先选择一个工程团队开展试点，并确保其管理者和开发者都认同收集遥测数据的目的。验证身份归因是否准确、dashboard 能否回答实际运营问题，以及访问控制是否符合组织的治理政策。

接下来，添加少量受控的组织 dimension，并为需要采取行动的情况定义告警。只有在 collector 生命周期管理、身份更新和支持流程都可以稳定复用之后，才通过托管工作站配置扩大部署范围。最后，将 CloudWatch 使用遥测数据与 CUR 2.0 报告结合起来，使管理者能够同时查看采用情况、运行行为和符合计费标准的成本数据。

按照这一顺序实施，可以将初始投入保持在较低水平，也能让利益相关方有机会不断完善指标及其所支持的决策。

如需移除该监控模式，请停止开发者工作站上的 collector，并删除 dashboard stack：

aws cloudformation delete-stack \
  --stack-name codex-otel-dashboard \
  --region us-west-2

aws cloudformation wait stack-delete-complete \
  --stack-name codex-otel-dashboard \
  --region us-west-2

如果账户中的其他 workload 都不依赖这些账户级 enrichment 功能，可以评估是否使用 aws cloudwatch stop-otel-enrichment 和 aws observabilityadmin stop-telemetry-enrichment 将其禁用。请先确认依赖关系。这些设置可能还在支持该账户中的其他 CloudWatch 可观测性用例。

扩大 Codex 的使用规模不仅是访问权限方面的决策，也是运营模式方面的决策，它将开发者赋能、系统可靠性、治理和财务问责联系在一起。

通过组合使用 Codex OTel 指标、IAM Identity Center 属性、本地 collector 和 Amazon CloudWatch，组织无需在推理路径中加入新的集中式服务，也能构建可直接用于决策的可见性。CloudWatch 展示 Codex 的实际使用方式，CUR 2.0 则提供财务数据的事实来源。两者结合，可以支持组织以审慎、可衡量的方式，从试点逐步走向受治理的全面采用。

你可以使用 Codex on AWS 原生访问 quickstart 启动试点，然后根据组织需要做出的决策，调整 dimension、访问模型和报告周期。

本文介绍的是一种基于公共指导仓库的实现模式，并不意味着 AWS 已正式发布或认可该模式。