This document explains how Cloud Logging routes log entries that arereceived by Google Cloud. There are several different types of routingdestinations. For example, you can route log entries to a destination like alog bucket, which stores log entries. If you want to export your log datato a third-party destination, then you can route log entries to Pub/Sub.Also, a log entry can be routed to multiple destinations.

At a high level, this is how Cloud Logging routes and stores log entries:

About Log Routers

Each Google Cloud project, billing account, folder, and organization has aLog Router, which manages the flow of log entries throughresource-level sinks. A Log Router also manages the flow of a log entrythrough sinks that are in the entry'sresource hierarchy.Sinks control how log entries are routed to destinations.

A Log Router stores a log entry temporarily. This behaviorbuffers against temporary disruptions and outages that might occur whena log entry flows through sinks. Temporary storage doesn't protectagainst configuration errors.

A Log Router's temporary storage is distinct from the longerterm storage provided by Logging buckets.

Incoming log entries with timestamps that are more than thelogs retention period in the past or thatare more than 24 hours in the future are discarded.

About log sinks

When a log sink receives a log entry, it determines whether it should ignoreor route the log entry. This decision is made by comparing the log entryto the filters in the log sink. When the log entry is routed, the log sinksends the log entry to the destination specified by the log sink. Thatdestination might be a project, a storage location, or a service.

Log sinks belong to a given Google Cloud resource: Google Cloud projects,billing accounts, folders, and organizations. These resources also containmultiple log sinks. When a resource receives a log entry, every log sinkin that resource independently evaluates the log entry. As a result,multiple log sinks can route the same log entry.

By default, log data is stored in the project where the data originates.However, there are several reasons why you might want to change thisconfiguration:

• To centralize the storage of your log data.
• To join your log data with other business data.
• To organize your log data in a way that is useful to you.
• To stream your logs to other applications, other repositories, or thirdparties. For example, you might want to export your logs from Google Cloud sothat you can view them on a third-party platform. To export your log entries,create a log sink that routes your log entries to Pub/Sub.

A misconfigured log sink doesn't route log entries. When a sink ismisconfigured, log entries that report the detail of the error are written.Also, an email is sent to the Essential Contacts for the resource.For more information, seeTroubleshoot: View errors.

Log sinks can't retroactively route log entries. That is, a log sink can'troute a log entry that was received before the sink was created. Similarly,if a sink is misconfigured, then the sink only routes log entries that arriveafter the configuration error is resolved.However, you can retroactively copy log data from a log bucket toCloud Storage. For more information, seeCopy logs.

Support for organizations and folders

To help you manage the log data in an organization or folder, you can dothe following:

• You can createaggregated sinks, which route log entries for anorganization or folder and their children, to the destination specifiedby the sink. There are two types of aggregated sinks:

  • Non-intercepting aggregated sinks
  • Intercepting aggregated sinks

  The difference between these two sink types is that intercepting sinksat one level in the resource hierarchy can affect routing for resourceslower in the hierarchy. Non-intercepting sinks don't affect routing for otherresources.When an intercepting sink in a resource matches a log entry, the log entryisn't sent to the sinks in child resources, with the exception that thelog entry is always sent to the_Required log sinkin the resource where the log entry originates.

• You can configureDefault resource settings to specifythe configuration of the system-created_Default sink for new resourcesin an organization or folder. For example, you can use these settingsto disable the_Default sink or specify the filters in that sink.

Routing examples

This section illustrates how a log entry that originates in a projectmight flow through the sinks in its resource hierarchy.

Example: No aggregated sinks exist

When no aggregated sinks exist in the resource hierarchy of the log entry,the log entry is sent to the log sinks in the project where the log entryoriginates. A project-level sink routes the log entry to the sink'sdestination when the log entry matches the sink's inclusion filter but doesn'tmatch any of the sink's exclusion filters.

Example: A non-intercepting aggregated sink exists

Assume that a non-intercepting aggregated sink exists in the resourcehierarchy for a log entry. After the Log Router sends the log entry tothe non-intercepting aggregated sink, the following occurs:

1. The non-intercepting aggregated sink routes the log entry to the sink'sdestination when the log entry matches the inclusion filter but doesn'tmatch any exclusion filter.

2. The Log Router sends the log entry to the log sinks in the projectwhere the log entry originated.

   A project-level sink routes the log entry to the sink'sdestination when the log entry matches the sink's inclusion filter but doesn'tmatch any of the sink's exclusion filters.

Example: An intercepting aggregated sink exists

Assume that an intercepting aggregated sink exists in the resourcehierarchy for a log entry. After the Log Router sends the log entry tothe intercepting aggregated sink, one of the following occurs:

• The log entry matches the inclusion filter but doesn't matchany exclusion filter:

  1. The log entry is routed to the destination of theintercepting aggregated sink.
  2. The log entry is sent to the_Required sink in the project where thelog entry originated.

• The log entry doesn't match the inclusion filter or it matchesat least one exclusion filter:

  1. The log entry isn't routed by the intercepting aggregated sink.

  2. The Log Router sends the log entry to the log sinks in the projectwhere the log entry originated.

     A project-level sink routes the log entry to the sink'sdestination when the log entry matches the sink's inclusion filter but doesn'tmatch any of the sink's exclusion filters.

Log sink filters

Each log sink contains one inclusion filter andcan contain multiple exclusion filters. These filters determinewhether the log sink routes a log entry to the destination of the sink.If you don't specify any filters, then every log entry is routed tothe sink's destination.

A log entry is routed by a log sink based on these rules:

• If the log entry doesn't match the inclusion filter, then it isn't routed.When a sink doesn't specify an inclusion filter, then every log entrymatches that filter.

• If the log entry matches the inclusion filter and at least oneexclusion filter, then it isn't routed.

• If the log entry matches the inclusion filter and doesn'tmatch any exclusion filter, then it is routed to the sink's destination.

The filters in a log sink are specified by using theLogging query language.

You can't use exclusion filters to reduce the consumption of yourentries.write API quota or thethe number ofentries.write API calls. Exclusion filtersare applied after log entries are received by the Logging API.

System-created log sinks

For each Google Cloud project, billing account, folder, and organization,Cloud Logging creates two log sinks, one named_Required and the othernamed_Default. The inclusion and exclusion filters for these sinks verifythat every log entry that reaches the resource is routed by one of these sinks.Both sinks route log data to a log bucket that is in the same resource as thelog sink.

The remainder of this section provides information about the filters anddestinations of the system-created log sinks.

_Required log sink

The_Required log sink in a resource, routes a subset of audit logs to theresource'_Required log bucket.This sink doesn't specify any exclusion filters, and the inclusion filteris as shown:

LOG_ID("cloudaudit.googleapis.com/activity") ORLOG_ID("externalaudit.googleapis.com/activity") ORLOG_ID("cloudaudit.googleapis.com/system_event") ORLOG_ID("externalaudit.googleapis.com/system_event") ORLOG_ID("cloudaudit.googleapis.com/access_transparency") ORLOG_ID("externalaudit.googleapis.com/access_transparency")

The_Required log sink only matches log entries that originate in theresource where the_Required log sink is defined. For example, supposea log sink routes an activity log entry from projectA to projectB.Because the log entry didn't originate in projectB, the_Required log sink in projectB doesn't route this log entry to the_Required log bucket.

You can't modify or delete the_Required log sink.

_Default log sink

The_Default log sink in a resource, routes all log entriesexcept those that match the filter of the_Required log sink,to the resource'_Default log bucket.Because the inclusion filter for this sink is empty, it matches alllog entries. However, the exclusion filter is configured as follows:

