AWS CLI put-insight-rule 实战指南：用 CloudWatch Contributor Insights 规则分析 VPC 流日志等高基数数据

AWS CLI put-insight-rule 实战指南用 CloudWatch Contributor Insights 规则分析 VPC 流日志等高基数数据【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli本篇技术指南聚焦 AWS CLI 的aws cloudwatch put-insight-rule命令讲解如何通过 Contributor Insights 规则对高基数high-cardinality日志数据如 VPC Flow Logs进行贡献者分析。你将掌握规则定义文件insight-rule.json的完整语法、命令行参数语义与取值约束并配合本仓库的官方示例与 API 模型源码理解规则从创建、启用到查询报告、清理的完整生命周期。一、为什么需要 Contributor Insights 规则高基数数据是指日志中具有大量不同取值cardinality的字段例如 VPC 流日志中的源 IP、目的端口、tcp-flag或者 Web 访问日志中的requestId、User-Agent。传统指标Metric擅长聚合数值却无法直接回答谁是最大的贡献者这类问题。CloudWatch Contributor Insights 恰好解决这一场景它持续分析指定日志组中的日志事件找出**贡献者Contributor**及其对应的贡献值。而put-insight-rule正是创建这类规则的核心命令。AWS CLI 官方文档在本仓库中给出了一个完整可运行的示例位于 awscli/examples/cloudwatch/put-insight-rule.rst本文以它为主体展开。二、命令概览与完整示例2.1 命令作用根据仓库中的 API 模型定义awscli/botocore/data/cloudwatch/2010-08-01/service-2.json 中PutInsightRule的 documentation创建一条 Contributor Insights 规则规则会评估指定 CloudWatch Logs 日志组中的日志事件找出该日志组中日志事件的贡献者数据如果创建规则后将其删除再以同名重新创建则第一次创建期间产生的历史数据可能不再可用PutInsightRule的接口说明明确提示了这一点。2.2 官方示例命令仓库中的 put-insight-rule.rst 展示了创建名为VPCFlowLogsContributorInsights规则的命令aws cloudwatch put-insight-rule \ --rule-name VPCFlowLogsContributorInsights \ --rule-definition file://insight-rule.json \ --rule-state ENABLED要点--rule-definition file://insight-rule.json表示从本地 JSON 文件读取规则定义这是避免在命令行内联长 JSON 的推荐做法该命令成功执行后不产生任何输出This command produces no output可用于脚本中静默创建规则。2.3 规则定义文件insight-rule.json完整内容示例中提供的规则定义文件内容如下{ Schema: { Name: CloudWatchLogRule, Version: 1 }, AggregateOn: Count, Contribution: { Filters: [], Keys: [ tcp-flag ] }, LogFormat: CLF, LogGroupNames: [ /vpc/flowlogs/* ], Fields: { 23: tcp-flag } }三、规则定义文件逐字段深度解析下面结合规则语法与仓库中describe-insight-rules示例describe-insight-rules.rst的返回结构逐一说明各字段含义字段类型/取值含义Schema.NameCloudWatchLogRule声明这是一条日志类 Contributor Insights 规则Schema.Version1规则语法版本AggregateOnCount等聚合方式决定贡献值的计算口径Contribution.Filters过滤条件数组空数组表示不过滤规则评估所有匹配日志事件Contribution.Keys字符串数组定义哪些字段作为贡献者维度本例按tcp-flag分组LogFormatCLF/JSON等日志格式CLF为 Common Log Format常见于 VPC 流日志LogGroupNames日志组名数组支持通配符/vpc/flowlogs/*匹配所有 VPC 流日志日志组Fields字段编号到名称的映射在CLF格式下将位置索引如23映射为语义名如tcp-flag3.1 关于LogGroupNames与LogGroupARNs示例中LogGroupNames使用带通配符的日志组名/vpc/flowlogs/*可一次性覆盖所有 VPC 流日志日志组在describe-insight-rules的返回结果中可以看到规则定义最终会被归一化为LogGroupARNs形如arn:aws:logs:us-east-1:123456789012:log-group:demo说明 AWS 服务端会将对数组名解析为 ARN 进行内部存储。3.2 规则定义在服务端的持久化形态从 describe-insight-rules.rst 的 Output 可以看到服务端返回的Definition是一个被转义的 JSON 字符串例如{ Name: Rule-A, State: ENABLED, Schema: CloudWatchLogRule/1, Definition: {\n\t\AggregateOn\: \Count\,\n\t...\n\t\LogGroupARNs\: [\arn:aws:logs:us-east-1:123456789012:log-group:demo\]\n}, ManagedRule: false }这说明put-insight-rule提交的规则定义会被 CloudWatch 服务端规范化存储如将LogGroupNames转为LogGroupARNsdescribe-insight-rules读回的是规范化后的 JSON 字符串。理解这一点有助于在编写自动化脚本时正确解析Definition字段。四、API 模型中的参数语义与约束仓库中的 service-2.json 精确描述了PutInsightRule的输入结构PutInsightRuleInput这是 AWS CLI 参数校验与序列化的底层依据必填参数requiredRuleName规则唯一名称。RuleDefinition规则定义为 JSON 对象。可选参数RuleState规则状态合法值为ENABLED和DISABLED。Tags键值对列表最多可关联 50 个标签。需额外拥有cloudwatch:TagResource权限若用于更新已存在规则此参数会被忽略修改已有规则标签应使用TagResource接口。ApplyOnTransformedLogs设为true时规则评估经过 Log transformation 转换后的日志事件默认false。类型约束来自 shape 定义参数 shape约束InsightRuleName长度 1–128仅可打印 ASCII 字符InsightRuleDefinition长度 1–8192仅 ASCII 字符InsightRuleState长度 1–32仅可打印 ASCII 字符可能抛出的错误errorsInvalidParameterValueException参数值非法MissingRequiredParameterException缺少必填参数LimitExceededException规则数量或资源达到账户/区域配额上限。HTTP 层面该操作以POST请求发送至/Query API输入结构PutInsightRuleInput由 AWS CLI 基于该模型完成序列化无需手动构造请求体。五、规则生命周期创建后的管理与查询put-insight-rule只是生命周期起点仓库中配套的示例文件构成了完整的运维闭环5.1 查询规则列表describe-insight-rulesaws cloudwatch describe-insight-rules返回当前账户下所有规则及其State、Schema、规范化后的Definition、ManagedRule是否托管规则等字段。完整输出见 describe-insight-rules.rst。5.2 获取规则时序数据get-insight-rule-reportaws cloudwatch get-insight-rule-report \ --rule-name Rule-A \ --start-time 2024-10-13T20:15:00Z \ --end-time 2024-10-13T20:30:00Z \ --period 300返回Contributors贡献者及其ApproximateAggregateValue、按period聚合的Datapoints、AggregateValue、ApproximateUniqueCount近似去重贡献者数等。完整输出见 get-insight-rule-report.rst。5.3 启用 / 禁用规则aws cloudwatch enable-insight-rules --rule-names Rule-A Rule-B aws cloudwatch disable-insight-rules --rule-names Rule-A Rule-B两者均返回Failures数组成功时为空数组[]。示例见 enable-insight-rules.rst 与 disable-insight-rules.rst。5.4 删除规则aws cloudwatch delete-insight-rules --rule-names Rule-A Rule-B同样返回Failures数组示例见 delete-insight-rules.rst。注意前文提到的删除后同名重建旧历史数据可能不可用。六、从示例到生产实践的建议规则定义文件化将insight-rule.json纳入版本管理配合--rule-definition file://...使用保证规则可审计、可回滚。区分托管规则describe-insight-rules输出中的ManagedRule: false表明这是用户自建规则托管规则managed rules由PutManagedInsightRules创建且不能用PutInsightRule编辑只能通过Enable/Disable/DeleteInsightRules管理。CLF 字段映射VPC 流日志采用 Common Log Format 时务必通过Fields将列索引映射为语义字段名如23: tcp-flag否则Contribution.Keys无法引用。配额与约束前置检查LimitExceededException意味着需要检查账户规则配额RuleDefinition最长 8192 字符、RuleName最长 128 字符编写动态生成逻辑时需预留校验。七、总结aws cloudwatch put-insight-rule是启用 CloudWatch Contributor Insights 能力的关键入口。通过 put-insight-rule.rst 中的 VPC 流日志示例你可以快速掌握规则定义文件的全部核心字段结合 service-2.json 中的参数模型可以精准预判参数约束与错误行为再配合describe-insight-rules、get-insight-rule-report、enable/disable/delete-insight-rules完成规则的全生命周期管理。这套组合拳足以支撑在生产环境中对高基数日志数据开展持续的贡献者维度分析。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考