/cloud-logging-cross-project-configuration

name: cloud-logging-cross-project-configuration
description: >-
  Configure and troubleshoot Google Cloud cross-project centralized logging and read-time aggregation.
  Use when:
  - Setting up log routing from multiple projects/folders/organizations to a central log bucket.
  - Creating cross-project log sinks and configuring central log buckets.
  - Troubleshooting cross-project routing.
  Don't use for single-project basic configurations.
metadata:
  category: CloudObservabilityAndMonitoring

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.

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:

1. **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. 2. **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. 3. **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. 4. **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.

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

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. :