configuring-log-export

配置日志导出

配置 CockroachDB Cloud 集群的日志和指标导出，将集群日志、审计日志和性能指标发送到外部监控服务。支持 AWS CloudWatch、GCP Cloud Logging，以及 Datadog 等第三方集成。

适用场景

• 设置日志导出到 AWS CloudWatch 或 GCP Cloud Logging
• 配置指标导出到 CloudWatch 或 Datadog
• 验证 SQL 审计日志是否已导出到外部接收端
• 排查日志导出错误或日志缺失问题
• 估算 CockroachDB 日志量产生的 CloudWatch 或日志服务费用
• 通过 Terraform 配置日志导出

前提条件

• CockroachDB Cloud Advanced 计划 — Basic 或 Standard 计划不支持日志导出
• ccloud CLI 已通过 Cluster Admin 角色进行身份验证
• 云服务提供商配置：
  • AWS： 已创建 CloudWatch Logs 日志组，并配置了允许 CockroachDB Cloud 跨账户访问的 IAM 角色
  • GCP： 已启用 Cloud Logging API，并配置了具有 Logs Writer 角色的服务账号
• 集群 ID： 可通过 ccloud cluster list 获取

验证访问权限：

ccloud auth whoami
ccloud cluster info <cluster-name> -o json
# Look for "plan": "ADVANCED"

配置决策

继续操作前，确定哪些导出目标适用于用户的环境。询问哪些选项适用，然后仅按照下方相应章节操作。

决策 1 — 日志导出目标：

• AWS CloudWatch： 当集群运行在 AWS 上，且日志需要发送到 CloudWatch Logs 时使用。需要设置 IAM 跨账户角色。
• GCP Cloud Logging： 当集群运行在 GCP 上时使用。需要配置具有 Logs Writer 角色的服务账号。

决策 2 — 指标导出目标：

• CloudWatch： 当指标需要发送到 AWS CloudWatch 时使用。需要具有 cloudwatch:PutMetricData 权限的 IAM 角色。
• Datadog： 当指标需要发送到 Datadog 时使用。需要 Datadog API 密钥和站点。
• 跳过： 当前不需要导出指标。

步骤

1. 检查当前日志导出配置

# Check if log export is currently configured
ccloud cluster info <cluster-name> -o json
# Look for "log_export_config" in the output

2. 设置日志导出到 AWS CloudWatch

仅当用户在决策 1 中选择了 AWS CloudWatch 时，才执行本节。如果使用 GCP Cloud Logging，请跳至步骤 3。

2.1 创建 CloudWatch 日志组

# Create a log group in AWS (if it doesn't exist)
aws logs create-log-group \
  --log-group-name cockroachdb-<cluster-name> \
  --region <aws-region>

# Set retention policy (recommended)
aws logs put-retention-policy \
  --log-group-name cockroachdb-<cluster-name> \
  --retention-in-days 90 \
  --region <aws-region>

2.2 为 CockroachDB Cloud 创建 IAM 角色

完整的 IAM 角色策略请参阅云服务提供商配置参考。

IAM 角色必须：

• 信任 CockroachDB Cloud AWS 账户，将其设为允许的主体
• 授予 logs:CreateLogStream、logs:PutLogEvents、logs:DescribeLogGroups、logs:DescribeLogStreams 权限
• 将权限范围限定为指定的日志组

2.3 启用日志导出

# Enable log export to CloudWatch
ccloud cluster log-export create <cluster-id> \
  --log-group-name cockroachdb-<cluster-name> \
  --auth-principal <iam-role-arn> \
  --type AWS_CLOUDWATCH \
  --region <aws-region>

3. 设置日志导出到 GCP Cloud Logging

仅当用户在决策 1 中选择了 GCP Cloud Logging 时，才执行本节。如果使用 AWS CloudWatch，请跳过。

3.1 启用 Cloud Logging API

gcloud services enable logging.googleapis.com

3.2 授予 CockroachDB Cloud 服务账号访问权限

# Get the CockroachDB Cloud service account from ccloud cluster info
# Grant Logs Writer role
gcloud projects add-iam-policy-binding <gcp-project-id> \
  --member="serviceAccount:<cockroachdb-service-account>" \
  --role="roles/logging.logWriter"

3.3 启用日志导出

ccloud cluster log-export create <cluster-id> \
  --auth-principal <gcp-project-id> \
  --type GCP_CLOUD_LOGGING

4. 配置指标导出

如果用户在决策 2 中选择了 跳过，请跳过本节。根据所选的指标导出目标，仅执行相关的小节（4.1 或 4.2）。

