最近在负责一套 AWS 环境里几十台 EC2 和一组 EKS 集群的可观测性改造目标很明确把 AWS DevOps Agent 采集到的系统指标、日志和链路数据统一接入观测云沉淀成一套能直接给研发运维团队看的数据面板。整个过程踩了不少坑从 IAM 权限模型到网络边界从 Agent 安装到观测云侧的数据校验几乎每一层都有值得复盘的地方。这篇文章就把完整的接入过程、关键配置和排错思路整理出来给正准备做同样事情的同学做参考。这次改造最终跑通之后最大的感受是Agent 接入本身并不难难的是提前把数据模型、权限模型和网络边界想清楚。如果一上来就急着装 Agent大概率会在中途反复返工。所以下面我按实际推进顺序来写从整体设计讲到每一步的实操细节最后把几个高频问题的排查过程也放进来。1. 接入前的整体设计与方案选型1.1 先想清楚数据链路Agent 到底在采集什么很多团队第一次接触观测云时容易把“接入 Agent”理解成一个安装动作装上就算结束。但实际落地时首先要回答的问题是Agent 采集的数据从哪里来经过什么通道最终在观测云里以什么形态呈现。以我这次负责的 AWS 环境为例资源主要分三类EC2 虚拟机和 Auto Scaling 组、EKS 容器集群、少量运行在 Lambda 上的无服务器任务。它们的可观测数据来源不同EC2 上有系统指标、进程列表和文本日志EKS 上除了节点指标还有 Pod 级别的事件、容器日志和 Service 访问链路Lambda 上则更适合接收调用链和函数运行日志。这就引出 Agent 的一个核心设计思路它应当是一个统一的采集入口而不是每类数据各装一个采集器。观测云的 Agent 正好承担这个角色通过插件方式同时采集系统指标、日志、容器数据和链路信息然后把数据统一上报到工作空间。这样做的好处很明显运维侧不需要维护多套采集组件研发侧看到的数据也能在一个时间轴上对齐。我在接入前专门花了一天时间梳理数据源清单给每个数据源标上采集方式、采集频率和数据保留周期。这一步看起来繁琐但后续配置 Agent、建立仪表盘和配置告警时都派上了用场否则很容易出现指标和日志各看各的链路数据又没有关联维度的情况。1.2 两种典型接入方式Agent 直采与云监控拉取在 AWS 场景下观测云的数据接入大体上有两条路一条是把 Agent 部署到 AWS 资源上由 Agent 直采数据后上报另一条是通过观测云与 AWS 的集成能力直接调用云监控相关的 API 拉取实例指标。两条路各有适用场景我简单对比一下。Agent 直采的优势是覆盖面广、实时性强。除了 CPU、内存、磁盘这类云监控也有的指标它还能采集日志内容、进程状态、端口连通性、容器事件和链路数据而且采集间隔可以控制在秒级对 DevOps 实践中的发布监控、异常定位更有价值。缺点是需要维护 Agent 本身的部署、升级和故障恢复。云监控拉取的方式优势是部署成本低不需要在每台机器上装 Agent适合只想看基础资源水位、不想管理采集组件的轻量场景。缺点也很明显拿不到日志和链路指标维度偏少且拉取频率受云厂商 API 限制通常在分钟级。对于 DevOps Agent 这种强调自动化反馈的场景分钟级延迟往往来不及发现问题。所以我的建议是如果你的团队已经在用观测云做统一的日志检索、链路追踪和告警那优先选择 Agent 直采只有对极少数无法安装 Agent 的托管资源才退回云监控拉取作为补充。我这次的实际方案也是以直采为主只对少数 RDS 和 ELB 这类托管组件保留 API 拉取。1.3 权限与网络边界接入前必须先画好的两条线接入 AWS 资源时最容易出问题的其实不是 Agent 本身的配置而是“Agent 以什么身份访问 AWS API”和“Agent 的数据能否顺利出网”。这两条线如果在设计阶段没画清楚后面排错会非常痛苦。先说身份权限。Agent 如果部署在 EC2 或 EKS 节点上强烈建议使用 IAM Role 而不是在配置文件里硬编码 AK/SK。原因很简单长期密钥一旦泄露影响面是整个账号而 IAM Role 配合临时凭证可以有效缩小风险范围还能通过角色策略精确控制 Agent 具备的权限。我这次统一采用 EC2 实例角色和 EKS IRSA 两种方式分别覆盖虚拟机场景和工作负载场景后面专门有一节讲具体配置。再说网络边界。Agent 上报数据需要能访问观测云的接入点如果你的实例在私有子网且没有 NAT 网关或者安全组没有放通 443 出方向Agent 进程会一直显示运行中但数据怎么都到不了观测云。排查时还容易误判成 Token 问题。这类问题最好在规划网络时就检查一遍域名解析、出网策略、安全组规则、代理环境变量等一次位。2. 环境准备与 AWS 侧配置2.1 准备 AWS CLI 并校验身份后续所有 AWS 侧的资源配置我基本都通过 AWS CLI 完成所以第一步先把本地的 AWS CLI 装好并验证身份。现在 AWS CLI 已经出到 v2安装方式很简单Linux 和 macOS 都能用官方脚本装Windows 也有对应的安装包。装完后先配置默认身份。如果本机使用的是长期 AK/SK可以执行aws configure依次输入 Access Key ID、Secret Access Key 和默认区域。如果团队使用 SSO 或临时凭证也可以把凭证配置在~/.aws/credentials的指定 profile 里执行命令时通过--profile指定。配置完成后务必先跑一条命令确认身份和权限范围aws sts get-caller-identity aws ec2 describe-regions --region ap-southeast-1第一条命令会显示当前调用者的 Account ID、Arn 和 UserId确认你用的就是预期账号和身份第二条命令验证是否有基本的 EC2 读权限。如果这两条命令都能正常返回说明 AWS 侧的基础访问通道是通的后续创建角色、查询实例元数据时不会再被卡在最外层。2.2 创建最小权限的 IAM 角色团队如果对 AWS 权限管理有要求比如通过了 Well-Architected 相关评审那“最小权限”四个字几乎是硬指标。Agent 采集数据时确实需要访问一些 AWS API比如查询实例标签、获取 Auto Scaling 组信息、读取 EKS 节点状态等但没必要把 AdministratorAccess 挂上去。以一个部署在 EC2 上的 Agent 角色为例我使用的信任策略比较简单允许 EC2 服务代入该角色{ Version: 2012-10-17, Statement: [ { Effect: Allow, Principal: { Service: ec2.amazonaws.com }, Action: sts:AssumeRole } ] }角色本身的权限策略按实际采集需求收敛。比如需要读取实例资源和标签时可以给ec2:Describe*相关权限需要访问 S3 中的日志文件时另加对应桶的s3:GetObject和s3:ListBucket。永远遵循一个原则只开当前需要的权限后续缺了再加。用 AWS CLI 创建角色也很直接把信任策略保存成trust-policy.json然后执行aws iam create-role --role-name guance-agent-role --assume-role-policy-document file://trust-policy.json aws iam attach-role-policy --role-name guance-agent-role --policy-arn arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess最后再把角色附加到实例上。在 EC2 控制台选中目标实例依次点击“操作 - 安全 - 修改 IAM 角色”选择刚才创建的角色即可。如果实例已经运行这种附加方式无需重启实例几秒内就能生效Agent 后续通过实例元数据服务就能拿到临时凭证。2.3 EKS 场景下的 IRSA 配置容器场景比虚拟机多一层身份映射。Pod 不能直接使用 EC2 实例角色最常见的方式是 IRSA也就是让 Kubernetes ServiceAccount 关联到一个 IAM RolePod 运行时通过 OIDC 换取临时凭证。这种方式比把 AK/SK 放到 Secret 里安全得多也符合 DevOps 的自动化管理习惯。IRSA 配置分三步走。第一步确认 EKS 集群已经创建了 OIDC Provider可以用下面的命令查看aws eks describe-cluster --name my-cluster --query cluster.identity.oidc.issuer --output text第二步创建 IAM Role信任策略里的 Principal 换成 EKS 的 OIDC ProviderCondition 中限制sub为指定的 ServiceAccount。这一步如果写错 namespace 或 ServiceAccount 名Pod 代入角色时会直接失败。第三步在 Deployment 的spec.template.spec.serviceAccountName里指定 ServiceAccount并在 ServiceAccount 上添加注解eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/guance-agent-sa-role。配置完成后进入 Pod 执行aws sts get-caller-identity能正确返回角色信息就说明 IRSA 生效了。我这次在 EKS 集群上调了整整一个下午才把 IRSA 跑通最后定位到问题出在 OIDC Provider 的 thumbprint 过期重新更新后才恢复正常。所以后面在排查 Pod 权限问题时我建议先检查 OIDC Provider 状态再检查 ServiceAccount 注解不要一上来就怀疑 Agent 配置。2.4 网络连通性检查清单网络问题往往比权限问题更隐蔽。Agent 进程一直活着日志没有明显报错但工作空间里就是看不到数据这种时候十有八九是数据根本没送出去。为避免这类情况我在正式安装 Agent 前会先执行一轮连通性检查。检查项主要是三条。第一实例能否解析观测云接入点的域名用nslookup或dig确认解析结果正常。第二实例能否在 443 端口访问接入点地址可以用curl -v https://接入点域名做一次测试能返回 HTTP 响应就说明出网正常。第三时间是否同步AWS 的临时凭证签名对时间偏移非常敏感偏差超过几分钟就会出现签名过期错误建议提前确认 NTP 服务正常运行。如果实例在私有子网且没有绑定公网 IP还需要确认 NAT 网关或其它出网通道存在。安全组也要放行出站 443 端口网络 ACL 同样不能挡。我自己踩过一个坑单独放行了安全组但忘了子网关联的网络 ACL 还在默认 deny 状态结果排查了快半小时。3. Agent 安装与配置实操3.1 安装前要确认的四件事到这一步AWS 侧的身份和网络已经打通可以开始安装 Agent 了。但别急着执行安装命令先把下面四件事确认完能省掉后面很多无意义的重试。第一确认实例的操作系统和架构。观测云的 Agent 提供多种安装包覆盖主流 Linux 发行版、Windows 和容器镜像架构上要区分 x86_64 和 ARM64。如果服务器是 Graviton 实例选了 x86 的安装包安装完会出现各种诡异进程异常。第二确认观测云工作空间的接入地址和 Token。Token 相当于 Agent 上报数据的身份凭证在观测云控制台对应工作空间里可以找到。不同环境的 Token 要分开管理比如生产环境和测试环境各用各的避免数据串空间。第三检查端口和资源占用。Agent 默认会监听一个本地端口用于状态查询和数据调试如果这个端口和业务冲突需要在配置里改掉。资源方面Agent 常驻内存大约在 200 到 500 MB 之间具体看开启的采集插件数量和数据量建议给实例预留至少 1 GB 的余量磁盘上日志文件也要考虑滚动清理。第四想清楚要给这台机器打什么标签。标签是后面数据聚合和权限分级的关键维度比如env:prod、team:payment、region:ap-southeast-1。如果标签不统一团队看板时就得靠 IP 猜机器相当痛苦。3.2 Linux 实例安装 Agent确认完上面四项安装过程本身就比较机械了。观测云提供了一键安装脚本也支持手动下载安装包我习惯用脚本方式做快速验证用包管理方式做批量交付。以最常见的 Debian/Ubuntu 系统为例一键安装的命令类似下面这样核心变量是工作空间接入地址和 TokenDK_ENDPOINThttps://接入点域名 DK_TOKEN工作空间Token bash -c $(curl -L https://static.guance.com/installer/datakit/install.sh)安装完成后服务会自动注册为 systemd 服务。用下面两条命令确认运行状态systemctl status datakit datakit monitordatakit monitor是一个非常有用的交互式界面能直接看到采集器运行状态、采集点数、错误信息和上报队列情况。如果采集器出现红色状态基本上能从界面上直接看到原因比如权限错误、网络超时或配置文件解析失败省去翻日志的功夫。对于需要批量部署的服务器我建议把 Token 和接入点统一放在环境变量或者集中配置里下发不要每台机器手敲避免出现生产环境配了测试 Token 的乌龙。如果用了配置管理工具这一步完全可以写进 Playbook 或 Terraform 模板里。3.3 关键采集配置与标签规范Agent 安装完成后核心工作在配置采集器。观测云的 Agent 通过主配置文件加采集器配置的方式来启用不同数据采集能力常见采集场景包括系统指标、日志、容器、APM 链路和安全巡检。系统指标采集器一般默认启用不需要额外配置主要采集 CPU、内存、磁盘、网络和进程数据。日志采集器需要指定日志文件路径和解析规则例如 Nginx 访问日志、应用 error.log、系统 secure 日志等每类日志对应一套 source 和 type方便后续在观测云侧做全文检索。容器采集器用于 EKS 或 ECS 场景需要让 Agent 以足够权限访问 Kubernetes API 或 Docker Socket通过 ServiceAccount 的权限配置来控制范围。链路口径则推荐与标准协议对齐应用侧通过 OpenTelemetry 或其它协议把 Trace 数据发给 Agent再由 Agent 统一上报。标签部分我在每台主机的 Agent 配置中添加了统一的全局标签[global_tags] env prod team devops region ap-southeast-1标签的作用不仅是分类查看更重要的是后续告警通知和仪表盘变量能基于标签做过滤。比如接收告警时只看teamdevops的消息仪表盘切换环境时用env标签维度做联动。标签规范最好在建项目初期就定好中途改标签会导致历史数据断链观测云的对比分析功能就发挥不出来了。3.4 使用配置管理工具下发 Agent如果只有一两台机器手动安装完全没有问题但像我们这样几十台 EC2 加一套 EKS 集群手动配置不现实。我这次采用了 GitOps 的思路把 Agent 的安装脚本、配置模板和标签策略全部放到代码仓库里用自动化工具统一推送到目标实例。一个很自然的做法是用 Terraform 管理 AWS 资源同时用用户数据脚本在实例首次启动时自动安装并配置 Agent。用户数据脚本可以读取从 Terraform 传入的变量比如环境、标签、Token 等这样新扩容的实例一加入负载均衡就能自动出现在观测云的资源列表里不需要再人工登录补装 Agent。EKS 场景则是把 Agent 以 DaemonSet 或 Deployment 方式部署到集群中用 Helm Chart 管理。需要监控的平台组件单独起一个 DaemonSet采集节点指标和容器日志需要关联业务 Trace 的则以 Sidecar 或中心 Agent 的方式接入。发布流程走 Helm 升级回滚也方便。整套配置都进 Git任何改动都有审计记录这对 DevOps 团队落地来说很重要。4. 数据上报校验与观测云侧配置4.1 本地自检先确认数据已经生成Agent 装完不代表数据已经进空间。我习惯在观测云控制台查看数据之前先在本地做一轮自检确认 Agent 确实采集到了数据。最直接的方式是查看 Agent 的上报统计。通过datakit monitor界面能看到每个采集器的采集次数、字节数和错误数。如果采集器状态是绿色且错误数为零说明数据已经正常上报。如果想更加精细地确认某条数据可以通过 Agent 的调试接口查询。执行下面的命令能看到最近一段时间内 Agent 缓存的数据包情况判断指标、日志、对象数据是否齐全curl -s http://127.0.0.1:9529/stats | jq .data如果采集数据为零重点检查两部分。一是采集器配置是否真的加载了观察 Agent 启动日志里有没有解析成功的信息。二是 Tag 是否正确匹配了采集范围比如日志采集器指定的路径和实际日志路径不一致就会出现采集器一直运行但采集不到内容的假象。4.2 观测云侧核验数据接入本地确认采集到了数据再去观测云控制台核验数据是否真的入库。这一步一般在“基础设施”或“指标”页面里看确认对应主机或工作负载已经出现在资源列表里并且指标曲线正常滚动更新。如果本地显示上报成功但观测云侧看不到数据优先检查 Token 和接入点是否匹配。观测云的接入地址有地域属性Agent 配置的接入点必须和控制台提示的工作空间地址保持一致。Token 也一样工作空间之间不通用。这里有一个小经验在 Agent 配置里通过环境变量方式传入 Token不同环境用不同的变量值能有效避免串 Token。数据入库后建议立刻建立一个最小化的仪表盘把 CPU 使用率、内存使用率、磁盘使用率和日志采集量这几个基础视图放上去。这样既能验证数据链路是通的也方便后续逐步补充业务相关的视图。我之前一上来就画复杂大屏结果数据有问题排查时反而被一堆空视图干扰。4.3 配置告警规则让数据产生价值数据进了观测云如果只满足于“能看到”那这套系统还停留在监控阶段离 DevOps 要求的“快速反馈”还有距离。真正让数据产生价值的是告警规则的配置。我这次主要配了三类告警。第一类是基础设施告警比如 CPU 使用率超过 90% 持续 10 分钟、磁盘使用率超过 85%、进程意外退出等这类告警直接关联到具体主机或集群接收人一般是 SRE 和运维。第二类是日志关键字告警比如应用日志里出现OutOfMemoryError、Connection refused这类明显异常按服务维度分派给对应研发负责人。第三类是链路健康告警比如某条核心链路的错误率超过阈值或 P99 延迟明显升高。这类告警往往在用户感知之前就能发现问题。告警要避免一个常见误区规则设得太多太碎最后所有消息都变成了“狼来了”。比较好的做法是先只对少部分核心指标配置电话和短信级别的告警其它都走群通知观察一周后再根据实际效果调整阈值和聚合维度。DevOps 讲究持续改进告警规则也不是一成不变的每个月复盘一次告警的命中率和误报率很有必要。5. 常见问题与排查技巧实录5.1 高频问题速查表在实际接入过程中我记录了下面这些高频问题。很多问题不只在我们的环境里出现过和同行交流时他们也踩过类似的坑所以整理成速查表方便团队遇到同类问题时快速定位。问题现象可能原因排查方向Agent 进程运行但无数据上报网络不通、Token 错误、接入点地域不匹配先查本地上报统计再 curl 测试接入点连通性数据有延迟曲线滞后较久采集间隔过大或批量上报队列堵塞调整采集间隔检查 Agent 日志中的上报耗时部分主机的数据缺失实例 IAM Role 未附加或权限不足登录实例执行aws sts get-caller-identity日志采集不到内容路径写错、日志文件权限不足查看 Agent 日志确认日志采集器状态EKS 工作负载没有数据IRSA 配置错误或 OIDC Provider 异常检查 ServiceAccount 注解和 Role 信任策略磁盘占用持续增长Agent 日志或缓冲队列文件未滚动清理配置日志轮转和采集缓存清理策略这张表不能覆盖所有情况但覆盖了 80% 的常见问题。如果按表排查没有结果不要急着折腾配置先把 Agent 日志打开看原始报错信息通常会比界面状态提示更直接。5.2 身份权限问题排查权限问题的表现比较有迷惑性。Agent 正常运行部分指标能采到但某些数据就是空缺比如实例标签、EKS 事件、ASG 信息等这时候基本可以判断是 IAM 权限不足。第一步先确认实例当前的真实身份。在 EC2 实例上执行aws sts get-caller-identity如果返回的 Arn 里没有看到预期角色说明实例元数据服务没有取到正确的 IAM Role或者实例上根本没有附加角色。进一步可以查询实例元数据确认curl -s http://169.254.169.254/latest/meta-data/iam/security-credentials/正常情况下这条命令会返回角色名称。如果连接超时可能是实例元数据服务被禁用或实例处于较老的 VPC 子网中无法访问链路本地地址。如果角色存在但权限不到位就要回到 IAM 策略本身检查 Action 和 Resource 的匹配。EKS 场景的排查重点在 IRSA。先看 ServiceAccount 的注解是不是写错了环境变量里的 Role Arn再看 IAM Role 的信任策略里的 OIDC Provider 地址和集群是否一致。一个容易忽略的点是如果集群是后来才创建的 OIDC ProviderIAM Role 里的issuer地址可能用的是旧值需要重新生成。5.3 日志与链路数据缺失的排查日志和链路数据丢失是最容易被误判的一类问题。很多人第一反应是“云平台又丢数据了”但实际查下来绝大多数情况出在采集配置上。日志缺失时先确认文件路径是否真实存在以及运行 Agent 的用户对文件是否有读权限。很多应用日志存放在业务用户目录下Agent 如果以 root 部署问题不大但如果是普通用户安装很可能连文件列表都看不到更别说采集。另一种情况是文件被 logrotate 切分Agent 没正确识别新文件名可以通过通配符方式解决。链路数据缺失时优先检查应用是否真的把请求代理到了 Agent 的采集端口。很多接入链路追踪的开发同学只改了代码里的上报地址却忘了检查网络策略是否允许访问该端口。如果 Agent 和服务不在同一台主机还要看安全组有没有放通对应端口。不管是日志还是链路问题排查时都可以借助 Agent 自带的调试能力查看最近的上报状态和错误信息。相比直接去工作空间里刷页面这种方式反馈更实时、定位更准确。6. 从“能采”到“好用”的进阶落地6.1 用 GitOps 管理 Agent 配置Agent 接入跑通只是第一步真正让这套体系可维护必须把所有配置纳入版本管理。我们现在把 Agent 安装脚本、配置模板、标签规范、告警规则模板全部放在一个 Git 仓库里每次变更是代码评审、自动测试、灰度发布、全量生效的流程。比如修改一台主机的自定义标签传统做法是登录服务器改配置文件然后重启 Agent在几十台机器的环境下很容易漏改。现在通过修改 Git 仓库中的配置模板再用自动化工具统一渲染和下发配合 CI 校验配置格式基本不会出现配置漂移。这里推荐把 Agent 的安装和配置也纳入 Terraform 或其它基础设施即代码工具的管理范围而不是单独维护一套脚本。这样资源的创建、Agent 的安装和观测云侧的配置就形成一个整体新扩容机器时不再需要人工介入DevOps 的自动化价值才能真正体现。6.2 把可观测性引入 CI/CD 流水线Agent 接入观测云之后最容易忽略的是和现有 CI/CD 流水线打通。传统的发布流程通常关注代码构建、镜像推送、应用部署极少把“可观测性验证”作为发布门禁的一环。这次我们的做法是在发布流水线里增加两步第一步是发布前检查。从观测云工作空间确认新版本涉及的机器或工作负载已经有数据上报没有空白期的迹象。这个检查不需要太复杂通过接口查询告警事件确认没有新增的严重告警即可。第二步是发布后校验。在流水线里调用观测云接口查询指定服务的错误率和 P99 延迟如果连续几次查询都超过阈值自动化触发回滚。这套机制把可观测性从“事后看板”变成了“发布门禁”发布过程中的异常能够第一时间被自动化流程捕获。当然这一步需要在观测云侧先设置好对应的接口权限和调用凭据同时要在流水线里配置好合理的超时和重试策略避免因为查询接口偶发超时阻塞整个发布。一次配置完成后后续新服务接入只需要修改服务名和指标阈值整体维护成本很低。6.3 定期巡检与容量规划Agent 接入不是一锤子买卖长期运行后需要定期巡检。我建议每月至少检查一次 Agent 的采集任务异常数、上报队列占用、磁盘缓存大小和内存使用情况。如果发现某个采集器持续报错尽快处理避免积累成数据链路的大面积故障。容量规划同样重要。随着业务增长新增的机器、日志量、指标维度都会影响 Agent 的上报压力。在核心集群上我会给 Agent 预留额外的 CPU 和内存限额并观察上报队列的堆积情况。一旦队列经常处于高水位就要考虑拆分采集任务或升级实例规格而不是等到数据开始丢弃才介入。另外观测云侧的数据存储和索引策略也值得定期审视。不同类型的日志和指标可以设置不同的保留周期比如系统指标保留 30 天业务日志保留 90 天链路数据按需缩短。这个策略既能满足排障需求也能控制成本属于长期的运维新常态。我个人的体会是Agent 接入只是可观测性体系的一块基石真正拉开团队之间差距的是拿到数据之后能不能快速定位问题、能不能把数据反馈到研发流程中。AWS 环境本身提供了丰富的元数据和事件源观测云又给了统一的数据入口把两者用好DevOps 这条链路才算真正跑起来。