Console

To create an aggregated sink for your folder or organization, do the following:

1. In the Google Cloud console, go to theLog Router page:

   Go toLog Router

   If you use the search bar to find this page, then select the result whose subheading isLogging.

2. Select an existing folder or organization.

3. SelectCreate sink.

4. In theSink details panel, enter the following details:

   • Sink name: Provide an identifier for the sink; note that after youcreate the sink, you can't rename the sink but you can delete it andcreate a new sink.

   • Sink description (optional): Describe the purpose or use case forthe sink.

5. In theSelect sink service menu, select the type of destination,and then complete the dialog to specify the destination. You can selectan existing destination or create the destination.

   • For an intercepting sink, selectGoogle Cloud project, and thenenter the fully-qualified name of the destination Google Cloud project:

     logging.googleapis.com/projects/DESTINATION_PROJECT_ID

   • For a non-intercepting sink, select the destination, and thenenter the fully-qualified name of the destination. The followingdestinations are supported:

     • Google Cloud project

       logging.googleapis.com/projects/DESTINATION_PROJECT_ID

     • Cloud Logging bucket

       logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME

     • BigQuery dataset

       You must enter the fully-qualified name of a write-enabled dataset.The dataset can be adate-sharded or partitioned table. Don't enter thename of a linked dataset. Linked datasets are read only.

       bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID

     • Cloud Storage bucket

       storage.googleapis.com/BUCKET_NAME

     • Pub/Sub topic

       pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

     • Splunk

       Enter the Pub/Sub topic for yourSplunkservice.

6. In theChoose logs to include in sink panel, select the resourcesto include in the sink.

   • For an intercepting sink, selectIntercept logs ingested by this organization and all child resources.

   • For a non-intercepting sink, selectInclude logs ingested by this resource and all child resources.

7. In theBuild inclusion filter field,enter a filter expression that matches the log entries youwant to include. If you don't set a filter, alllog entries from your selected resource are routed to the destination.

   For example, you might want to build a filter to route all Data Accessaudit logs to a single Logging bucket. This filter lookslike the following:

   LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")

   For filter examples, seeCreate filters for aggregated sinks section of thispage.

   Note that the length of a filter can't exceed 20,000 characters.

8. Optional: To verify you entered the correct filter, selectPreview logs. This opens the Logs Explorer in a new tab with thefilter pre-populated.

9. Optional: In theChoose logs to exclude from the sink panel, dothe following:

   1. In theExclusion filter name field, enter a name.

   2. In theBuild an exclusion filter field, enter afilter expression thatmatches the log entries you want to exclude. You can also use thesample functionto select a portion of the log entries to exclude.

      Key Point: If you want your exclusion filter to be disabledwhen the sink is created, then selectDisable after you enteryour filter expression. You can update the sink later to enable theexclusion filter.

      For example, to exclude the log entries from a specific project frombeingrouted to the destination, add the following exclusion filter:

      logName:projects/PROJECT_ID

      To exclude log entries from multiple projects, use the logical-ORoperator to joinlogName clauses.

   You can create up to 50 exclusion filtersper sink. Note that the length of a filter can't exceed20,000 characters.

10. SelectCreate sink.

11. To complete the configuration of your aggregated sink,grant the service account for the sink the permission to writelog entries to your sink's destination. For more information, seeSet destination permissions.

gcloud

To create an aggregated sink, use thelogging sinks create command:

1. To create a sink, call thegcloud logging sinks createcommand, and ensure that you include the--include-children option.

   Before using the following command, make the following replacements:

   • SINK_NAME: The name of the log sink. You can't change the name of a sink after you create it.
   • SINK_DESTINATION: The service or project to where you want your log entries routed. For information about the format of thesedestinations, seeDestination path formats.
   • INCLUSION_FILTER: The inclusion filter for a sink. For filter examples, seeCreate filters for aggregated sinks.
   • FOLDER_ID: The ID of the folder. If you want to create a sinkat the organization level, then replace--folder=FOLDER_ID with-- organization=ORGANIZATION_ID.

   Execute thegcloud logging sinks createcommand:

   gcloud logging sinks createSINK_NAME \SINK_DESTINATION  --include-children \  --folder=FOLDER_ID --log-filter="INCLUSION_FILTER"

   You can also provide the following options:

   • To create an intercepting sink, include the--intercept-children option.

   For example, if you're creating an aggregated sink at the folder leveland whose destination is a Pub/Sub topic, your commandmight look like the following:

   gcloudloggingsinkscreateSINK_NAME\pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID--include-children \--folder=FOLDER_ID --log-filter="logName:activity"

2. Grant the service account for the sink permission to write to your sinkdestination. For more information, seeSet destination permissions.

REST

To create an aggregated sink, use theorganizations.sinks.create orfolders.sinks.create Logging API method.Prepare the arguments to the method as follows:

