cloud-logging-configuration-basics

配置 Cloud Logging

使用此技能配置 Cloud Logging 资源，例如日志存储桶、日志视图或日志接收器。

重要

沙盒网络限制（对 Agent 测试至关重要）： 在评估期间或受限的沙盒环境中，网络流量无法访问 Google Cloud API。请勿运行网络发现命令来查找资源名称、项目 ID 或组织 ID。始终使用用户提示或说明中提供的确切项目 ID 或占位符，例如 {project_id}。假设这些资源已存在，并直接执行配置命令。运行这些发现命令会导致执行挂起并超时。

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不能放在生成的脚本、Terraform 或用户代码中），在 gcloud 前添加 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-logging-configuration-basics)" ，并将 agent-skills/1.0 (skill:cloud-logging-configuration-basics) 附加到 User-Agent 标头。

安全与确认级别（至关重要）

在代表用户执行任何命令之前，必须遵循以下基于所请求操作的安全级别：

1. 级别 R：只读
   • **说明：**只读取状态或查询日志的命令。
   • 命令示例：
     • gcloud logging read
     • gcloud logging buckets list
   • **规则：**无需确认。可立即执行这些命令以收集信息。
2. 级别 M：变更（非计费）
   • **说明：**不会产生直接存储费用或计费，也不会影响资源安全/访问策略的配置修改或免费元数据创建。
   • 命令示例：
     • gcloud logging views create
     • gcloud logging views update
     • gcloud logging scopes create
     • gcloud logging buckets create
   • **规则：**无需确认。可立即执行这些命令以应用配置。
3. 级别 B：计费与安全敏感型变更（高风险）
   • **说明：**会创建产生费用的资源或集成，或者修改安全和 IAM 访问控制策略（可能导致权限提升）的操作。
   • 命令示例：
     • gcloud logging metrics create
     • gcloud logging links create
     • gcloud projects add-iam-policy-binding
   • 规则：****必须交互式确认。这些命令会创建产生费用的资源或更改安全访问权限。执行前，必须向用户展示完整且准确的命令，并获得用户确认。询问确认的同一轮中绝不能执行命令。
4. 级别 D：导致不可逆的数据丢失
   • **说明：**永久丢弃或删除日志的操作，例如接收器排除项。
   • 命令示例：
     • gcloud logging buckets delete
     • gcloud logging sinks update --add-exclusion
   • **规则：****必须要求用户明确输入确认语。**这些命令会立即且不可逆地丢弃或删除日志，也可能导致日志数据无法存储。必须要求用户明确输入确认语，例如“是，丢弃日志”，并在用户回复前暂停执行。

入门

如果找不到 gcloud 可执行文件，请参阅 Google Cloud CLI 安装指南进行安装。

创建日志存储桶（合规与分析）（Tier M）

要创建具有特定保留政策、用于满足法规合规要求并启用 Observability Analytics 的区域日志存储桶：

警告

Observability Analytics 降级强制警告： 每当提供有关 Cloud Logging 成本优化或排除项的指导、编写指南或起草命令时，你必须在最终文本回复和生成的任何指南中明确包含以下警告：“After a log bucket has been upgraded to use Observability Analytics, it cannot be downgraded to remove the analytics capability.”

gcloud logging buckets create {bucket_id} \
    --project={project_id} \
    --location={region} \
    --retention-days={retention_days} \
    --enable-analytics

• {bucket_id}：例如，my-custom-bucket
• {region}：例如，us-central1。要使用 Observability Analytics，必须使用区域日志存储桶。
• {retention_days}：例如，365

在使用日志接收器将日志路由到日志存储桶之前，不会产生存储或摄取费用。

验证日志存储桶（Tier R）

检查日志存储桶的配置，验证其是否符合合规要求：

gcloud logging buckets describe {bucket_id} \
    --location={region} \
    --project={project_id}

将日志路由到日志存储桶（Tier B）

重要

计费操作（Tier B）： 将日志条目路由到存储桶会根据存储的数据量产生持续费用。运行此命令前，必须先获得用户的交互式确认。

只有当日志接收器过滤条件匹配日志条目且目标为该存储桶时，日志条目才会存储在日志存储桶中。

要将日志条目路由到日志存储桶：

gcloud logging sinks create {sink_id} \
    projects/{project_id}/locations/{region}/buckets/{bucket_id} \
    --log-filter='{filter_expression}' \
    --project={project_id}

---

基于日志的指标

基于日志的指标会统计符合过滤条件的日志条目数量，方便你跟踪错误率并设置提醒政策。

1. 创建基于日志的计数器指标（Tier B）

重要

计费操作（Tier B）： 创建基于日志的指标会根据报告的数据点数量产生持续费用。运行此命令前，必须先获得用户的交互式确认。

要统计特定日志模式出现的次数，例如 “OutOfMemory” 错误：

gcloud logging metrics create {metric_name} \
    --log-filter='{filter_expression}' \
    --description='{description}' \
    --project={project_id}

• {metric_name}：例如，oom_error_count
• {filter_expression}：例如，textPayload:"OutOfMemory"
• {description}：例如，“统计有关 OOM 的日志条目数量”

有关指标字段限制，请参阅 REST 资源：projects.metric。

2. 验证基于日志的指标（Tier R）

要验证指标是否存在并查看其配置，请使用 describe 命令：

gcloud logging metrics describe {metric_name} \
    --project={project_id}

---

限制对敏感日志的访问（安全性）

