This document describes how to create and manage log views on your Cloud Logging buckets by using the gcloud CLI. Log views give you advanced and granular control over who has access to the logs within your log buckets.
For general information about the Logging storage model, see Routing and storage overview.
About log views
Log views let you grant a user access to only a subset of the logs stored in a log bucket. For example, consider a scenario in which you store your organization's logs in a central project. You might create one log view for each project that contributes logs to the log bucket. You can then grant each user access to one or more log views, and thereby restrict which logs the users can view.
You can create a maximum of 30 log views per log bucket.
Control access to a log view
Cloud Logging uses IAM policies to control who has access to log views. IAM policies can exist at the resource, project, folder, and organization levels. For Cloud Logging, you can create an IAM policy for each log view. To determine whether a principal is authorized for an action, IAM evaluates all applicable policies, with the first evaluation at the resource level.
Principals with the role of roles/logging.viewAccessor
on a
Google Cloud project can access views and logs in any log bucket
in the project.
To grant a principal access to only a specific log view, do one of the following:
Create an IAM policy for the log view, and then add an IAM binding to that policy which grants the principal access to the log view.
If you create large numbers of log views, then we recommend this approach.
Grant the principal the IAM role of
roles/logging.viewAccessor
on the project that contains the log view, but attach an IAM condition to restrict the grant to the specific log view. If you omit the condition, then you grant the principal access to all log views. There is a limit of 20 role bindings in the policy file for a Google Cloud project that include the same role and the same principal, but different condition expressions.
For more information, see the section of this document titled Grant access to a log view.
Automatically created log views
Cloud Logging automatically creates an _AllLogs
view for every
log bucket and a _Default
view for the _Default
log bucket:
_AllLogs
view: You can view all logs in the log bucket._Default
view: You can view all non-Data Access audit logs in the log bucket.
You can't modify views that are automatically created by Cloud Logging;
however, you can delete the _AllLogs
view.
Log view filter
Each log view contains a filter that determines which log entries that are
visible in the view. Filters can contain logical AND
and NOT
operators;
however, they can't include logical OR
operators.
Filters can compare any of the following values:
A data source using the
source
function. Thesource
function returns log entries from a particular resource in the organizations, folders, and Google Cloud projects hierarchy.A log ID using the
log_id
function. Thelog_id
function returns log entries that match the givenLOG_ID
argument from thelogName
field.A valid resource type using the
resource.type=
FIELD_NAME comparison.
For example, the following filter captures Compute Engine stdout
log
entries from a Google Cloud project called myproject
:
source("projects/myproject") AND resource.type = "gce_instance" AND log_id("stdout")
For details about the filtering syntax, see Comparisons.
Before you begin
Before you create or update a log view, complete the following steps:
If you haven't already done so, in the appropriate Google Cloud project, create a Logging bucket for which you want to configure a custom log view.
-
To get the permissions that you need to create and manage log views and to grant access to log views, ask your administrator to grant you the following IAM roles on your project:
-
Logs Configuration Writer (
roles/logging.configWriter
) -
To add a role binding to a project:
Project IAM Admin (
roles/resourcemanager.projectIamAdmin
) -
To add a role binding to a log view:
Logging Admin (
roles/logging.admin
)
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.
-
Logs Configuration Writer (
-
In the Google Cloud console, 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.
Determine which logs you want to include in the view. You use this information to specify the filter of the log view.
Determine who should have access to the log view and whether you want to add bindings to the IAM policy of the log view or the Google Cloud project. For more information, see Control access to a log view.
Create a log view
To create a log view,
use the gcloud logging views update
command.
You can create a maximum of 30 log views per log bucket.
Before using any of the command data below, make the following replacements:
- VIEW_ID: The identifier of the log view.
- BUCKET_NAME: The name of the log bucket.
- LOCATION: The location of the log bucket.
- FILTER: A filter that defines the log view. When empty, the log view includes all logs. For example, to filter by Compute Engine VM instances logs, enter
"resource.type=gce_instance"
. - DESCRIPTION: A description of the log view. For example, you might enter the following for the
description
"Compute logs"
.
Execute the
gcloud logging views create
command:
Linux, macOS, or Cloud Shell
gcloud logging views create VIEW_ID --bucket=BUCKET_NAME --location=LOCATION --log-filter=FILTER --description=DESCRIPTION
Windows (PowerShell)
gcloud logging views create VIEW_ID --bucket=BUCKET_NAME --location=LOCATION --log-filter=FILTER --description=DESCRIPTION
Windows (cmd.exe)
gcloud logging views create VIEW_ID --bucket=BUCKET_NAME --location=LOCATION --log-filter=FILTER --description=DESCRIPTION
This command doesn't provide a response. To confirm the changes, you can run the
gcloud logging views list
command.
Next, grant principals access to your log view.
Grant access to a log view
To restrict a principal to a specific log view on a user-defined log bucket, there are two approaches that you can use:
You can use the IAM policy file of the log view.
You can use the IAM policy file of the Google Cloud project that stores the log bucket, along with an IAM condition.
When you create a large number of log views, we recommend that you control access by using the IAM policy file of the log view.
Log view: Add role bindings
This section describes how to use the IAM policy file for a log view to control who has access to the log entries in that log view. When you use this approach, you add a binding to the log view's policy file, the binding grants the specified principal access to the log view.
This section also describes how to list the role binding contained in the IAM policy file for a log view.
Add a role binding to a log view
To update the IAM policy file of a log view, complete the following steps.
gcloud
Before using any of the command data below, make the following replacements:
- VIEW_ID: The identifier of the log view.
- 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, see Principal identifiers. - BUCKET_NAME: The name of the log bucket.
- LOCATION: The location of the log bucket.
Execute the
gcloud logging views add-iam-policy-binding
command:
Linux, macOS, or Cloud Shell
gcloud logging views add-iam-policy-binding VIEW_ID --member=PRINCIPAL --role='roles/logging.viewAccessor' --bucket=BUCKET_NAME --location=LOCATION
Windows (PowerShell)
gcloud logging views add-iam-policy-binding VIEW_ID --member=PRINCIPAL --role='roles/logging.viewAccessor' --bucket=BUCKET_NAME --location=LOCATION
Windows (cmd.exe)
gcloud logging views add-iam-policy-binding VIEW_ID --member=PRINCIPAL --role='roles/logging.viewAccessor' --bucket=BUCKET_NAME --location=LOCATION
The following illustrates the response when a single binding is added:
Updated IAM policy for logging view [projects/PROJECT_ID/locations/global/buckets/BUCKET_NAME/views/VIEW_ID]. bindings: - members: - PRINCIPAL role: roles/logging.viewAccessor etag: BwYXfSd9-Gw= version: 1
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands. For more information, see the Terraform provider reference documentation.
To provision IAM associations for a log view by using Terraform, several different resources are available:
google_logging_log_view_iam_policy
google_logging_log_view_iam_binding
google_logging_log_view_iam_member
For more information, see IAM policy for Cloud Logging LogView.
Console
Not supported. To add bindings to a log view, use the Google Cloud CLI.
List role bindings on a log view
To list the IAM bindings for a log view, complete the following steps.
gcloud
Before using any of the command data below, make the following replacements:
- VIEW_ID: The identifier of the log view.
- BUCKET_NAME: The name of the log bucket.
- LOCATION: The location of the log bucket.
Execute the
gcloud logging views get-iam-policy
command:
Linux, macOS, or Cloud Shell
gcloud logging views get-iam-policy VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
Windows (PowerShell)
gcloud logging views get-iam-policy VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
Windows (cmd.exe)
gcloud logging views get-iam-policy VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
When a log view doesn't contain any bindings, the response contains only an etag
field. The following illustrates the response when a log view contains a single binding:
bindings: - members: - PRINCIPAL role: roles/logging.viewAccessor etag: BwYXfSd9-Gw= version: 1
Terraform
To list IAM associations for log views by using Terraform,
use the data source
google_logging_log_view_iam_policy
.
Console
Not supported. To list the bindings for a log view, use the Google Cloud CLI.
Google Cloud project: Add role bindings
This section describes how to add a role binding to a Google Cloud project, and how to list the bindings attached to a project. When you use this approach, to restrict a principal to having access to the log entries stored in a specific log view, you must add an IAM condition to the grant.
Add a role binding to a project
To add a role binding to the IAM policy file of a Google Cloud project, complete the following steps.
gcloud
Create a JSON or yaml file with your condition.
For example, you might create a file named
condition.yaml
with the following contents:expression: "resource.name == \"projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME/views/VIEW_ID\"" title: "My title" description: "My description"
Optional: To verify that the JSON or yaml file is properly formatted, run the following command:
gcloud alpha iam policies lint-condition --condition-from-file=condition.yaml
Update the IAM policy on the Google Cloud project by calling the
gcloud projects add-iam-policy-binding
method.Before using the following command, make the following replacements:
- PROJECT_ID: The identifier of the project.
- 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, see Principal identifiers.
Execute the
gcloud projects add-iam-policy-binding
command:gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role='roles/logging.viewAccessor' --condition-from-file=condition.yaml
The response to the previous command includes all role bindings.
- condition: description: My description expression: resource.name == "projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME/views/VIEW_ID" title: My title members: - PRINCIPAL role: roles/logging.viewAccessor
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands. For more information, see the Terraform provider reference documentation.
To provision IAM associations for projects by using Terraform, several different resources are available:
google_project_iam_policy
google_project_iam_binding
google_project_iam_member
For more information, see IAM policy for projects.
Console
In the project where you created the log bucket, do the following:
-
In the Google Cloud console, go to the IAM page:
If you use the search bar to find this page, then select the result whose subheading is IAM & Admin.
Click
Grant access.In the New principals field, add the user's email account.
In the Select a role drop-down menu, select Logs View Accessor.
This role provides users with read access to all views. To limit user access to a specific view, add a condition based on the resource name.
Click Add IAM condition.
Enter a Title and Description for the condition.
In the Condition type drop-down menu, select Resource > Name.
In the Operator drop-down menu, select is.
In the Value field, enter the ID of the log view, including the full path to the view.
For example:
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME/views/VIEW_ID
Click Save to add the condition.
Click Save to set the permissions.
List role binding on a project
To list the role bindings on a Google Cloud project, complete the following steps.
gcloud
Before using the following command, make the following replacements:
- PROJECT_ID: The identifier of the project.
Execute the
gcloud projects get-iam-policy
command:
gcloud projects get-iam-policy PROJECT_ID
The response to the previous command includes all role bindings.
- condition:
description: My description
expression: resource.name == "projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME/views/VIEW_ID"
title: My title
members:
- PRINCIPAL
role: roles/logging.viewAccessor
Terraform
To list IAM associations for projects by using Terraform,
use the data source
google_project_iam_policy
.
Console
In the Google Cloud console, go to the IAM page:
If you use the search bar to find this page, then select the result whose subheading is IAM & Admin.
The IAM page lists all principals, their IAM roles, and any conditions attached to those roles.
List log views on a log bucket
To list the log views created for a log bucket,
use the gcloud logging views list
command.
Before using any of the command data below, make the following replacements:
- BUCKET_NAME: The name of the log bucket.
- LOCATION: The location of the log bucket.
Execute the
gcloud logging views list
command:
Linux, macOS, or Cloud Shell
gcloud logging views list --bucket=BUCKET_NAME --location=LOCATION
Windows (PowerShell)
gcloud logging views list --bucket=BUCKET_NAME --location=LOCATION
Windows (cmd.exe)
gcloud logging views list --bucket=BUCKET_NAME --location=LOCATION
The response data is a list of log views. For each log view, the filter is shown along with
the create and last update dates. When the create and update dates are empty, the log view was
created when the Google Cloud project was creatd. The following example output shows that ther are
two view IDs, _AllLogs
and compute
, on the log bucket that was queried:
VIEW_ID: _AllLogs FILTER: CREATE_TIME: UPDATE_TIME: VIEW_ID: compute FILTER: resource.type="gce_instance" CREATE_TIME: 2024-02-20T17:41:17.405162921Z UPDATE_TIME: 2024-02-20T17:41:17.405162921Z
Update a log view
To update or modify a log view,
use the gcloud logging views update
command.
If you don't know the view ID, then see List log views.
Before using any of the command data below, make the following replacements:
- VIEW_ID: The identifier of the log view.
- BUCKET_NAME: The name of the log bucket.
- LOCATION: The location of the log bucket.
- FILTER: A filter that defines the log view. When empty, the log view includes all logs. For example, to filter by Compute Engine VM instances logs, enter
"resource.type=gce_instance"
. - DESCRIPTION: A description of the log view. For example, you might enter the following for the
description
"New description for the log view"
.
Execute the
gcloud logging views update
command:
Linux, macOS, or Cloud Shell
gcloud logging views update VIEW_ID --bucket=BUCKET_NAME --location=LOCATION --log-filter=FILTER --description=DESCRIPTION
Windows (PowerShell)
gcloud logging views update VIEW_ID --bucket=BUCKET_NAME --location=LOCATION --log-filter=FILTER --description=DESCRIPTION
Windows (cmd.exe)
gcloud logging views update VIEW_ID --bucket=BUCKET_NAME --location=LOCATION --log-filter=FILTER --description=DESCRIPTION
This command doesn't provide a response. To confirm the changes, you can run the
gcloud logging views describe
command.
Delete a log view
When you no longer need a log view that you created, you can delete it. However, before you delete a log view, we recommend that you verify that the log view isn't being referenced by another resource, such as a saved query.
You can't delete the _Default
log view on the _Default
log bucket.
To delete a log view, do the following:
Recommended: Review your Google Cloud project to ensure that the log view isn't being referenced. Consider examining the following:
- Queries run from the Logs Explorer or Log Analytics pages that were saved or shared.
- Custom dashboards.
Use the
gcloud logging views delete
command. If you don't know the view ID, then see List log views.Before using any of the command data below, make the following replacements:
- VIEW_ID: The identifier of the log view.
- BUCKET_NAME: The name of the log bucket.
- LOCATION: The location of the log bucket.
Execute the
gcloud logging views delete
command:Linux, macOS, or Cloud Shell
gcloud logging views delete VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
Windows (PowerShell)
gcloud logging views delete VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
Windows (cmd.exe)
gcloud logging views delete VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
The response confirms the deletion. For example, the following shows the response to deleting a log view named
tester
:Deleted [tester].
Describe a log view
To retrieve detailed information about a log view,
use the gcloud logging views describe
command.
If you don't know the view ID, then see List log views.
Before using any of the command data below, make the following replacements:
- VIEW_ID: The identifier of the log view.
- BUCKET_NAME: The name of the log bucket.
- LOCATION: The location of the log bucket.
Execute the
gcloud logging views describe
command:
Linux, macOS, or Cloud Shell
gcloud logging views describe VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
Windows (PowerShell)
gcloud logging views describe VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
Windows (cmd.exe)
gcloud logging views describe VIEW_ID --bucket=BUCKET_NAME --location=LOCATION
The response always includes the description and the fully-qualified name of the log view. It also includes the filter, when the filter field isn't empty. The following is a sample response:
createTime: '2024-02-20T17:41:17.405162921Z' filter: resource.type="gce_instance" name: projects/my-project/locations/global/buckets/my-bucket/views/compute updateTime: '2024-02-20T17:41:17.405162921Z'
View logs associated with a log view
To view logs in a log view, ensure you have the
Logs View Accessor (roles/logging.viewAccessor
)
role for the log view:
-
In the Google Cloud console, go to the Logs Explorer page:
If you use the search bar to find this page, then select the result whose subheading is Logging.
In the toolbar, click Refine scope, click Log view, and then select the log views.
For more information, see the Logs Explorer documentation.
What's next
To learn how to control access to specific fields in a log entry, see Configure field-level access.