指标导出会将 CockroachDB 性能指标发送到 CloudWatch 或 Datadog。

4.1 将指标导出到 CloudWatch

ccloud cluster metric-export create cloudwatch <cluster-id> \
  --role-arn <iam-role-arn> \
  --target-region <aws-region>

指标导出的 IAM 角色需要 cloudwatch:PutMetricData 权限。

4.2 将指标导出到 Datadog

ccloud cluster metric-export create datadog <cluster-id> \
  --api-key <datadog-api-key> \
  --site <datadog-site>

Datadog 站点值： datadoghq.com（美国）、datadoghq.eu（欧盟）、us3.datadoghq.com（US3）、us5.datadoghq.com（US5）

5. 验证日志和指标导出

# Check log export status
ccloud cluster log-export list <cluster-id> -o json
# Status should be ENABLED

# Check metric export status
ccloud cluster metric-export list <cluster-id> -o json

在 CloudWatch 中验证日志是否送达：

# Check for recent log streams
aws logs describe-log-streams \
  --log-group-name cockroachdb-<cluster-name> \
  --order-by LastEventTime \
  --descending \
  --limit 5 \
  --region <aws-region>

# Tail recent log events
aws logs tail cockroachdb-<cluster-name> \
  --since 1h \
  --region <aws-region>

验证审计日志是否正在导出：

如果集群已启用 SQL 审计日志记录，审计日志就会包含在日志导出中。确认方法如下：

-- Check audit logging is enabled
SHOW CLUSTER SETTING sql.log.admin_audit.enabled;
SHOW CLUSTER SETTING sql.log.user_audit;

如果已启用审计日志记录，但 CloudWatch 中没有显示审计事件，请检查：

1. 日志导出状态为 ENABLED
2. IAM 角色具有正确的权限
3. 日志组名称与配置的导出目标一致
4. 首次送达日志需要等待 5-10 分钟

6. 通过 Terraform 配置日志导出

resource "cockroach_log_export_config" "main" {
  id         = cockroach_cluster.main.id
  auth_principal = "<iam-role-arn>"
  log_name       = "cockroachdb-${cockroach_cluster.main.name}"
  type           = "AWS_CLOUDWATCH"
  region         = "<aws-region>"
}

resource "cockroach_metric_export_cloudwatch_config" "main" {
  id         = cockroach_cluster.main.id
  role_arn       = "<iam-role-arn>"
  target_region  = "<aws-region>"
}

**已知的 Terraform 问题：**在同一次 terraform apply 中创建启用了日志导出和 CMEK 的集群可能会导致竞态条件。请先应用集群配置，然后在后续的应用操作中添加日志导出和 CMEK 配置。

安全注意事项

影响类型	严重程度	建议
启用日志导出	低	不影响集群运行
禁用日志导出	低	停止日志送达，但不影响集群
IAM 配置错误	中	日志导出会静默失败；请监控是否存在送达中断
成本影响	中	高流量集群可能产生大量 CloudWatch/日志记录成本
Terraform 竞态条件	中	在应用日志/CMEK 配置前，先应用集群创建配置

成本规划：

• 根据查询量和审计设置，CockroachDB Cloud 每个节点每天可能生成 1-10 GB 的日志
• CloudWatch Logs 定价：摄取约 $0.50/GB + 存储 $0.03/GB/月（因区域而异）
• 启用日志保留策略以控制存储成本
• 审计日志记录会显著增加日志量，请据此做好规划

请勿：

• 在日志导出启用期间删除 CloudWatch 日志组（这会导致送达错误）
• 未先禁用日志导出就撤销 IAM 权限
• 未考虑日志量增加的影响就启用集群范围的 SQL 审计日志记录

回滚

# Disable log export
ccloud cluster log-export delete <cluster-id>

# Disable metric export
ccloud cluster metric-export delete cloudwatch <cluster-id>
ccloud cluster metric-export delete datadog <cluster-id>

随时可以使用相同或不同的配置重新启用日志导出。历史日志不会重新发送——重新启用后只会导出新日志。

参考资料

技能参考：

• 云提供商 IAM 设置

相关技能：

• 配置审计日志记录 — 启用 SQL 审计日志记录（必须启用，审计日志才会显示在导出内容中）
• 审计云集群安全性 — 执行全面的安全态势审计

CockroachDB 官方文档：

• 从 CockroachDB Cloud 集群导出日志
• 从 CockroachDB Cloud 集群导出指标
• Cloud API — 日志导出