NOT LOG_ID("cloudaudit.googleapis.com/activity") ANDNOT LOG_ID("externalaudit.googleapis.com/activity") ANDNOT LOG_ID("cloudaudit.googleapis.com/system_event") ANDNOT LOG_ID("externalaudit.googleapis.com/system_event") ANDNOT LOG_ID("cloudaudit.googleapis.com/access_transparency") ANDNOT LOG_ID("externalaudit.googleapis.com/access_transparency")

You can modify and disable the_Default log sink. For example, you canedit the_Default log sink and change the destination. You can alsomodify any existing filter and add exclusion filters.

Sink destinations

Google Cloud project

Select this destination when you want the log sinks in thedestination project to reroute your log entries, or when you have createdan intercepting aggregated sink. The log sinks in the project that is thesink destination can reroute the log entries to any supported destinationexcept a project.

Note: This is the only type of destination where log entries are rerouted.For example, if you route log entries from one project to a log bucket inanother project, then those log entries aren't rerouted by the log sinksin the project that stores the log bucket.

Log bucket

Select this destination when you want to store your log data inresources managed by Cloud Logging. Log data stored in log bucketscan be viewed and analyzed using services like the Logs Explorerand Log Analytics.

If you want to join your log data with other business data, then youcan store your log data in a log bucket and create a linkedBigQuery dataset. A linked dataset is a read-only datasetthat can be queried like any other BigQuery dataset.

BigQuery dataset

Select this destination when you want to join your log data withother business data. The dataset you specify must be write-enabled.Don't set the destination of a sink to be a linkedBigQuery dataset. Linked 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 same project in which log entriesoriginate, 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 fromGoogle Cloud and then use third-party integrations like Splunk or Datadog.Log entries are formatted into JSON and then routed toa 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, seeError Reporting overview.

• If you route log entries to a BigQuery dataset, theBigQuery dataset must be write-enabled. You can't routelog entries to linked datasets, which are read-only.

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

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

  • There is a one-hop limit.
  • Log entries that match the filter of the_Required log sinkare only routed to the_Required log bucket of the destination projectwhen they originate in the destination project.
  • Only aggregated sinks that are in the resource hierarchy of a log entryprocess the log entry.

  For example, assume the destination of a log sink in projectA isprojectB. Then the following are true:

  • Due to the one-hop limit, the log sinks in projectB can't reroutelog entries to a Google Cloud project.
  • The_Required log bucket of projectB only stores log entries thatoriginate in projectB. This log bucket doesn't store any logentries that originate in any other resource, including thosethat originate in projectA.
  • If the resource hierarchy of projectA and projectB differ, thena log entry that a log sink in projectA routes to projectBisn't sent to the aggregated sinks in the resource hierarchy ofprojectB.
  • If projectA and projectB 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 log entry to the sinks in projectA.

How routing log entries affects log-based metrics

Log-based metrics areCloud Monitoring metricsthat are derived from the content of log entries. For example, you can use alog-based metric to count the number of log entries that contain a particularmessage or to extract latency information recorded in log entries.You can display log-based metrics in Cloud Monitoring charts, and alertingpolicies can monitor these metrics.

System-defined log-based metrics apply at the project level. User-definedlog-based metrics can apply at the project level or log bucket level.Bucket-scoped log-based metrics are useful when you use aggregated sinksto route log entries to a log bucket, and when you route log entries fromone project to a log bucket in another project.

System-defined log-based metrics

The Log Router counts a log entry when all of the following are true:

• The log entry passes through the log sinks of the project where the log-based metric is defined.

• The log entry is stored in a log bucket. The log bucket can be in any project.

  For example, suppose projectA has a log sink whose destination is projectB. Also assume that the log sinks in the projectB route the log entries to a log bucket. In this scenario, the log entries routed from projectA to projectB contribute to projectA's system-defined log-based metrics. These log entries also contribute to projectB's system-defined log-based metrics.

User-defined log-based metrics

The Log Router counts a log entry when all of the following are true:

