Cloud Logging Configuration Basics

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

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.

Getting Started

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

Creating Log Buckets (Compliance and Analytics) (Tier 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."

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.

Verify the Log Bucket (Tier R)

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

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

Route logs to the Log Bucket (Tier 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:

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)

[!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:

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.

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

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

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