cloud-logging-configuration-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring Cloud Logging

配置Cloud Logging

Use this skill to configure Cloud Logging resources such as log buckets, log views, or log sinks.

[!IMPORTANT] Sandbox Network Limitation (CRITICAL for Agent Testing): During evaluation or in restricted sandboxed environments, network traffic to Google Cloud APIs is blocked. Do NOT run network discovery commands to find resource names, project IDs, or organization IDs. Always use the exact project IDs or placeholders provided in the user prompt or instructions for example,
{project_id}
. Assume these resources exist and proceed directly with configuration commands. Running these discovery commands will cause the execution to hang and timeout.

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

[!IMPORTANT] 沙箱网络限制（对Agent测试至关重要）： 在评估或受限沙箱环境中，通往Google Cloud APIs的网络流量会被阻断。请勿运行网络发现命令来查找资源名称、项目ID或组织ID。请始终使用用户提示或指令中提供的准确项目ID或占位符，例如
{project_id}
。假设这些资源已存在，直接执行配置命令。运行这些发现命令会导致执行挂起并超时。

Safety and Confirmation Tiers (CRITICAL)

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

Before executing any commands on behalf of the user, you MUST adhere to the following safety tiers based on the action requested:

Tier R: Read-Only
- Description: Commands that only read state or query logs.
- Example commands:
  - ```
  gcloud logging read
```
- ```
gcloud logging buckets list
```
- Rule: No confirmation needed. You may execute these commands immediately to gather information.
Tier M: Mutation (Non-Billing)
- Description: Configuration modifications or free metadata creations that do not incur direct storage or billing costs and do not affect resource security/access policies.
- Example commands:
  - ```
  gcloud logging views create
```
- ```
gcloud logging views update
```
  - ```
  gcloud logging scopes create
```
- ```
gcloud logging buckets create
```
- Rule: No confirmation needed. You may execute these commands immediately to apply configurations.
Tier B: Billing and Security-Sensitive Mutations (High-Risk)
- Description: Operations that create billing-inducing resources or integrations, or modify security and IAM access control policies (presenting a risk of privilege escalation).
- Example commands:
  - ```
  gcloud logging metrics create
```
- ```
gcloud logging links create
```
  - ```
  gcloud projects add-iam-policy-binding
```
- Rule: Interactive confirmation required. These commands create resources that incur billing costs or alter security access. You MUST present the exact, literal command and receive user confirmation before executing. NEVER execute in the same turn as asking.
Tier D: Causes irreversible data loss
- Description: Actions that permanently discard or delete logs, for example sink exclusions.
- Example commands:
  - ```
  gcloud logging buckets delete
```
- ```
gcloud logging sinks update --add-exclusion
```
- Rule: Explicit typed confirmation required. These commands discard or delete logs immediately and irreversibly, or they may result in log data not being stored. You MUST ask for explicit typed confirmation, for example, "Yes, discard logs", and halt execution until the user replies.

在代表用户执行任何命令之前，您必须根据请求的操作遵循以下安全层级：

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

Getting Started

入门指南

If the

gcloud

executable is missing, refer to the Google Cloud CLI Installation Guide to install it.

如果缺少

gcloud

可执行文件，请参考Google Cloud CLI安装指南进行安装。

Creating Log Buckets (Compliance and Analytics) (Tier M)

创建日志桶（合规与分析）（层级M）

To create a regional log bucket with a specific retention policy for regulatory compliance, and with Observability Analytics enabled:

[!WARNING] Mandatory Observability Analytics Downgrade Warning: Whenever providing guidance, writing a guide, or drafting commands on Cloud Logging cost optimization or exclusions, you must explicitly include the following warning in your final text response and any generated guides: "After a log bucket has been upgraded to use Observability Analytics, it cannot be downgraded to remove the analytics capability."

bash

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

```
{bucket_id}
```
: for example,
```
my-custom-bucket
```
```
{region}
```
: for example,
```
us-central1
```
. You must use a regional log bucket to also use Observability Analytics.
```
{retention_days}
```
: for example,
```
365
```

A log bucket incurs no storage or ingestion charges until logs are routed to it with a log sink.

创建具有特定保留策略以满足法规合规要求，并启用Observability Analytics的区域日志桶：

[!WARNING] 强制Observability Analytics降级警告：每当提供指导、编写指南或起草关于Cloud Logging成本优化或排除规则的命令时，您必须在最终文本回复和任何生成的指南中明确包含以下警告：“日志桶升级为使用Observability Analytics后，无法降级以移除分析功能。”