• Billing is enabled on the project where the log-based metric is defined.
• For bucket-scoped metrics, the log entry is stored in the log bucket where the log-based metric is defined.
• For project-scoped metrics, the log entry passes through the log sinks of the project where the log-based metric is defined.

For more information, seeLog-based metrics overview.

Best practices

For best practices about using routing for data governance or for commonuse cases, see the following documents:

• Aggregate your organization's log into a central logbucket

• Regionalize your logs

• Set up multi-tenant logging for GKE

• Configure CMEK for logs routing

• Logs data: A step by step guide for overcoming common compliancechallenges

• Data governance: Principles for securing and managinglogs

Examples: Centralize your log storage

This section outlines how you mightconfigure centralized storage. Centralized storageprovidesa single place to query for log data, which simplifies your queries when youare searching for trends or investigating issues. From a security perspective,you also have one storage location, which can simplify the tasks of yoursecurity analysts.

If you centralize your log storage, then consider whether to place a lien on theproject that stores your log data. A lien can prevent the accidental deletion ofa project. To learn more, seeProtecting projects with liens.

Centralize log storage for projects in a folder

Suppose that you manage a folder and want to centralize the storageof your log entries. For this use case, you might do the following:

1. In your folder, you create a project namedCentralStorage.
2. Create an intercepting aggregated sink for your folder and you configureit to route all log entries. You set the destination of the sink to be theproject namedCentralStorage.

When a log entry that originates in the folder or in one of its childresources arrives, that log entry is sent to theintercepting aggregated sink that you created. That sink routes log entriesto the project namedCentralStorage. The log sinks in this projectprocess the log entries:

• The_Default log sink routes to the_Default log bucket all log entries that match the sink's filter.This log bucket is your centralized storage location.

• The_Required log sink routes to the_Required log bucket the log entries that match the sink's filters andthat originate in theCentralStorage project. This log bucket isn't acentralized storage location. However, you can centrally store all yourlog data. For an example, seeStore audit logs in a central location.

After the aggregated sink processing completes, the log entry is sent tothe_Required log sink in theresource in which the log entry originated. When the log entry matchesthe filter in the_Required log sink, the log entry is routed to theresource's_Required log bucket. Consequently, each Google Cloud project in yourfolder stores log entries in their_Required log bucket.

Centralize log storage for a set of projects

You can also store log entries in a single location when you don't have anorganization or a folder. For example, you might do the following:

1. Create a project namedCentralStorage.
2. For each project exceptCentralStorage, you edit the_Default log sinkand set the destination to be the project namedCentralStorage.

You might wonder why the previous example sets the destination of the_Default log sinks to be a project, instead of the_Default log bucketin that project. The primary reasons are simplicity and consistency.When you route log entries to a project, the log sinks in the destinationproject control which log entries are stored and where they are stored.That is, you centralize the filter and destination functionality. If you wantto change which log entries are stored or where they are stored, then youonly need to modify the log sinks in one project.

Centralize log storage for audit logs

You can centrally store log entries that match the_Required log sink. If you want store these log entriescentrally, then do one of the following:

• Create log sinks that route log entries that match the_Required log sink to a centralized log bucket.

• Configure log sinks as in the previous two examples, and then adda log sink in the destination project that routes log entries thatmatch the_Required log sink to a log bucket. Youcould also edit the filters in the_Default log sink.

Before you implement such a strategy, review the pricing guidelines.

Pricing

To learn about pricing for Cloud Logging, see theGoogle Cloud Observability pricing page.

What's next

To help you route and store Cloud Logging data, see the followingdocuments:

• To create sinks to route log entries to supported destinations, seeRoute logs to supported destinations.

• To learn how to create aggregated sinks that can route log entries fromthe resources in folders or organizations, seeAggregated sinks overview.

• To learn about the format of routed log entries and how the logs areorganized in destinations, see the following documents:

  • View logs routed to log buckets.
  • View logs routed to BigQuery.
  • View logs routed to Cloud Storage.
  • View logs routed to log Pub/Sub.