Route logs to supported destinations

This document explains how to create and manage log sinks, which route log entries that originate in a Google Cloud project to supported destinations.

A sink performs a write action and therefore it must be authorized to write to the destination. When the destination is a log bucket in the same project as the sink, the sink is automatically authorized. For all other destinations, the sink must be attached to a service account that has been granted the permissions required to write data to the destination.

When a service account is required, Cloud Logging automatically creates and manages it. However, you might need to modify the permissions granted to the service account. You don't have to use the service account created by Logging. You can create and manage a service account that is used by sinks in multiple projects. For more information, see Configure log sinks with user-managed service accounts.

Overview

This page describes how to create a sink and how to configure the options you might see when using the Google Cloud console or the API.

Sinks belong to a given Google Cloud resource: a Google Cloud project, a billing account, a folder, or an organization. When the resource receives a log entry, every sink in the resource processes the log entry. When a log entry matches the filters of the sink, then the log entry is routed to the sink's destination.

Typically, sinks only route the log entries that originate in a resource. However, for folders and organizations you can create aggregated sinks, which route log entries from the folder or organization, and the resources it contains. This document doesn't discuss aggregated sinks. For more information, see Aggregated sinks overview.

To create and manage sinks, you can use the Google Cloud console, the Cloud Logging API, and the Google Cloud CLI. We recommend that you use the Google Cloud console for the following reasons:

• You can configure sink destinations as part of the flow to create a sink.
• You can preview which log entries match the sink's filters.
• Some authorization steps are simplified.

We recommend that you review your log sink configuration when you make any changes to your log storage. For example, if you delete the destination of a log sink, then delete the corresponding log sink.

To learn how to view and manage your log sinks, see the Manage sinks section of this document.

Supported destinations

The destination of a sink can be in a different resource from the sink. For example, you can use a log sink to route log entries from one project to a log bucket stored in a different project.

The following destinations are supported:

Google Cloud project

Select this destination when you want the log sinks in the destination project to reroute your log entries, or when you have created an intercepting aggregated sink. The log sinks in the destination project can reroute the log entries to any supported destination except a project.

The system-created log sinks in the destination project exclude log entries that are routed to the _Required log bucket in the source project. For example, if you route Admin Activity logs to another project, then both the _Required and _Default log sinks in the destination project exclude those log entries. To store those log entries, in the destination project update the _Default log sink or create a custom log sink.

Log bucket

Select this destination when you want to store your log data in resources managed by Cloud Logging. Log data stored in log buckets can be viewed and analyzed using services like the Logs Explorer and Observability Analytics.

If you want to join your log data with other business data, then you can store your log data in a log bucket and create a linked BigQuery dataset. A linked BigQuery dataset is read-only, but you can query it like any other BigQuery dataset.

BigQuery dataset

Select this destination when you want to join your log data with other business data. The dataset you specify must be write-enabled. Don't set the destination of a sink to be a linked BigQuery dataset. Linked BigQuery datasets are read-only.

Cloud Storage bucket

Select this destination when you want long-term storage of your log data. The Cloud Storage bucket can be in the project where the log entries originate, or in a different project. Log entries are stored as JSON files.

Pub/Sub topic

Select this destination when you want to export your log data from Google Cloud and then use third-party integrations like Splunk or Datadog. Log entries are formatted as JSON and then routed to a Pub/Sub topic.

Destination limitations

This section describes destination-specific limitations:

• If you route log entries to a log bucket in a different Google Cloud project, then Error Reporting doesn't analyze those log entries. For more information, see Error Reporting overview.

• The following limitations apply when the destination of a log sink is a BigQuery dataset:

  • The BigQuery dataset must be write-enabled. Don't set the destination to be a linked BigQuery dataset. Linked datasets are read-only.
  • Logging creates a table inside the dataset for each log name. You can't rename a table while a sink is streaming data into it.

• New sinks that route log data to Cloud Storage buckets might take several hours to start routing log entries. These sinks are processed hourly.

• The following limitations apply when the destination of a log sink is a Google Cloud project:

  • There is a one-hop limit.
  • The _Required log sink in the destination project routes log entries to the project's _Required log bucket when the log entries match the sink's filter and originate in the destination project.
  • The _Default log sink in the destination project routes log entries that match its inclusion filter and don't match any exclusion filter. The _Default log sink excludes some log entries. For example, this sink doesn't route Admin Activity and System Event log entries. You can modify this sink.
  • Only aggregated sinks that are in the resource hierarchy of a log entry process the entry.

  For example, assume the destination of a log sink in project A is project B. In this case, the following rules apply:

  • Due to the one-hop limit, the log sinks in project B can't reroute log entries to another Google Cloud project.
  • The _Required log bucket of project B only stores log entries that originate in project B. This log bucket doesn't store any log entries that originate in any other resource, including those that originate in project A.
  • If project A and project B have different resource hierarchies, then a log entry that a log sink in project A routes to project B isn't sent to the aggregated sinks in the resource hierarchy of project B.
  • If project A and project B have the same resource hierarchy, then log entries are sent to the aggregated sinks in that hierarchy. If a log entry isn't intercepted by an aggregated sink, then the Log Router sends the entry to the sinks in project A.

Before you begin

The instructions in this document describe creating and managing sinks at the Google Cloud project level. You can use the same procedure to create a sink that routes log entries that originate in an organization, folder, or billing account.

To get started, do the following:

1. Enable the Cloud Logging API.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the API

2. Make sure that your Google Cloud project contains log entries that you can see in the Logs Explorer.

3. To get the permissions that you need to create, modify, or delete a sink, ask your administrator to grant you the Logs Configuration Writer (roles/logging.configWriter) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

   You might also be able to get the required permissions through custom roles or other predefined roles.

   For information about granting IAM roles, see the Logging Access control guide.

4. You have a resource in a supported destination or have the ability to create one.

   To route log entries to a destination, the destination must exist before you create the sink. You can create the destination in any Google Cloud project in any organization.

5. Before you create a sink, review the limitations that apply for the sink destination. For more information, see the Destination limitations section in this document.

6. Select the interface you plan to use:

   Console

   When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

   gcloud

   In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   REST

   To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

   Install the Google Cloud CLI.

   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

   For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Create a sink

This section describes how to create a sink in a Google Cloud project. You can create up to 200 sinks per Google Cloud project. To view the number and volume of log entries that are routed, view the logging.googleapis.com/exports/ metrics.

You use the Logging query language to create a filter expression that matches the log entries you want to include. Don't put sensitive information in sink filters. Sink filters are treated as service data.

When a query contains multiple statements, you can either specify how those statements are joined or rely on Cloud Logging implicitly adding the conjunctive restriction, AND, between the statements. For example, suppose a query or filter dialog contains two statements, resource.type = "gce_instance" and severity >= "ERROR". The actual query is resource.type = "gce_instance" AND severity >= "ERROR". Cloud Logging supports both disjunctive restrictions, OR, and conjunctive restrictions, AND. When you use OR statements, we recommend that you group the clauses with parentheses.

To create a sink, do the following: