querying-aws-cloudwatch

查询 AWS CloudWatch 系统表

概述

与 AWS MCP server 配合使用效果最佳，可实现沙盒执行和审计日志记录。以下所有命令均使用 AWS CLI，可在已配置 AWS 凭证的任何环境中运行。

CloudWatch Logs S3 Tables 集成会将日志数据导出为 AWS 管理的 aws-cloudwatch 表存储桶中的 Apache Iceberg 表。这样即可通过 Amazon Athena 进行 SQL 分析，并将日志数据与非 CloudWatch 数据（S3 元数据、业务表等）关联起来。除 CloudWatch 数据摄取费用外，不收取额外存储费用。

决策树

用户意图	使用此技能？	替代方案
对大量日志数据运行 SQL	是	—
将日志与 S3 元数据或其他表关联	是 — 跨目录联接	—
快速搜索日志／匹配模式	否	CloudWatch Logs Insights（适用于临时查询，速度更快）
实时流式传输／跟踪日志	否	CloudWatch Logs 控制台或 logs filter-log-events
根据日志模式设置警报	否	CloudWatch Metric Filters／Alarms
查询启用集成之前的历史日志	否	CloudWatch Logs（S3 Tables 不会回填数据）

支持的数据源

以下数据源可通过 S3 Tables 集成使用。每个数据源都有一个在 SQL 查询中使用的命名空间模式。并非所有 AWS 提供的数据源都能在所有区域使用；请查看 CloudWatch 控制台的 Data Sources 选项卡，了解当前的可用情况。

数据源	命名空间模式	常见用途
VPC Flow Logs	amazon_vpc__flow	网络流量分析、被拒绝的连接
WAF Logs	aws_waf__logs	被拦截的请求、规则命中分析
CloudFront Access Logs	amazon_cloudfront__access	CDN 流量模式、错误率
Route 53 Resolver Query Logs	amazon_route53resolver__query	DNS 查询分析
Network Firewall Logs	aws_networkfirewall__logs	防火墙规则命中、丢弃的流量
EKS Audit Logs	amazon_eks__audit	Kubernetes API 审计跟踪
Verified Access Logs	amazon_verifiedaccess__logs	零信任访问决策
SES Mail Logs	amazon_ses__mail	电子邮件投递／退信跟踪
VPC Lattice Access Logs	amazon_vpclattice__access	服务间访问模式
Step Functions Logs	aws_stepfunctions__logs	工作流执行调试
Global Accelerator Flow Logs	aws_globalaccelerator__flow	全球网络流量
NLB Access Logs	elastic_load_balancing__nlb_access	负载均衡器请求跟踪
Shield Logs	aws_shield__logs	DDoS 缓解事件
Cognito Logs	amazon_cognito__logs	身份验证／身份操作
ElastiCache Logs	amazon_elasticache__logs	Redis 慢日志、引擎日志
SageMaker Logs	amazon_sagemaker__logs	ML 训练／推理事件
WorkMail Audit Logs	amazon_workmail__audit	电子邮件安全／合规
Bedrock Agent Logs	aws_bedrock_agent_core__logs	AI Agent 调用
Client VPN Logs	aws_client_vpn__connections	VPN 连接跟踪
Entity Resolution Logs	aws_entity_resolution__logs	记录匹配操作
MediaPackage Access Logs	aws_elemental_mediapackage__access	流媒体交付指标
MediaTailor Logs	aws_elemental_mediatailor__logs	广告插入事件
Transfer Family Logs	aws_transfer_family__logs	SFTP／FTPS 文件传输跟踪
Site-to-Site VPN Logs	aws_site_to_site_vpn__logs	VPN 隧道诊断

注意：此表列出了最常查询的 24 个数据源。该集成总共支持 43 个以上 AWS 提供的数据源。使用 aws-cloudwatch 存储桶上的 list-namespaces，即可发现账户中所有可用的数据源。命名空间模式遵循 <service>__<type> 这一约定。

常见任务

1. 检查是否已配置

# Check if the aws-cloudwatch table bucket exists
aws s3tables list-table-buckets --region <REGION> \
  --query "tableBuckets[?name=='aws-cloudwatch']"

