Vector AWS EC2 Metadata Transform用 EC2 实例元数据实时丰富日志与指标【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读aws_ec2_metadata是 Vector 中一个面向 AWS 环境的丰富enrich型 transform它通过访问 EC2 实例元数据服务IMDSv2为流经管线的每条日志Log和指标Metric自动注入实例级上下文例如instance-id、region、availability-zone、vpc-id、subnet-id、IAMrole-name以及实例标签tags。读完本文你将掌握该 transform 的完整配置项与默认值、它与 IMDSv2 的底层交互机制token 获取、定时刷新、字段来源映射、在日志与指标上的差异化输出形态以及 Docker 部署、实例标签访问等前置要求。功能概览为事件补上“实例身份”在 AWS EC2 上大规模采集日志或指标时原始事件往往只携带主机进程数据缺乏可用于分组、聚合与故障定位的云环境上下文。aws_ec2_metadatatransform 正是为解决这一问题而存在它以纯旁路方式egress_method: stream无状态见 CUE 定义周期性查询本机 IMDS把查询结果缓存到共享状态再在事件流过时以 O(1) 的插入/打标方式附加到事件上对数据面吞吐的影响极小。其输入输出能力见 CUE 输入输出定义为输入Log与全部指标类型counter、distribution、gauge、histogram、set、summary输出仍是Log或Metric但已携带 EC2 元数据字段不支持Trace源码中Event::Trace(_) panic!(Traces are not supported.)见 transform_one。该组件的开发状态标记为stable适用于生产环境。工作原理IMDSv2、Token 与后台刷新数据来源与 IMDSv2 鉴权默认元数据端点为http://169.254.169.254链路本地地址。实现严格遵循 EC2 Instance Metadata Service 第 2 版IMDSv2的流程见 MetadataClient 实现获取 Token向PUT /latest/api/token发起请求携带X-aws-ec2-metadata-token-ttl-seconds: 21600头换取有效期 6 小时的会话 Token见 get_token。Token 过期前会按 6 小时周期自动续期。携带 Token 拉取元数据每个元数据子路径的 GET 请求都会带上X-aws-ec2-metadata-token头见 get_metadata。HTTP 404 会被视为“该字段不存在”而安全跳过其他非 200 状态码则视为错误。字段与元数据路径的映射不同字段来自不同元数据路径路径常量定义见 源码 L56-L87输出字段IMDS 路径说明account-id、ami-id、instance-id、instance-type、region/latest/dynamic/instance-identity/document一次 JSON 请求反序列化为IdentityDocumentcamelCase同时取得多个字段availability-zone/latest/meta-data/placement/availability-zonelocal-hostname/local-ipv4/latest/meta-data/local-hostname/local-ipv4public-hostname/public-ipv4/latest/meta-data/public-hostname/public-ipv4未分配公网地址时 IMDS 返回 404字段自动省略subnet-id/vpc-id先取/latest/meta-data/mac再请求/latest/meta-data/network/interfaces/macs/{mac}/subnet-id与.../vpc-id基于默认网卡 MAC 二次拼接路径见 refresh_metadatarole-name/latest/meta-data/iam/security-credentials/该路径返回按行分隔的多个角色名因此输出为数组tags.*/latest/meta-data/tags/instance/{tag}每个配置的标签单独发起一次请求见 L571-L587后台刷新与共享状态组件启动时build阶段见 L206-L254会先执行一次初始refresh_metadata()随后把刷新循环作为一个独立的 tokio 后台任务运行按refresh_interval_secs周期重查元数据并通过ArcSwap原子地整体替换缓存状态state: ArcArcSwapVec(MetadataKey, Bytes)。事件处理时transform_one只读取这份共享快照因此主数据路径上没有任何网络 I/O。值得注意的是每次刷新是“先全部拉取、再一次替换”注释见 L461-L462避免刷新中途事件读到字段不完整的混合状态。日志与指标的不同附加形态对Log 事件元数据以字段field形式插入role-name为数组、tags为对象见 enrich 测试期望值对Metric 事件元数据以**标签tag**形式挂载数组/对象被拍平为role-name[0]、tags[Name]这类带索引/键名的标签名见 expected_metric_fields。此外如果输入事件的 schema 不是对象例如纯字符串日志transform 会先将其转换为对象再附加字段见 outputs并由测试 schema_def_with_string_input 验证。配置项详解以下配置项定义见 generated/aws_ec2_metadata.cue对应的 Rust 结构体与默认值见 Ec2Metadata 及默认函数 L145-L170。配置项类型默认值说明endpointstringhttp://169.254.169.254覆盖默认 EC2 元数据端点支持host别名#[serde(alias host)]常用于测试或代理场景namespacestring无空为所有新增字段设置统一前缀例如ec2或aws.ec2空字符串表示不加前缀fieldsarray[ami-id, availability-zone, instance-id, instance-type, local-hostname, local-ipv4, public-hostname, public-ipv4, region, subnet-id, vpc-id, role-name]需要注入的元数据字段白名单注意account-id默认不在其中身份文档中此字段非必填tagsarray[]需要注入的实例标签名列表如[Name, Project]实例标签需先在 AWS 侧显式启用见下文前置要求refresh_interval_secsuint10后台查询最新元数据的间隔秒refresh_timeout_secsuint1单次元数据请求的超时时间秒超时会使本次刷新失败requiredbooltrue为true时若启动阶段无法成功查询元数据transform 构建直接失败、Vector 不启动为false时降级为记录错误并继续运行proxyobject无HTTP(S) 代理配置支持按协议区分、设置不代理的主机未显式配置时与全局代理合并ProxyConfig::merge_with_env见 build同时支持通过环境变量配置代理http_proxy、HTTP_PROXY、https_proxy、HTTPS_PROXY、no_proxy、NO_PROXY见 CUE env_vars 定义。关于requiredfalse的容错语义requiredfalse的典型场景是在可能未部署于 EC2或 IMDS 暂时不可达的环境下先启动 Vector。其行为有集成测试佐证not_required 测试构建阶段刷新失败仅发出AwsEc2MetadataRefreshError内部事件而不阻止启动此后后台任务会持续重试。反之requiredtrue默认时启动期失败会直接导致构建报错。完整配置示例以下是一个可直接落地的配置为日志与指标统一注入 EC2 元数据启用标签并把字段统一放到ec2命名空间下避免与事件原有字段冲突transforms: enrich_ec2: type: aws_ec2_metadata inputs: - my_source # 覆盖默认端点默认 http://169.254.169.254 # endpoint: http://169.254.169.254 namespace: ec2 fields: - ami-id - availability-zone - instance-id - instance-type - local-hostname - local-ipv4 - public-hostname - public-ipv4 - region - subnet-id - vpc-id - role-name - account-id tags: - Name - Project refresh_interval_secs: 10 refresh_timeout_secs: 1 required: true加上namespace: ec2后日志事件会得到ec2.instance-id、ec2.region、ec2.tags.Name等字段指标则会得到ec2.instance-id、ec2.tags[Name]等标签。输出字段说明transform 在日志事件上可能产出的全部字段及说明见 CUE output 定义字段是否默认必填示例值account-id否默认不采集123456789ami-id是ami-00068cd7555f543d5availability-zone是us-east-1ainstance-id是i-096fba6d03d36d262instance-type是m4.largelocal-hostname是ip-172-31-93-227.ec2.internallocal-ipv4是172.31.93.227public-hostname是ec2-54-234-246-107.compute-1.amazonaws.compublic-ipv4是54.234.246.107region是us-east-1role-name是数组[some_iam_role]subnet-id是subnet-9d6713b9vpc-id是vpc-a51da4dctags否{Name: InstanceName, ApplicationId: 12345678}account-id之所以标记为非必填且默认不在fields白名单中是因为身份文档结构在不同账号下字段可能缺失源码中IdentityDocument的该字段也允许缺省#[allow(dead_code)]反序列化见 L356-L368若需要请在fields中显式追加。前置要求与使用注意事项依据 CUE requirements 与 warnings有三点必须注意Docker 部署需提高 Hop Limit在 EC2 上以 Docker 运行 Vector 时元数据请求需要经过 2 跳网络默认 1 跳会失败。必须执行aws ec2 modify-instance-metadata-options --instance-id ID --http-endpoint enabled --http-put-response-hop-limit 2实例标签必须显式开启要采集tags需在 AWS 控制台或通过 CLI 为该实例开启实例元数据标签访问aws ec2 modify-instance-metadata-options --instance-id ID --instance-metadata-tags enabled不要在 Aggregator 节点上启用该 transform如果你把 Vector 当作日志聚合器Aggregator运行千万不要启用此组件——它读取的是Aggregator 节点自身的元数据服务而非客户端节点的元数据打上的标签与来源客户端毫无关系会造成错误关联。可观测性刷新指标与内部事件组件暴露两个与元数据刷新相关的内部指标见 CUE telemetry 定义 与 内部事件实现metadata_refresh_successful_total后台刷新成功的累计次数每次成功刷新计数 1metadata_refresh_failed_total后台刷新失败的累计次数同时会以error_typerequest_failed、stageprocessing的标签计入component_errors_total。可通过internal_metrics源观察这两个计数器用于判断 IMDS 可达性与刷新频率是否符合预期例如频繁失败时应检查 Hop Limit、安全组或 IAM 配置。测试验证组件行为如何被保证aws_ec2_metadata的实现质量由一套模拟 IMDS 的集成测试保障aws-ec2-metadata-integration-testsfeature测试见 src/transforms/aws_ec2_metadata.rs#L749-L1247可用EC2_METADATA_ADDRESS环境变量指向本地 mock默认http://localhost:1338enrich_log/enrich_metric验证默认字段 account-id 多个标签在日志字段与指标标签上的完整注入结果包括不存在的标签被安全跳过fields_log/fields_metric验证fields白名单过滤后仅注入指定字段namespace_log/namespace_metric验证namespace前缀含显式空命名空间在日志路径与指标标签上的表现timeout验证refresh_timeout_secs1时对慢端点的超时失败路径not_required验证requiredfalse时端点不可达也能正常构建启动。这些测试同时通过assert_transform_compliance校验组件生命周期与拓扑合规性可作为你在本地验证配置行为的参考入口。小结aws_ec2_metadatatransform 以极低的运行开销把 EC2 实例元数据无缝注入到日志与指标事件中是构建可分组、可关联、可追溯的 AWS 观测管线的关键一环。使用时只需重点确认三点Docker 下的 Hop Limit、实例标签的显式开启以及不要在 Aggregator 节点上误用其余细节字段白名单、命名空间、刷新节奏、代理与超时均可通过上述配置项精细调优。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vector AWS EC2 Metadata Transform用 EC2 实例元数据实时丰富日志与指标【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读aws_ec2_metadata是 Vector 中一个面向 AWS 环境的丰富enrich型 transform它通过访问 EC2 实例元数据服务IMDSv2为流经管线的每条日志Log和指标Metric自动注入实例级上下文例如instance-id、region、availability-zone、vpc-id、subnet-id、IAMrole-name以及实例标签tags。读完本文你将掌握该 transform 的完整配置项与默认值、它与 IMDSv2 的底层交互机制token 获取、定时刷新、字段来源映射、在日志与指标上的差异化输出形态以及 Docker 部署、实例标签访问等前置要求。功能概览为事件补上“实例身份”在 AWS EC2 上大规模采集日志或指标时原始事件往往只携带主机进程数据缺乏可用于分组、聚合与故障定位的云环境上下文。aws_ec2_metadatatransform 正是为解决这一问题而存在它以纯旁路方式egress_method: stream无状态见 CUE 定义周期性查询本机 IMDS把查询结果缓存到共享状态再在事件流过时以 O(1) 的插入/打标方式附加到事件上对数据面吞吐的影响极小。其输入输出能力见 CUE 输入输出定义为输入Log与全部指标类型counter、distribution、gauge、histogram、set、summary输出仍是Log或Metric但已携带 EC2 元数据字段不支持Trace源码中Event::Trace(_) panic!(Traces are not supported.)见 transform_one。该组件的开发状态标记为stable适用于生产环境。工作原理IMDSv2、Token 与后台刷新数据来源与 IMDSv2 鉴权默认元数据端点为http://169.254.169.254链路本地地址。实现严格遵循 EC2 Instance Metadata Service 第 2 版IMDSv2的流程见 MetadataClient 实现获取 Token向PUT /latest/api/token发起请求携带X-aws-ec2-metadata-token-ttl-seconds: 21600头换取有效期 6 小时的会话 Token见 get_token。Token 过期前会按 6 小时周期自动续期。携带 Token 拉取元数据每个元数据子路径的 GET 请求都会带上X-aws-ec2-metadata-token头见 get_metadata。HTTP 404 会被视为“该字段不存在”而安全跳过其他非 200 状态码则视为错误。字段与元数据路径的映射不同字段来自不同元数据路径路径常量定义见 源码 L56-L87输出字段IMDS 路径说明account-id、ami-id、instance-id、instance-type、region/latest/dynamic/instance-identity/document一次 JSON 请求反序列化为IdentityDocumentcamelCase同时取得多个字段availability-zone/latest/meta-data/placement/availability-zonelocal-hostname/local-ipv4/latest/meta-data/local-hostname/local-ipv4public-hostname/public-ipv4/latest/meta-data/public-hostname/public-ipv4未分配公网地址时 IMDS 返回 404字段自动省略subnet-id/vpc-id先取/latest/meta-data/mac再请求/latest/meta-data/network/interfaces/macs/{mac}/subnet-id与.../vpc-id基于默认网卡 MAC 二次拼接路径见 refresh_metadatarole-name/latest/meta-data/iam/security-credentials/该路径返回按行分隔的多个角色名因此输出为数组tags.*/latest/meta-data/tags/instance/{tag}每个配置的标签单独发起一次请求见 L571-L587后台刷新与共享状态组件启动时build阶段见 L206-L254会先执行一次初始refresh_metadata()随后把刷新循环作为一个独立的 tokio 后台任务运行按refresh_interval_secs周期重查元数据并通过ArcSwap原子地整体替换缓存状态state: ArcArcSwapVec(MetadataKey, Bytes)。事件处理时transform_one只读取这份共享快照因此主数据路径上没有任何网络 I/O。值得注意的是每次刷新是“先全部拉取、再一次替换”注释见 L461-L462避免刷新中途事件读到字段不完整的混合状态。日志与指标的不同附加形态对Log 事件元数据以字段field形式插入role-name为数组、tags为对象见 enrich 测试期望值对Metric 事件元数据以**标签tag**形式挂载数组/对象被拍平为role-name[0]、tags[Name]这类带索引/键名的标签名见 expected_metric_fields。此外如果输入事件的 schema 不是对象例如纯字符串日志transform 会先将其转换为对象再附加字段见 outputs并由测试 schema_def_with_string_input 验证。配置项详解以下配置项定义见 generated/aws_ec2_metadata.cue对应的 Rust 结构体与默认值见 Ec2Metadata 及默认函数 L145-L170。配置项类型默认值说明endpointstringhttp://169.254.169.254覆盖默认 EC2 元数据端点支持host别名#[serde(alias host)]常用于测试或代理场景namespacestring无空为所有新增字段设置统一前缀例如ec2或aws.ec2空字符串表示不加前缀fieldsarray[ami-id, availability-zone, instance-id, instance-type, local-hostname, local-ipv4, public-hostname, public-ipv4, region, subnet-id, vpc-id, role-name]需要注入的元数据字段白名单注意account-id默认不在其中身份文档中此字段非必填tagsarray[]需要注入的实例标签名列表如[Name, Project]实例标签需先在 AWS 侧显式启用见下文前置要求refresh_interval_secsuint10后台查询最新元数据的间隔秒refresh_timeout_secsuint1单次元数据请求的超时时间秒超时会使本次刷新失败requiredbooltrue为true时若启动阶段无法成功查询元数据transform 构建直接失败、Vector 不启动为false时降级为记录错误并继续运行proxyobject无HTTP(S) 代理配置支持按协议区分、设置不代理的主机未显式配置时与全局代理合并ProxyConfig::merge_with_env见 build同时支持通过环境变量配置代理http_proxy、HTTP_PROXY、https_proxy、HTTPS_PROXY、no_proxy、NO_PROXY见 CUE env_vars 定义。关于requiredfalse的容错语义requiredfalse的典型场景是在可能未部署于 EC2或 IMDS 暂时不可达的环境下先启动 Vector。其行为有集成测试佐证not_required 测试构建阶段刷新失败仅发出AwsEc2MetadataRefreshError内部事件而不阻止启动此后后台任务会持续重试。反之requiredtrue默认时启动期失败会直接导致构建报错。完整配置示例以下是一个可直接落地的配置为日志与指标统一注入 EC2 元数据启用标签并把字段统一放到ec2命名空间下避免与事件原有字段冲突transforms: enrich_ec2: type: aws_ec2_metadata inputs: - my_source # 覆盖默认端点默认 http://169.254.169.254 # endpoint: http://169.254.169.254 namespace: ec2 fields: - ami-id - availability-zone - instance-id - instance-type - local-hostname - local-ipv4 - public-hostname - public-ipv4 - region - subnet-id - vpc-id - role-name - account-id tags: - Name - Project refresh_interval_secs: 10 refresh_timeout_secs: 1 required: true加上namespace: ec2后日志事件会得到ec2.instance-id、ec2.region、ec2.tags.Name等字段指标则会得到ec2.instance-id、ec2.tags[Name]等标签。输出字段说明transform 在日志事件上可能产出的全部字段及说明见 CUE output 定义字段是否默认必填示例值account-id否默认不采集123456789ami-id是ami-00068cd7555f543d5availability-zone是us-east-1ainstance-id是i-096fba6d03d36d262instance-type是m4.largelocal-hostname是ip-172-31-93-227.ec2.internallocal-ipv4是172.31.93.227public-hostname是ec2-54-234-246-107.compute-1.amazonaws.compublic-ipv4是54.234.246.107region是us-east-1role-name是数组[some_iam_role]subnet-id是subnet-9d6713b9vpc-id是vpc-a51da4dctags否{Name: InstanceName, ApplicationId: 12345678}account-id之所以标记为非必填且默认不在fields白名单中是因为身份文档结构在不同账号下字段可能缺失源码中IdentityDocument的该字段也允许缺省#[allow(dead_code)]反序列化见 L356-L368若需要请在fields中显式追加。前置要求与使用注意事项依据 CUE requirements 与 warnings有三点必须注意Docker 部署需提高 Hop Limit在 EC2 上以 Docker 运行 Vector 时元数据请求需要经过 2 跳网络默认 1 跳会失败。必须执行aws ec2 modify-instance-metadata-options --instance-id ID --http-endpoint enabled --http-put-response-hop-limit 2实例标签必须显式开启要采集tags需在 AWS 控制台或通过 CLI 为该实例开启实例元数据标签访问aws ec2 modify-instance-metadata-options --instance-id ID --instance-metadata-tags enabled不要在 Aggregator 节点上启用该 transform如果你把 Vector 当作日志聚合器Aggregator运行千万不要启用此组件——它读取的是Aggregator 节点自身的元数据服务而非客户端节点的元数据打上的标签与来源客户端毫无关系会造成错误关联。可观测性刷新指标与内部事件组件暴露两个与元数据刷新相关的内部指标见 CUE telemetry 定义 与 内部事件实现metadata_refresh_successful_total后台刷新成功的累计次数每次成功刷新计数 1metadata_refresh_failed_total后台刷新失败的累计次数同时会以error_typerequest_failed、stageprocessing的标签计入component_errors_total。可通过internal_metrics源观察这两个计数器用于判断 IMDS 可达性与刷新频率是否符合预期例如频繁失败时应检查 Hop Limit、安全组或 IAM 配置。测试验证组件行为如何被保证aws_ec2_metadata的实现质量由一套模拟 IMDS 的集成测试保障aws-ec2-metadata-integration-testsfeature测试见 src/transforms/aws_ec2_metadata.rs#L749-L1247可用EC2_METADATA_ADDRESS环境变量指向本地 mock默认http://localhost:1338enrich_log/enrich_metric验证默认字段 account-id 多个标签在日志字段与指标标签上的完整注入结果包括不存在的标签被安全跳过fields_log/fields_metric验证fields白名单过滤后仅注入指定字段namespace_log/namespace_metric验证namespace前缀含显式空命名空间在日志路径与指标标签上的表现timeout验证refresh_timeout_secs1时对慢端点的超时失败路径not_required验证requiredfalse时端点不可达也能正常构建启动。这些测试同时通过assert_transform_compliance校验组件生命周期与拓扑合规性可作为你在本地验证配置行为的参考入口。小结aws_ec2_metadatatransform 以极低的运行开销把 EC2 实例元数据无缝注入到日志与指标事件中是构建可分组、可关联、可追溯的 AWS 观测管线的关键一环。使用时只需重点确认三点Docker 下的 Hop Limit、实例标签的显式开启以及不要在 Aggregator 节点上误用其余细节字段白名单、命名空间、刷新节奏、代理与超时均可通过上述配置项精细调优。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