1. Set theparent field to be the Google Cloud organization orfolder in which to create the sink. The parent must be one of thefollowing:

   • organizations/ORGANIZATION_ID
   • folders/FOLDER_ID

2. In theLogSink object in the method request body,do one of the following:

   • SetincludeChildren toTrue.

   • To create an intercepting sink, also set theinterceptChildren field toTrue.

3. Set thefilter field to match the log entries you want to include.

   For filter examples, seeCreate filters for aggregated sinks.

   The length of a filter can't exceed 20,000 characters.

4. Set the remainingLogSink fields as you would for any sink.For more information, seeRoute logs to supported destinations.

5. Callorganizations.sinks.create orfolders.sinks.create tocreate the sink.

6. Grant the service account for the sink permission to write to your sinkdestination. For more information, seeSet destination permissions.

Console

1. To get information about the service account for your sink,do the following:

   1. In the Google Cloud console, go to theLog Router page:

      Go toLog Router

      If you use the search bar to find this page, then select the result whose subheading isLogging.

   2. Selectmore_vertMenu and then selectView sink details. The writer identity appears in theSink details panel.

   3. If the value of thewriterIdentity field contains an email address,then proceed to the next step. When the value isNone, you don'tneed to configure destination permissions.

   4. Copy the sink's writer identity into your clipboard. Writer identitiesmight look different depending on what resource your sink belongs to,but are always prefixed byserviceAccount:. The following is anexample of a writer identity:

      serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

2. Grant the principal specified by the sink's writer identity thepermission to write log data to the destination:

   1. In the Google Cloud console, go to theIAM page:

      Go toIAM

      If you use the search bar to find this page, then select the result whose subheading isIAM & Admin.

   2. In the toolbar of the Google Cloud console, select the project which storesthe destination of the aggregated sink. When the destination is aproject, select that project.

   3. Clickperson_addGrant access.

   4. Enter the principal specified by the sink's writer identity andthen grant an IAM role:

      • For all destinations, grant theLogs Writer role (roles/logging.logWriter). Specifically, a principal needs thelogging.logEntries.route permission.
      • Grant one of the following roles based on the destination:
        • Log bucket: Grant theLogs Bucket Writer role (roles/logging.bucketWriter).
        • Cloud Storage bucket: Grant theStorage Object Creator role (roles/storage.objectCreator).
        • BigQuery dataset: Grant theBigQuery Data Editor role (roles/bigquery.dataEditor).
        • Pub/Sub topic, including Splunk: Grant thePub/Sub Publisher role (roles/pubsub.publisher).

gcloud

1. Ensure that you haveOwner access on theGoogle Cloud project that contains the destination.If you don't haveOwner access to the destination of the sink,then ask a project owner to add the writer identity as a principal.

2. To get information about the service account for your sink, call thegcloud logging sinks describe method.

   Before using the following command, make the following replacements:

   • SINK_NAME: The name of the log sink. You can't change the name of a sink after you create it.

   Execute thegcloud logging sinks describecommand:

   gcloudloggingsinksdescribeSINK_NAME

3. If the sink details contain a field labeledwriterIdentity, thenproceed to the next step. When the details don't include awriterIdentityfield, you don't need to configure destination permissions for the sink.

4. Copy the sink's writer identity into your clipboard. The followingillustrates a writer identity:

   serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

5. Grant the sink's writer identity the permission to write log data to thedestination by calling thegcloud projects add-iam-policy-binding command.

   Before using the following command, make the following replacements:

   • PROJECT_ID: The identifier of the project. Select the project which stores the destination ofthe aggregated sink. When the destination is a project, select thatproject.
   • PRINCIPAL: An identifier for the principal that you want to grant the role to. Principal identifiers usually have the following form:PRINCIPAL-TYPE:ID. For example,user:my-user@example.com. For a full list of the formats thatPRINCIPAL can have, seePrincipal identifiers.

   • ROLE: An IAM role. Grant the sink's writer identity an IAMrole based on the destination of the log sink:

     • For all destinations, grant theLogs Writer role (roles/logging.logWriter). Specifically, a principal needs thelogging.logEntries.route permission.
     • Grant one of the following roles based on the destination:
       • Log bucket: Grant theLogs Bucket Writer role (roles/logging.bucketWriter).
       • Cloud Storage bucket: Grant theStorage Object Creator role (roles/storage.objectCreator).
       • BigQuery dataset: Grant theBigQuery Data Editor role (roles/bigquery.dataEditor).
       • Pub/Sub topic, including Splunk: Grant thePub/Sub Publisher role (roles/pubsub.publisher).

     Execute thegcloud projects add-iam-policy-bindingcommand:

     gcloudprojectsadd-iam-policy-bindingPROJECT_ID--member=PRINCIPAL--role=ROLE

REST

We recommend that you use the Google Cloud console or the Google Cloud CLI to grant a role to the service account.