• 结果为空 → 尚未启用集成。引导用户完成设置。
• 存储桶存在但没有命名空间 → 已启用集成，但尚无日志数据（仅捕获关联之后发生的事件）。

列出可用表：

aws s3tables list-namespaces --table-bucket-arn arn:aws:s3tables:<REGION>:<ACCOUNT>:bucket/aws-cloudwatch --region <REGION>

aws s3tables list-tables --table-bucket-arn arn:aws:s3tables:<REGION>:<ACCOUNT>:bucket/aws-cloudwatch --namespace <NAMESPACE> --region <REGION>

2. 启用 / 配置

创建集成：

aws observabilityadmin create-s3-table-integration \
  --region <REGION> \
  --encryption '{"SseAlgorithm": "aws:kms", "KmsKeyArn": "<KMS_KEY_ARN>"}' \
  --role-arn <SERVICE_ROLE_ARN>

关联特定数据源（推荐）：

aws logs associate-source-to-s3-table-integration \
  --region <REGION> \
  --integration-arn <INTEGRATION_ARN> \
  --data-source '{"name": "<source-name>", "type": "<source-type>"}'

关联所有数据源（通配符）：

⚠️ 警告：通配符关联会将所有当前和未来的数据源发送到 S3 Tables。为更严格地控制哪些日志数据会进入可查询表，请使用特定关联。

aws logs associate-source-to-s3-table-integration \
  --region <REGION> \
  --integration-arn <INTEGRATION_ARN> \
  --data-source '{"name": "*", "type": "*"}'

有关 IAM 要求（服务角色信任策略、权限策略、条件键），请参阅下文的安全注意事项。

3. 验证查询权限

需要：

• 已在 Glue 中注册 S3 Tables 联合目录（s3tablescatalog）
• 对表具有 Lake Formation SELECT + DESCRIBE 授权（或在支持的区域使用仅 IAM 模式）
• Athena 执行权限

授予访问权限：

aws lakeformation grant-permissions \
  --principal DataLakePrincipalIdentifier=<ROLE_ARN> \
  --resource '{"Table": {"CatalogId": "<ACCOUNT>:s3tablescatalog/aws-cloudwatch", "DatabaseName": "<NAMESPACE>", "Name": "<TABLE>"}}' \
  --permissions DESCRIBE SELECT \
  --region <REGION>

4. 查询

查询语法：

"s3tablescatalog/aws-cloudwatch"."<namespace>"."<table>"

限制：

• 在编写任何 SQL 查询之前，必须始终对目标命名空间运行 get-tables，并在回复中包含该命令——不同数据源的架构各不相同。即使你已知道可能的架构，也绝不能跳过此步骤。对目标命名空间运行一次 get-tables（一次调用会返回所有表、列、类型和说明）：

  aws glue get-tables --catalog-id "<ACCOUNT>:s3tablescatalog/aws-cloudwatch" --database-name "<namespace>" --region <REGION>
  

• 执行查询前，必须确认工作组和输出位置

• 必须告知用户，只有关联之后收到的日志才可用（不回填）

示例 — VPC Flow Logs 中被拒绝的流量：

SELECT srcaddr, dstaddr, dstport, protocol, packets, bytes
FROM "s3tablescatalog/aws-cloudwatch"."amazon_vpc__flow"."<table>"
WHERE action = 'REJECT'
ORDER BY bytes DESC
LIMIT 50;

示例 — WAF 拦截的请求：

SELECT timestamp, action, terminatingRuleId, httpSourceId
FROM "s3tablescatalog/aws-cloudwatch"."aws_waf__logs"."<table>"
WHERE action = 'BLOCK'
ORDER BY timestamp DESC
LIMIT 50;

示例 — 将 VPC Flow Logs 与 S3 对象元数据相关联：

SELECT f.srcaddr, f.dstaddr, f.bytes, j.key, j.record_type
FROM "s3tablescatalog/aws-cloudwatch"."amazon_vpc__flow"."<table>" f
JOIN "s3tablescatalog/aws-s3"."b_<bucket>"."journal" j
  ON f.srcaddr = j.source_ip_address
WHERE j.record_type = 'CREATE'
  AND f.action = 'ACCEPT';

关键行为