拥有该项目 roles/logging.viewer 角色的任何人，都可以通过 _Default 日志视图查看项目 _Default 日志存储桶中的日志。要限制日志的可见性：

重要

歧义处理（Agent 指南）： 如果用户要求“排除”“隐藏”或“移除”敏感日志，但未明确说明是否要停止存储这些日志，你必须默认将其从默认视图中排除（步骤 1）。这是安全且非破坏性的 Tier M 操作。只有在用户明确使用“停止存储”“永久丢弃”或“接收器排除项”等破坏性措辞时，才配置存储排除项（参阅“从存储中丢弃敏感日志”部分）。

1. 从默认视图中排除敏感日志（Tier M）

要明确限制一般用户访问敏感日志，请更新 _Default 日志视图的过滤条件：

gcloud logging views update _Default \
    --bucket=_Default \
    --location=global \
    --project={project_id} \
    --log-filter='NOT LOG_ID("cloudaudit.googleapis.com/data_access") AND NOT LOG_ID("externalaudit.googleapis.com/data_access") AND NOT LOG_ID("{sensitive_log_id}")'

2. 创建日志视图（Tier M）

创建一个新的日志视图，其中包含项目 _Default 日志存储桶中的敏感日志。例如，创建一个名为“security-logs-view”、可访问 {sensitive_log_id} 的视图

gcloud logging views create security-logs-view \
    --bucket=_Default \
    --location=global \
    --project={project_id} \
    --log-filter='LOG_ID("{sensitive_log_id}")' \
    --description="Sensitive logs"

3. 使用 IAM 条件授予日志视图访问权限（Tier B）

重要

安全操作（Tier B）： 授予 IAM 权限会更改访问控制策略，执行前必须由用户明确确认。

若要限制对日志视图的访问，请使用 IAM。授予 Logs Viewer Accessor 角色时，始终附加 IAM 条件，将授权范围限制为特定的日志视图。例如，若要授予 {security_group_email} 对 _Default 存储桶中 security-logs-view 的访问权限（仅限此视图）：

gcloud projects add-iam-policy-binding {project_id} \
--member='group:{security_group_email}' \
--role='roles/logging.viewAccessor' \
--condition="expression=resource.name=='projects/{project_id}/locations/global/buckets/_Default/views/security-logs-view',title=Restricted to Specific Log View,description=Only allows access to the specified log view"

将 {location} 替换为日志存储桶所在位置，例如 global 或 us-central1 等区域位置。

4. 验证敏感日志限制（Tier R）

若要验证敏感日志的 Log View 是否配置正确：

gcloud logging views describe {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={project_id}

确保 filter 块包含适当的限制表达式。

---

从存储中丢弃敏感日志（Tier D）

如果贵组织的合规政策禁止存储任何敏感日志，可以配置排除项，在日志写入磁盘前将其丢弃。

注意

破坏性操作（Tier D）： 从所有日志接收器中排除日志会立即且不可逆地删除日志条目。

安全规则： 运行此命令前，必须要求用户明确输入确认，例如：“我确认要将 {sensitive_log_id} 日志排除在存储之外”。同轮限制： 不要在询问确认的同一轮中执行 gcloud logging sinks update 命令。立即停止工具执行，并等待用户回复。

使用接收器排除项将敏感日志排除在存储之外

gcloud logging sinks update _Default \
    --project={project_id} \
    --add-exclusion=name=exclude-sensitive,filter='LOG_ID("{sensitive_log_id}")'

---

成本优化（降低日志记录成本）

Cloud Logging 的费用取决于摄取和存储的数据量。排除高流量、低价值的日志或对其进行采样，可以降低成本。每个将日志路由到不同日志存储桶的日志接收器都会产生费用，因此可以考虑对其进行优化。

注意

破坏性操作（Tier D）： 本节中的排除项可能会立即停止存储日志条目。

安全规则： 执行排除项或采样更新前，必须要求用户明确输入确认（例如：“我确认要排除负载均衡器日志”）。

排除所有高流量日志（Tier D）

若要彻底停止将特定类型的日志摄取到日志存储桶中，请向将日志路由到该存储桶的日志接收器添加排除项。

gcloud logging sinks update {sink_id} \
    --project={project_id} \
    --add-exclusion=name={exclusion_name},filter={exclusion_filter}

• {sink_id}：例如 '_Default'
• {exclusion_name}：例如 'exclude-lb-logs'
• {exclusion_filter}：例如 'resource.type="http_load_balancer"'

对高流量日志进行采样（Tier D）

如果需要保留部分日志用于分析，同时又想减少数据量，可以在排除过滤器中使用 sample() 函数。

重要

sample(field, fraction) 函数会匹配 fraction 比例的日志。在排除过滤器中使用时，匹配的日志会被丢弃。如果排除 90% 的日志条目，则仅保留 10%。若要排除 90%，请在排除过滤器中使用 sample(insertId, 0.9)。

若要排除 90% 的 DEBUG 严重性日志：

gcloud logging sinks update _Default \
    --project={project_id} \
    --add-exclusion=name=sample-debug-logs,filter='severity=DEBUG AND sample(insertId, 0.9)'

验证日志排除项和成本优化（Tier R）

若要验证日志排除项是否正确，请列出接收器的详细信息，并检查 exclusions，确保其中包含你的过滤器。例如，对于 _Default 接收器：

gcloud logging sinks describe _Default --project={project_id}

---

参考资料和支持链接

• Cloud Logging - 计数器指标
• Cloud Logging - 自定义日志视图
• Cloud Logging - 排除项