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.
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.
You can create a maximum of 30 log views per log bucket.
Each log view contains a filter, which restricts the 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, view, update, and delete log views, ask your administrator to grant you the Logs Configuration Writer (
roles/logging.configWriter
) IAM role on project. For more information about granting roles, see Manage access.You might also be able to get the required permissions through custom roles or other predefined roles.
Install the Google Cloud CLI.
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. Principals with the role of
roles/logging.viewAccessor
can see the logs in any log view. However, Cloud Logging supports IAM conditions. Conditions let you grant a principal access to a specific log view. For more information, see Grant 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.
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
Grant access to a log view
Principals with the role of roles/logging.viewAccessor
on a
Google Cloud project can see the logs in any log view. However,
Cloud Logging supports
IAM conditions.
Conditions let you grant a principal access to a specific log view.
IAM conditions are specified in the role binding for a Google Cloud project. There is a limit of 20 role bindings in an allow policy that include the same role and the same principal, but different condition expressions.
To add users to a view to let them access the logs, complete the following steps.
gcloud
Get the project's IAM policy and write it to a local file in JSON format. Before you run the following command, replace PROJECT_ID with the ID of the project that contains the log bucket:
gcloud projects get-iam-policy PROJECT_ID --format json > output.json
Edit the JSON file that you created, and add an IAM condition that lets the user read from the log bucket you created.
For example, the following example specifies a binding that grants the role of
"roles/logging.viewAccessor"
to the specified members, but only for a single log view:{ "bindings": [ { "members": [ "user:username@gmail.com" ], "role": "roles/logging.viewAccessor", "condition": { "title": "Bucket reader condition example", "description": "Grants logging.viewAccessor role to user username@gmail.com for the VIEW_ID log view.", "expression": "resource.name == \"projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME/views/VIEW_ID\"" } } ], "etag": "BwWd_6eERR4=", "version": 3 }
Update the IAM policy:
gcloud projects set-iam-policy PROJECT_ID output.json
Console
In the project where you created the log bucket, do the following:
-
In the navigation panel of the Google Cloud console, select IAM:
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.
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
To delete a log view,
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 navigation panel of the Google Cloud console, select Logging, and then select Logs Explorer:
Click Refine scope to display the Refine scope panel. From here, you can select the log bucket and log view you want to use to view your logs.
For more information, see the Logs Explorer documentation.