bash

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
```

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

Verify the Log Bucket (Tier R)

验证日志桶（层级R）

Check the log bucket's configuration to verify its compliance:

bash

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

检查日志桶的配置以验证其合规性：

bash

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

Route logs to the Log Bucket (Tier B)

将日志路由到日志桶（层级B）

[!IMPORTANT] Billing Action (Tier B): Routing log entries to a bucket incurs ongoing charges based on the volume of data stored. You MUST get interactive user confirmation before running this command.

Log entries are stored in the log bucket only if a log sink filter matches the entries and targets that bucket.

To route log entries to the log bucket:

bash

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

[!IMPORTANT] **计费操作（层级B）：**将日志条目路由到桶会根据存储的数据量产生持续费用。您必须在运行此命令前获得用户交互式确认。

只有当日志接收器过滤器匹配条目并指向该桶时，日志条目才会存储在日志桶中。

将日志条目路由到日志桶：

bash

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

Logs-Based Metrics

基于日志的指标

Logs-based metrics count the number of log entries that match a filter, allowing you to track error rates and set up alerting policies.

基于日志的指标会统计匹配过滤器的日志条目数量，使您能够跟踪错误率并设置警报策略。

1. Create a logs-based counter metric (Tier B)

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

[!IMPORTANT] Billing Action (Tier B): Creating logs-based metrics incurs ongoing charges based on the volume of data points reported. You MUST get interactive user confirmation before running this command.

To count the occurrences of a specific log pattern, for example, "OutOfMemory" errors:

bash

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

```
{metric_name}
```
: for example,
```
oom_error_count
```

{filter_expression}

: for example,

textPayload:"OutOfMemory"

```
{description}
```
: for example, "Count of log entries about OOMs"

Refer to REST Resource: projects.metric for restrictions on the metric fields.

[!IMPORTANT] **计费操作（层级B）：**创建基于日志的指标会根据报告的数据点数量产生持续费用。您必须在运行此命令前获得用户交互式确认。

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

bash

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. Verify the logs-based metric (Tier R)

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

To verify that the metric exists and inspect its configuration, use the

describe

command:

bash

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

要验证指标是否存在并检查其配置，请使用

describe

命令：

bash

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

Restricting Access to Sensitive Logs (Security)

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

Anyone with

roles/logging.viewer

on that project can see logs in a project's

_Default

log bucket via

_Default

log view. To restrict visibility of the logs:

[!IMPORTANT] Ambiguity Handling (Guidance for Agents): If the user asks to "exclude", "hide", or "remove" sensitive logs without explicitly specifying whether they want to stop storing them, you MUST default to excluding them from the default view (Step 1). This is a safe, non-destructive Tier M action. Only configure a storage exclusion (under the "Discarding Sensitive Logs from Storage" section) if the user explicitly uses destructive terms like "stop storing", "permanently discard", or "sink exclusion".

拥有项目

roles/logging.viewer

权限的任何人都可以通过

_Default

日志视图查看项目

_Default

日志桶中的日志。要限制日志的可见性：

[!IMPORTANT] 歧义处理（Agent指南）：如果用户要求“排除”、“隐藏”或“移除”敏感日志，但未明确指定是否要停止存储它们，您必须默认选择从默认视图中排除（步骤1）。这是一种安全、非破坏性的层级M操作。只有当用户明确使用诸如“停止存储”、“永久丢弃”或“接收器排除规则”等破坏性术语时，才配置存储排除规则（在“从存储中丢弃敏感日志”部分下）。

1. Exclude sensitive logs from default view (Tier M)

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

To explicitly exclude sensitive logs from general access, update the filter for the

_Default

log view:

bash

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}")'

要明确排除敏感日志以防止一般访问，请更新

_Default

日志视图的过滤器：

bash

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. Create a log view (Tier M)

2. 创建日志视图（层级M）

Create a new log view that includes the sensitive logs in the project's

_Default

log bucket. For example, a "security-logs-view" with access to the

{sensitive_log_id}

bash

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

创建一个新的日志视图，包含项目

_Default

日志桶中的敏感日志。例如，一个名为“security-logs-view”的视图，可访问

{sensitive_log_id}

bash

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

3. Grant access to log view using IAM conditions (Tier B)

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

[!IMPORTANT] Security Action (Tier B): Granting IAM permissions changes access control policy and must be explicitly confirmed by the user before execution.

To restrict access to log view use IAM. When granting the Logs Viewer Accessor role, always attach an IAM condition that restricts the grant to a specific log view. For example, to grant

{security_group_email}

access ONLY to the

security-logs-view

in the

_Default

bucket:

bash

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"

Replace

{location}

with the location of the log bucket, for example

global

or a regional location like

us-central1

[!IMPORTANT] **安全操作（层级B）：**授予IAM权限会更改访问控制策略，必须在执行前获得用户明确确认。

要使用IAM限制日志视图的访问权限。授予Logs Viewer Accessor角色时，请始终附加一个IAM条件，将权限限制为特定日志视图。例如，授予

{security_group_email}

仅访问

_Default

桶中的

security-logs-view

的权限：

bash

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. Verify Sensitive Log Restrictions (Tier R)

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

To verify that your Log View for sensitive logs is configured correctly:

bash

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

Ensure that the

filter

block contains the appropriate restriction expression.

要验证您的敏感日志视图配置是否正确：

bash

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

确保

filter

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

Discarding Sensitive Logs from Storage (Tier D)

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

If your organization's compliance policies prohibit storing sensitive logs at all, you can configure an exclusion to discard them before they are written to disk.

[!CAUTION] Destructive Action (Tier D): Excluding logs from all log sinks deletes the log entries immediately and irreversibly.
Safety Rule: You MUST ask the user for explicit typed confirmation, for example, "I confirm I want to exclude
{sensitive_log_id}
logs from storage", before running this command. Same-Turn Restriction: Do NOT execute the
gcloud logging sinks update
command in the same turn as asking for confirmation. Stop tool execution immediately and wait for the user to reply.

Exclude sensitive logs from storage using sink exclusions

bash

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

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

[!CAUTION] **破坏性操作（层级D）：**从所有日志接收器中排除日志会立即且不可逆地删除日志条目。
**安全规则：**您必须请求用户明确的键入确认，例如“我确认要从存储中排除
{sensitive_log_id}
日志”，然后再运行此命令。**同轮次限制：**请勿在请求确认的同一轮次执行
gcloud logging sinks update
命令。立即停止工具执行并等待用户回复。

使用接收器排除规则从存储中排除敏感日志

bash

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

Cost Optimization (Reducing Logging Costs)

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

Cloud Logging costs are based on the volume of data ingested and stored. You can reduce costs by excluding high-volume, low-value logs or by sampling them. Each log sink that routes logs to a distinct log bucket contributes to cost and is a candidate for optimization.

[!CAUTION] Destructive Actions (Tier D): Exclusions in this section may immediately halt storage of log entries.

Safety Rule: You MUST ask for explicit typed confirmation (for example, "I confirm I want to exclude load balancer logs") before executing exclusions or sampling updates.

Cloud Logging成本基于摄入和存储的数据量。您可以通过排除高容量、低价值日志或对其进行采样来降低成本。每个将日志路由到不同日志桶的日志接收器都会产生成本，是优化的候选对象。

[!CAUTION] **破坏性操作（层级D）：**本节中的排除规则可能会立即停止日志条目的存储。

**安全规则：**在执行排除规则或采样更新之前，您必须请求明确的键入确认（例如“我确认要排除负载均衡器日志”）。

Exclude all high-volume logs (Tier D)

排除所有高容量日志（层级D）

To completely stop ingesting a specific type of log into a log bucket, add an exclusion to the log sinks that route logs into that bucket.

bash

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

```
{sink_id}
```
: for example '_Default'
```
{exclusion_name}
```
: for example 'exclude-lb-logs'
```
{exclusion_filter}
```
: for example 'resource.type="http_load_balancer"'

要完全停止将特定类型的日志摄入日志桶，请向将日志路由到该桶的日志接收器添加排除规则。

bash

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"'

Sample high-volume logs (Tier D)

对高容量日志进行采样（层级D）

If you need some logs for analysis but want to reduce volume, use the

sample()

function in the exclusion filter.

[!IMPORTANT] The
sample(field, fraction)
function matches a
fraction
of logs. When used in an exclusion filter, the matched logs are discarded. If you exclude 90% of log entries, then only 10% are retained. To exclude 90%, use
sample(insertId, 0.9)
in the exclusion filter.

To exclude 90% of

DEBUG

severity logs:

bash

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

如果您需要一些日志用于分析但想减少数据量，请在排除过滤器中使用

sample()

函数。

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

排除90%的

DEBUG

级日志：

bash

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

Verify Log Exclusions and Cost Optimization (Tier R)

验证日志排除规则和成本优化（层级R）

To verify that log exclusions are correct, list the details of the sink and check the

exclusions

to ensure your filter is present. For example, for the

_Default

sink:

bash

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

要验证日志排除规则是否正确，请列出接收器的详细信息并检查

exclusions

以确保您的过滤器已存在。例如，对于

_Default

接收器：

bash

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

cloud-logging-configuration-basics

Original

Translation

Configuring Cloud Logging

配置Cloud Logging

Safety and Confirmation Tiers (CRITICAL)

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

Getting Started

入门指南

Creating Log Buckets (Compliance and Analytics) (Tier M)

创建日志桶（合规与分析）（层级M）

Verify the Log Bucket (Tier R)

验证日志桶（层级R）

Route logs to the Log Bucket (Tier B)

将日志路由到日志桶（层级B）

Logs-Based Metrics

基于日志的指标

1. Create a logs-based counter metric (Tier B)

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

2. Verify the logs-based metric (Tier R)

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

Restricting Access to Sensitive Logs (Security)

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

1. Exclude sensitive logs from default view (Tier M)

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

2. Create a log view (Tier M)

2. 创建日志视图（层级M）

3. Grant access to log view using IAM conditions (Tier B)

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

4. Verify Sensitive Log Restrictions (Tier R)

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

Discarding Sensitive Logs from Storage (Tier D)

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

Cost Optimization (Reducing Logging Costs)

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

Exclude all high-volume logs (Tier D)

排除所有高容量日志（层级D）

Sample high-volume logs (Tier D)

对高容量日志进行采样（层级D）

Verify Log Exclusions and Cost Optimization (Tier R)

验证日志排除规则和成本优化（层级R）

References and Supporting Links

参考资料与支持链接