• 不回填 — 只有关联之后产生的新日志事件才会发送到 S3 Tables
• 保留期遵循日志组设置 — 日志组的保留期到期后，数据会从表中删除
• 删除日志组会移除其在 S3 表中的数据
• 不额外收取存储费用 — 已包含在 CloudWatch 定价中
• 架构因数据源而异 — 构建复杂查询前，务必对目标命名空间运行 get-tables

故障排除

错误	原因	修复方法
找不到 aws-cloudwatch 存储桶	尚未创建集成	运行 create-s3-table-integration
存储桶存在但没有命名空间	尚未关联数据源，或关联后没有日志流量	关联数据源；生成流量
Athena 中出现 CATALOG_NOT_FOUND	尚未在 Glue 中注册 S3 Tables	启用集成：S3 控制台 > Table buckets > Enable integration
查询时出现 AccessDenied	缺少 Lake Formation 授权或 IAM 权限	请参阅下文的安全注意事项
结果为空	日志仅在关联后开始流入；不回填	确认关联已建立，且日志源正在生成数据
架构不匹配 / 找不到列	AWS 更新了日志类型架构	对该命名空间运行 get-tables 以获取当前列

安全注意事项

服务角色信任策略

服务角色必须允许 logs.amazonaws.com 承担该角色。务必包含 aws:SourceAccount 和 aws:SourceArn 条件键，以防止混淆代理攻击：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "logs.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "<ACCOUNT>"
                },
                "ArnLike": {
                    "aws:SourceArn": ["arn:aws:logs:<REGION>:<ACCOUNT>:log-group:<LOG_GROUP_NAME>"]
                }
            }
        }
    ]
}

服务角色权限策略

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["logs:integrateWithS3Table"],
            "Resource": ["arn:aws:logs:<REGION>:<ACCOUNT>:log-group:<LOG_GROUP_NAME>"],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "<ACCOUNT>"
                }
            }
        }
    ]
}

KMS 密钥策略（用于加密数据）

如果使用客户管理的 KMS 密钥，请授予两个服务主体访问权限：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "EnableSystemTablesKeyUsage",
            "Effect": "Allow",
            "Principal": {"Service": "systemtables.cloudwatch.amazonaws.com"},
            "Action": ["kms:DescribeKey", "kms:GenerateDataKey", "kms:Decrypt"],
            "Resource": "arn:aws:kms:<REGION>:<ACCOUNT>:key/<KEY_ID>",
            "Condition": {"StringEquals": {"aws:SourceAccount": "<ACCOUNT>"}}
        },
        {
            "Sid": "EnableS3TablesMaintenanceKeyUsage",
            "Effect": "Allow",
            "Principal": {"Service": "maintenance.s3tables.amazonaws.com"},
            "Action": ["kms:GenerateDataKey", "kms:Decrypt"],
            "Resource": "arn:aws:kms:<REGION>:<ACCOUNT>:key/<KEY_ID>",
            "Condition": {"StringLike": {"kms:EncryptionContext:aws:s3:arn": "<TABLE_OR_TABLE_BUCKET_ARN>/*"}}
        }
    ]
}

数据敏感性

日志数据可能包含个人身份信息（PII），包括 IP 地址、用户代理、请求参数和身份验证令牌。默认情况下，应将所有导出的日志表视为敏感数据。

访问控制最佳实践

• 使用 Lake Formation 列级安全限制对敏感列（例如 srcaddr、source_ip_address、httpRequest）的访问。向特定表和列授予权限，而不要使用通配符。
• 在 Athena 工作组输出存储桶上配置 SSE-KMS 加密，以保护静态查询结果。
• 优先使用特定的数据源关联，而不是通配符 (*/*)，以限制可导出为可查询表的数据源。

审计跟踪

为 Athena（StartQueryExecution、GetQueryResults）和 Lake Formation（GrantPermissions、RevokePermissions）API 调用启用 CloudTrail 日志记录，以便跟踪谁查询了哪些数据。

其他资源

• CloudWatch Logs S3 Tables 集成
• 受支持的 AWS 托管数据源
• 集成所需的 IAM 权限
• 将 S3 Tables 与分析服务集成
• Lake Formation 权限