cloud-logging-cross-project-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring Cross-Project Logging

跨项目日志配置

This skill describes how to use

gcloud

commands to configure Cloud Logging so that you store log data in a central location, regardless of the point of origin. The skill also describes how to query log data when that data is stored in multiple projects.

[!IMPORTANT] Sandbox Network Limitation (CRITICAL for Agent Testing): During evaluation or in restricted sandboxed environments, network traffic to GCP 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}
,
{source_project_id}
,
{central_project_id}
. Assume these resources exist and proceed directly with configuration commands. Running these discovery commands will cause the execution to hang and timeout.

本技能介绍如何使用

gcloud

命令配置Cloud Logging，将日志数据存储在中央位置，无论其来源如何。同时还会介绍当日志数据存储在多个项目中时，如何查询这些数据。

[!IMPORTANT] 沙箱网络限制（Agent测试至关重要）： 在评估或受限沙箱环境中，通往GCP API的网络流量会被阻断。请勿运行网络发现命令来查找资源名称、项目ID或组织ID。请始终使用用户提示或说明中提供的准确项目ID或占位符，例如
{project_id}
、
{source_project_id}
、
{central_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
```
- **规则：**需要明确的输入确认。这些命令会立即且不可逆地丢弃或删除日志，或可能导致日志数据无法存储。您必须要求明确的输入确认，例如“是的，丢弃日志”，并在用户回复前停止执行。

Decision Matrix: Centralized Storage vs. Distributed Storage with Read-Time Aggregation

决策矩阵：集中式存储 vs 带实时聚合的分布式存储

Use this decision matrix to evaluate and choose between Centralized Storage and Read-Time Aggregation. With centralized storage, log data is routed to one log bucket, regardless of where the data originates. You write queries against the centralized log bucket. With read-time aggregation, log data is stored by the resource where it originates. However, a single query aggregates the data by querying all resources.

After you have determined the optimal architecture for handling cross-project logs, follow the corresponding configuration steps detailed below.

Criterion	Centralized Storage	Read-Time Aggregation
GCP Project Scale	Scales to thousands of	Best for < 375 projects.
: : projects. : :
Log Storage	Consolidated in a single	Resides in originating
: : log bucket. : resources. :
SQL Analytics	Easy; unified querying	Hard; requires querying
: : via Observability : multiple log buckets. :
: : Analytics. : :
Access Control	Scoped access via log	Requires IAM access to
: : views on the centralized : all views on resources :
: : log bucket. : that store log data. :
Configuration	Options vary based on	Will not interfere with
: Complexity : Project, Folder, : bucket-based log-based :
: : Organization structure. : metrics. :
Cost	Potential for duplicate	Cost-effective; no data
: : storage of log buckets : replication. :
: : if exclusions aren't : :
: : set. : :

使用此决策矩阵评估并选择集中式存储和实时聚合。在集中式存储中，日志数据会被路由到一个日志存储桶，无论其来源何处。您针对中央日志存储桶编写查询。在实时聚合中，日志数据存储在其来源的资源中。但单个查询可以通过查询所有资源来聚合数据。

确定处理跨项目日志的最佳架构后，请遵循以下详细的相应配置步骤。

评估标准	集中式存储	实时聚合
GCP项目规模	可扩展至数千个项目。	最适合少于375个项目的场景。
日志存储	整合到单个日志存储桶中。	存储在来源资源中。
SQL分析	简单；通过Observability Analytics实现统一查询	困难；需要查询多个日志存储桶。
访问控制	通过中央日志存储桶上的日志视图实现范围化访问	需要对存储日志数据的所有资源视图拥有IAM访问权限。
配置复杂度	选项因项目、文件夹、组织结构而异。	不会干扰基于存储桶的日志指标。
成本	如果未设置排除规则，可能会导致日志存储桶重复存储。	成本效益高；无数据复制。

Architecture

架构

Centralized Storage (Log Routing)

集中式存储（日志路由）

mermaid

graph LR
    subgraph "Source Project(s)"
        Log[Resource Logs] --> Sink["Sink: route-to-central-project"]
    end

    subgraph "Central Project"
        Sink --> Bucket["Bucket: central-logs-bucket (us-central1)"]
    end

mermaid

graph LR
    subgraph "Source Project(s)"
        Log[Resource Logs] --> Sink["Sink: route-to-central-project"]
    end

    subgraph "Central Project"
        Sink --> Bucket["Bucket: central-logs-bucket (us-central1)"]
    end

Read-Time Aggregation (Log Scopes)

实时聚合（日志范围）

mermaid

graph LR
    subgraph "Source Project 1"
        Log1[Resource Logs] --> Bucket1["Bucket: _Default"]
    end

    subgraph "Source Project 2"
        Log2[Resource Logs] --> Bucket2["Bucket: _Default"]
    end

    subgraph "Scoping Project (No Log Storage)"
        Scope["Log scope: central-query-scope"]
        Scope -.-> View1["_AllLogs View on Bucket1"]
        Scope -.-> View2["_AllLogs View on Bucket2"]
    end

mermaid

graph LR
    subgraph "Source Project 1"
        Log1[Resource Logs] --> Bucket1["Bucket: _Default"]
    end

    subgraph "Source Project 2"
        Log2[Resource Logs] --> Bucket2["Bucket: _Default"]
    end

    subgraph "Scoping Project (No Log Storage)"
        Scope["Log scope: central-query-scope"]
        Scope -.-> View1["_AllLogs View on Bucket1"]
        Scope -.-> View2["_AllLogs View on Bucket2"]
    end

Setup Steps: Centralized Storage (Log Routing)

设置步骤：集中式存储（日志路由）

Use these steps to route logs from one or more source projects to a central log bucket in a project. Create or select the Google Cloud project that you will use for storing your log data. This is the central project.

使用以下步骤将一个或多个源项目的日志路由到某个项目中的中央日志存储桶。创建或选择用于存储日志数据的Google Cloud项目，即中央项目。

1. Create log bucket in central project (Tier M)

1. 在中央项目中创建日志存储桶（M级）

Create a custom log bucket with Log Analytics enabled.

[Tip] Use regional log buckets, for example, set the location to
us-central1
. Don't use the
global
location. This approach ensures compatibility with Observability Analytics and SQL querying.

bash

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

创建启用了日志分析的自定义日志存储桶。

[提示] 使用区域日志存储桶，例如将位置设置为
us-central1
。请勿使用
global
位置。此方法确保与Observability Analytics和SQL查询兼容。

bash

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

2. Create log sink in central project (Tier M)

2. 在中央项目中创建日志接收器（M级）

Create a project-level sink in the central project pointing to the central log bucket. This sink will route logs that land in the central project's log router into the central log bucket.

bash

gcloud logging sinks create {sink_name} \
    logging.googleapis.com/projects/{central_project_id}/locations/{region}/buckets/{bucket_id} \
    --project={central_project_id}

在中央项目中创建一个项目级接收器，指向中央日志存储桶。此接收器会将进入中央项目日志路由器的日志路由到中央日志存储桶中。

bash

gcloud logging sinks create {sink_name} \
    logging.googleapis.com/projects/{central_project_id}/locations/{region}/buckets/{bucket_id} \
    --project={central_project_id}

3. Create log sink in source resource (Tier M)

3. 在源资源中创建日志接收器（M级）

To route logs to the central project, you must create a log sink in each source organization, folder, or project. While you can configure a sink to route only a subset of logs using the

--log-filter

argument, recommended practice is to route all non-audit logs, and then restrict access or partition logs at the destination using custom Log Views on the centralized log bucket.

For an organization-level log sink

bash

gcloud logging sinks create {sink_name} \
    logging.googleapis.com/projects/{central_project_id} \
    --organization={source_organization_id} \
    --include-children \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/access_transparency")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/access_transparency")'

For project-level log sinks

bash

gcloud logging sinks create {sink_name} \
    logging.googleapis.com/projects/{central_project_id} \
    --project={source_project_id} \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/access_transparency")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/access_transparency")'

要将日志路由到中央项目，您必须在每个源组织、文件夹或项目中创建一个日志接收器。虽然您可以使用

--log-filter

参数将接收器配置为仅路由日志的子集，但建议做法是路由所有非审计日志，然后在目标端使用中央日志存储桶上的自定义日志视图来限制访问或划分日志。

针对组织级日志接收器

bash

gcloud logging sinks create {sink_name} \
    logging.googleapis.com/projects/{central_project_id} \
    --organization={source_organization_id} \
    --include-children \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/access_transparency")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/access_transparency")'

针对项目级日志接收器

bash

gcloud logging sinks create {sink_name} \
    logging.googleapis.com/projects/{central_project_id} \
    --project={source_project_id} \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/access_transparency")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/access_transparency")'

4. Grant IAM permissions to sink writers (Tier B)

4. 向接收器写入者授予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 allow the source sinks to route logs to the central project's router, and to allow the central sink to write logs to the central bucket:

Grant Logs Writer permission to the source sink: Retrieve the

writerIdentity

of the source log sink and grant it

roles/logging.logWriter

on the central project.

bash

# Get the writer identity of the source sink
gcloud logging sinks describe {sink_name} \
    --project={source_project_id} \
    --format="value(writerIdentity)"

The output is the

{source_writer_identity}

value (for example

serviceAccount:...

) for the following command:

bash

# Grant Logs Writer permissions on the central project
gcloud projects add-iam-policy-binding {central_project_id} \
    --member={source_writer_identity} \
    --role=roles/logging.logWriter

Grant Bucket Writer permission to the central sink: Retrieve the

writerIdentity

of the central log sink and grant it

roles/logging.bucketWriter

on the central project.

bash

# Get the writer identity of the central sink
gcloud logging sinks describe {central_sink_name} \
    --project={central_project_id} \
    --format="value(writerIdentity)"

The output is the

{central_writer_identity}

value for the following command:

bash

# Grant Bucket Writer permissions on the central project
gcloud projects add-iam-policy-binding {central_project_id} \
    --member={central_writer_identity} \
    --role=roles/logging.bucketWriter

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

要允许源接收器将日志路由到中央项目的路由器，并允许中央接收器将日志写入中央存储桶：

**向源接收器授予日志写入者权限：**获取源日志接收器的

writerIdentity

，并在中央项目上为其授予

roles/logging.logWriter

角色。

bash

# 获取源接收器的写入者身份
gcloud logging sinks describe {sink_name} \
    --project={source_project_id} \
    --format="value(writerIdentity)"

输出结果是以下命令中的

{source_writer_identity}

值（例如

serviceAccount:...

）：

bash

# 在中央项目上授予日志写入者权限
gcloud projects add-iam-policy-binding {central_project_id} \
    --member={source_writer_identity} \
    --role=roles/logging.logWriter

**向中央接收器授予存储桶写入者权限：**获取中央日志接收器的

writerIdentity

，并在中央项目上为其授予

roles/logging.bucketWriter

角色。

bash

# 获取中央接收器的写入者身份
gcloud logging sinks describe {central_sink_name} \
    --project={central_project_id} \
    --format="value(writerIdentity)"

输出结果是以下命令中的

{central_writer_identity}

值：

bash

# 在中央项目上授予存储桶写入者权限
gcloud projects add-iam-policy-binding {central_project_id} \
    --member={central_writer_identity} \
    --role=roles/logging.bucketWriter

5. Create custom Log Views on the central bucket (Tier M)

5. 在中央存储桶上创建自定义日志视图（M级）

To partition logs or restrict access by log ID or project (since all logs were routed to the same central bucket), create custom Log Views on the central bucket.

Filter by log ID:

bash

gcloud logging views create {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={central_project_id} \
    --log-filter='LOG_ID("{log_id}")'

Filter by source project:

bash

gcloud logging views create {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={central_project_id} \
    --log-filter='project_id="{source_project_id}"'

要按日志ID或项目划分日志或限制访问（因为所有日志都被路由到同一个中央存储桶），请在中央存储桶上创建自定义日志视图。

按日志ID过滤：

bash

gcloud logging views create {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={central_project_id} \
    --log-filter='LOG_ID("{log_id}")'

按源项目过滤：

bash

gcloud logging views create {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={central_project_id} \
    --log-filter='project_id="{source_project_id}"'

Verify Centralized Log Routing (Tier R)

验证集中式日志路由（R级）

To verify that logs are being routed from the source projects to the central regional log bucket:

Write a test log in the source project:

bash

gcloud logging write {test_log_id} "Test log entry for verification" \
    --severity=WARNING \
    --project={source_project_id}

Read the test log from the central log bucket: For regional log buckets, you must specify the
```
--view
```
flag. Because the default view
```
_Default
```
only contains logs matching the default filter, you should query the _AllLogs
view or your custom log view on the central bucket:
bash
```
gcloud logging read 'logName:"projects/{source_project_id}/logs/{test_log_id}"' \
    --bucket={bucket_id} \
    --location={region} \
    --view=_AllLogs \
    --project={central_project_id}
```

要验证日志是否从源项目路由到中央区域日志存储桶：

在源项目中写入测试日志：

bash

gcloud logging write {test_log_id} "Test log entry for verification" \
    --severity=WARNING \
    --project={source_project_id}

从中央日志存储桶读取测试日志：对于区域日志存储桶，您必须指定
```
--view
```
标志。因为默认视图
```
_Default
```
仅包含匹配默认过滤器的日志，您应该查询中央存储桶上的**
```
_AllLogs
```
**视图或您的自定义日志视图：
bash
```
gcloud logging read 'logName:"projects/{source_project_id}/logs/{test_log_id}"' \
    --bucket={bucket_id} \
    --location={region} \
    --view=_AllLogs \
    --project={central_project_id}
```

Setup Steps: Read-Time Aggregation (Log Scopes)

设置步骤：实时聚合（日志范围）

Create or select a Google Cloud project that you will use for querying your log data. This is the scoping project. Use these steps to configure a log scope. Log scopes let you issue a query for log data that is stored in multiple projects.

创建或选择用于查询日志数据的Google Cloud项目，即范围项目。使用以下步骤配置日志范围。日志范围允许您针对存储在多个项目中的日志数据执行查询。

1. Create a custom Log View (Optional but recommended) (Tier M)

1. 创建自定义日志视图（可选但推荐）（M级）

Create a Log View in the source project to restrict which logs are accessible.

[!IMPORTANT] Gotcha: Log View filters can only contain specific restrictions. Refer to https://docs.cloud.google.com/logging/docs/logs-views.md.txt#view-filter

bash

gcloud logging views create {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={source_project_id} \
    --log-filter='LOG_ID("{log_id}")'

```
{bucket_id}
```
: for example,
```
_Default
```
```
{region}
```
: for example,
```
global
```
```
{view_id}
```
: for example,
```
app-logs-view
```
If you want to allow access to all logs in the log bucket, omit the
```
--log-filter
```
flag.

在源项目中创建日志视图以限制可访问的日志。

[!IMPORTANT] **注意事项：**日志视图过滤器只能包含特定的限制条件。请参考 https://docs.cloud.google.com/logging/docs/logs-views.md.txt#view-filter

bash

gcloud logging views create {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={source_project_id} \
    --log-filter='LOG_ID("{log_id}")'

```
{bucket_id}
```
：例如
```
_Default
```
```
{region}
```
：例如
```
global
```
```
{view_id}
```
：例如
```
app-logs-view
```
如果要允许访问日志存储桶中的所有日志，请省略
```
--log-filter
```
标志。

2. Create a log scope in the scoping project (Tier M)

2. 在范围项目中创建日志范围（M级）

Create a log scope in the scoping project listing the source resources, which may be projects or specific log views.

bash

gcloud logging scopes create {log_scope_id} \
    --project={scoping_project_id} \
    --resource-names={resource_names}

```
{log_scope_id}
```
: for example,
```
central-query-scope
```

{resource_names}

: Comma-separated list of log views. For example,

projects/source-project-1/locations/global/buckets/_Default/views/app-logs-view,projects/source-project-2/locations/global/buckets/_Default/views/app-logs-view

. You can include up to 100 views in the scope.

在范围项目中创建一个日志范围，列出源资源，这些资源可以是项目或特定的日志视图。

bash

gcloud logging scopes create {log_scope_id} \
    --project={scoping_project_id} \
    --resource-names={resource_names}

```
{log_scope_id}
```
：例如
```
central-query-scope
```

{resource_names}

：逗号分隔的日志视图列表。例如

projects/source-project-1/locations/global/buckets/_Default/views/app-logs-view,projects/source-project-2/locations/global/buckets/_Default/views/app-logs-view

。您可以在范围中包含最多100个视图。

3. Update Default Observability Scope (Optional) (Tier M)

3. 更新默认可观测性范围（可选）（M级）

Link the log scope to the project's default observability scope so it is used by default in Logs Explorer.

bash

gcloud observability scopes update _Default \
    --project={scoping_project_id} \
    --location=global \
    --log-scope=//logging.googleapis.com/projects/{scoping_project_id}/locations/global/logScopes/{log_scope_id}

将日志范围链接到项目的默认可观测性范围，以便在Logs Explorer中默认使用它。

bash

gcloud observability scopes update _Default \
    --project={scoping_project_id} \
    --location=global \
    --log-scope=//logging.googleapis.com/projects/{scoping_project_id}/locations/global/logScopes/{log_scope_id}

4. Grant IAM permissions to users (Tier B)

4. 向用户授予IAM权限（B级）

Unlike centralized routing, permissions are checked at query time on all source projects. Users running queries must have:

```
roles/logging.viewAccessor
```
granted on the specific Log View (with IAM conditions) or
```
roles/logging.viewer
```
on the source projects.
Access to the scoping project.

与集中式路由不同，权限会在查询时在所有源项目中进行检查。执行查询的用户必须拥有：

在特定日志视图上授予的
```
roles/logging.viewAccessor
```
角色（带有IAM条件），或在源项目上授予的
```
roles/logging.viewer
```
角色。
对范围项目的访问权限。

Troubleshooting Cross-Project Log Routing and Sink Permission Failures

排查跨项目日志路由与接收器权限故障

If logs are not appearing in a central project's bucket after configuring centralized logging:

配置集中式日志后，如果日志未出现在中央项目的存储桶中：

1. Verify Log Router Sink Filters in Source Resource

1. 验证源资源中的日志路由器接收器过滤器

Ensure that the log sink's filter matches the logs you expect to route.
[!IMPORTANT] Gotcha: Standard filter expressions like
```
logName:abc
```
or
```
logName="projects/{project_id}/logs/abc"
```
can fail to match in log sinks. Always use
```
LOG_ID("abc")
```
for precise matching in log sink filters.
Verify that you have not configured an exclusion filter that accidentally discards these logs.

确保日志接收器的过滤器与您期望路由的日志匹配。
[!IMPORTANT] **注意事项：**标准过滤器表达式如
```
logName:abc
```
或
```
logName="projects/{project_id}/logs/abc"
```
可能无法在日志接收器中匹配成功。请始终在日志接收器过滤器中使用
```
LOG_ID("abc")
```
进行精确匹配。
验证您是否未配置会意外丢弃这些日志的排除过滤器。

2. Verify and Grant Writer Identity Permissions (Most Common Cause)

2. 验证并授予写入者身份权限（最常见原因）

The log sink's writer identity service account in the source project must be explicitly granted the necessary permissions on the central resource.

Step A: Get the Writer Identity

bash

gcloud logging sinks describe {sink_name} \
    --project={source_project_id} \
    --format="value(writerIdentity)"

Step B: Grant the Permission in the Central Project (Tier B)

[!IMPORTANT] Security Action (Tier B): Granting IAM permissions changes access control policy and must be explicitly confirmed by the user before execution.
- For Cloud Logging Buckets (standard): Grant
```
roles/logging.bucketWriter
```
  :
  bash
```
gcloud projects add-iam-policy-binding {central_project_id} \
    --member={writer_identity} \
    --role=roles/logging.bucketWriter
```
- For GCS Buckets: Grant
```
roles/storage.objectCreator
```
  on the GCS bucket.
- For Pub/Sub Topics: Grant
```
roles/pubsub.publisher
```
  on the Pub/Sub topic.
- For BigQuery Datasets: Grant
```
roles/bigquery.dataEditor
```
  on the BigQuery dataset.

源项目中日志接收器的写入者身份服务帐户必须被明确授予中央资源所需的权限。

步骤A：获取写入者身份

bash

gcloud logging sinks describe {sink_name} \
    --project={source_project_id} \
    --format="value(writerIdentity)"

步骤B：在中央项目中授予权限（B级）

[!IMPORTANT] **安全操作（B级）：**授予IAM权限会更改访问控制策略，必须在执行前获得用户的明确确认。
- **针对Cloud Logging存储桶（标准）：**授予
```
roles/logging.bucketWriter
```
  角色：
  bash
```
gcloud projects add-iam-policy-binding {central_project_id} \
    --member={writer_identity} \
    --role=roles/logging.bucketWriter
```
- **针对GCS存储桶：**在GCS存储桶上授予
```
roles/storage.objectCreator
```
  角色。
- **针对Pub/Sub主题：**在Pub/Sub主题上授予
```
roles/pubsub.publisher
```
  角色。
- **针对BigQuery数据集：**在BigQuery数据集上授予
```
roles/bigquery.dataEditor
```
  角色。

cloud-logging-cross-project-configuration

Original

Translation

Configuring Cross-Project Logging

跨项目日志配置

Safety and Confirmation Tiers (CRITICAL)

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

Decision Matrix: Centralized Storage vs. Distributed Storage with Read-Time Aggregation

决策矩阵：集中式存储 vs 带实时聚合的分布式存储

Architecture

架构

Centralized Storage (Log Routing)

集中式存储（日志路由）

Read-Time Aggregation (Log Scopes)

实时聚合（日志范围）

Setup Steps: Centralized Storage (Log Routing)

设置步骤：集中式存储（日志路由）

1. Create log bucket in central project (Tier M)

1. 在中央项目中创建日志存储桶（M级）

2. Create log sink in central project (Tier M)

2. 在中央项目中创建日志接收器（M级）

3. Create log sink in source resource (Tier M)

3. 在源资源中创建日志接收器（M级）

4. Grant IAM permissions to sink writers (Tier B)

4. 向接收器写入者授予IAM权限（B级）

5. Create custom Log Views on the central bucket (Tier M)

5. 在中央存储桶上创建自定义日志视图（M级）

Verify Centralized Log Routing (Tier R)

验证集中式日志路由（R级）

Setup Steps: Read-Time Aggregation (Log Scopes)

设置步骤：实时聚合（日志范围）

1. Create a custom Log View (Optional but recommended) (Tier M)

1. 创建自定义日志视图（可选但推荐）（M级）

2. Create a log scope in the scoping project (Tier M)

2. 在范围项目中创建日志范围（M级）

3. Update Default Observability Scope (Optional) (Tier M)

3. 更新默认可观测性范围（可选）（M级）

4. Grant IAM permissions to users (Tier B)

4. 向用户授予IAM权限（B级）

Troubleshooting Cross-Project Log Routing and Sink Permission Failures

排查跨项目日志路由与接收器权限故障

1. Verify Log Router Sink Filters in Source Resource

1. 验证源资源中的日志路由器接收器过滤器

2. Verify and Grant Writer Identity Permissions (Most Common Cause)

2. 验证并授予写入者身份权限（最常见原因）

References and Supporting Links

参考资料与支持链接