This document helps you understand how Cloud Logging usesIdentity and Access Management (IAM) roles and permissions to control accessto Logging resources. Your IAM rolesdetermine whether you can perform actions like create log sinks orlog buckets, read log data stored in a log bucket, or access pages like theLogs Explorer. If you issue aLogging API orGoogle Cloud CLIcommand, then your IAM roles determine whether you havethe permission to run the command.

Overview

Your IAM roles determine what actions you can performwithin Logging. Arole is a collection ofpermissions. When you grant a role to a principal,you grant them all the permissions that the role contains. You can grantmultiple roles to the same principal.

IAM roles are granted on a resource, such as a Google Cloud project,folder, bucket, or organization. For example, you might grant a principal theLogs Viewer role (roles/logging.viewer) on a particular Google Cloud project.

ThePredefined roles andLogging roles sections of this page providecomprehensive information about Logging roles and permissions.Other sections of this page provide information about roles or permissionsfor specific use cases.

The remainder of this section summarizes how you can grant a principalaccess to log buckets or grant them access to only some of the log entriesin a log bucket. It also describes how you can restrict accessto someLogEntry fields.

Note:Log scopes aren't used for access control.A log scope is used to define what resources to search for log data.Your IAM roles on those resources determine whether you havethe permissions required to view the log data.

Grant access to log buckets

The Logs Viewer role (roles/logging.viewer) lets a principal access alllog data stored in the_Required and_Default log buckets, except fordata access logs. If a principal needs access to data access logs, thengrant the Private Logs Viewer role (roles/logging.privateLogViewer).

For custom log buckets, you can grant access to the_AllLogs view or toa custom log view. Logging automatically creates the_AllLogs view, which includes all log entries in the log bucket. To grantaccess to a log view, you add an IAM binding to theIAM policy attached to the log view or to the project. Tolearn more, seeControl access to a log view.

Logging also supports tags on log buckets, which can helpyou understand your costs. You can also use tags to prevent a user fromdeleting a log bucket. To learn more, seeUse tags to manage access to log buckets.

Grant access to some log entries in a log bucket

To grant a principal access to only some of the log entries stored in alog bucket, create a log view and then grant the principal access to thelog view. Forexample, you might create a log view on the_Default log bucket that onlyincludes log entries whose resource type is a Compute Engine instance.To learn more about creating log views and the different strategies that you canuse to grant access to the view, seeConfigure log views on a log bucket.

Restrict access to specificLogEntry fields

To restrict access to specific fields in theLogEntry datastructure, configure field-level access controls on the log bucket that storesyour data. For example, for your_Default log bucket, you can placea restriction on thejsonPayload of theLogEntry data structure,and then grant your administrators access to that field. To learn more,seeConfigure field-level access controls.

You can't restrict fields on a log bucket that has been upgraded to useLog Analytics. Similarly, if a log bucket contains a restricted field, then youcan't upgrade it to use Log Analytics.

Predefined roles

IAM provides predefined roles to grant granular access tospecific Google Cloud resources and prevent unwanted access to otherresources. Google Cloud creates and maintains these roles and automaticallyupdates their permissions as necessary, such as when Logging addsnew features.

The following table lists the predefined roles for Logging. Foreach role, the table displays the role title, description, containedpermissions, and the lowest-level resource type where the roles can be granted.You can grant the predefined roles at the Google Cloud project level or, inmost cases, any type higher in theresource hierarchy.To restrict the Logs View Accessor role to a log view on a bucket, useresource attributes for IAM Conditions.

To get a list of allindividual permissions contained in a role, seeGetting the role metadata.

Role	Permissions
Logging Admin (roles/logging.admin) Provides all permissions necessary to use all features of Cloud Logging. Lowest-level resources where you can grant this role: Project	logging.buckets.copyLogEntries logging.buckets.create logging.buckets.createTagBinding logging.buckets.delete logging.buckets.deleteTagBinding logging.buckets.get logging.buckets.list logging.buckets.listEffectiveTags logging.buckets.listTagBindings logging.buckets.undelete logging.buckets.update logging.exclusions.* logging.exclusions.create logging.exclusions.delete logging.exclusions.get logging.exclusions.list logging.exclusions.update logging.fields.access logging.links.* logging.links.create logging.links.delete logging.links.get logging.links.list logging.locations.* logging.locations.get logging.locations.list logging.logEntries.* logging.logEntries.create logging.logEntries.download logging.logEntries.list logging.logEntries.route logging.logMetrics.* logging.logMetrics.create logging.logMetrics.delete logging.logMetrics.get logging.logMetrics.list logging.logMetrics.update logging.logScopes.* logging.logScopes.create logging.logScopes.delete logging.logScopes.get logging.logScopes.list logging.logScopes.update logging.logServiceIndexes.list logging.logServices.list logging.logs.* logging.logs.delete logging.logs.list logging.notificationRules.* logging.notificationRules.create logging.notificationRules.delete logging.notificationRules.get logging.notificationRules.list logging.notificationRules.update logging.operations.* logging.operations.cancel logging.operations.get logging.operations.list logging.privateLogEntries.list logging.queries.* logging.queries.deleteShared logging.queries.getShared logging.queries.listShared logging.queries.share logging.queries.updateShared logging.queries.usePrivate logging.settings.* logging.settings.get logging.settings.update logging.sinks.* logging.sinks.create logging.sinks.delete logging.sinks.get logging.sinks.list logging.sinks.update logging.sqlAlerts.* logging.sqlAlerts.create logging.sqlAlerts.update logging.usage.get logging.views.* logging.views.access logging.views.create logging.views.delete logging.views.get logging.views.getIamPolicy logging.views.list logging.views.listLogs logging.views.listResourceKeys logging.views.listResourceValues logging.views.setIamPolicy logging.views.update observability.scopes.get resourcemanager.projects.get resourcemanager.projects.list
Logs Bucket Writer (roles/logging.bucketWriter) Ability to write logs to a log bucket. Lowest-level resources where you can grant this role: Project	logging.buckets.write
Logs Configuration Writer (roles/logging.configWriter) Provides permissions to read and write the configurations of logs-basedmetrics and sinks for exporting logs. Lowest-level resources where you can grant this role: Project	logging.buckets.create logging.buckets.createTagBinding logging.buckets.delete logging.buckets.deleteTagBinding logging.buckets.get logging.buckets.list logging.buckets.listEffectiveTags logging.buckets.listTagBindings logging.buckets.undelete logging.buckets.update logging.exclusions.* logging.exclusions.create logging.exclusions.delete logging.exclusions.get logging.exclusions.list logging.exclusions.update logging.links.* logging.links.create logging.links.delete logging.links.get logging.links.list logging.locations.* logging.locations.get logging.locations.list logging.logMetrics.* logging.logMetrics.create logging.logMetrics.delete logging.logMetrics.get logging.logMetrics.list logging.logMetrics.update logging.logScopes.* logging.logScopes.create logging.logScopes.delete logging.logScopes.get logging.logScopes.list logging.logScopes.update logging.logServiceIndexes.list logging.logServices.list logging.logs.list logging.notificationRules.* logging.notificationRules.create logging.notificationRules.delete logging.notificationRules.get logging.notificationRules.list logging.notificationRules.update logging.operations.* logging.operations.cancel logging.operations.get logging.operations.list logging.settings.* logging.settings.get logging.settings.update logging.sinks.* logging.sinks.create logging.sinks.delete logging.sinks.get logging.sinks.list logging.sinks.update logging.sqlAlerts.* logging.sqlAlerts.create logging.sqlAlerts.update logging.views.create logging.views.delete logging.views.get logging.views.getIamPolicy logging.views.list logging.views.update observability.scopes.get resourcemanager.projects.get resourcemanager.projects.list
Log Field Accessor (roles/logging.fieldAccessor) Ability to read restricted fields in a log bucket. Lowest-level resources where you can grant this role: Project	logging.fields.access
Log Link Accessor (roles/logging.linkViewer) Ability to see links for a bucket.	logging.links.get logging.links.list
Logs Writer (roles/logging.logWriter) Provides the permissions to write log entries. Lowest-level resources where you can grant this role: Project	logging.logEntries.create logging.logEntries.route
Private Logs Viewer (roles/logging.privateLogViewer) Provides permissions of the Logs Viewer role and in addition, providesread-only access to log entries in private logs. Lowest-level resources where you can grant this role: Project	logging.buckets.get logging.buckets.list logging.exclusions.get logging.exclusions.list logging.links.get logging.links.list logging.locations.* logging.locations.get logging.locations.list logging.logEntries.list logging.logMetrics.get logging.logMetrics.list logging.logServiceIndexes.list logging.logServices.list logging.logs.list logging.operations.get logging.operations.list logging.privateLogEntries.list logging.queries.getShared logging.queries.listShared logging.queries.usePrivate logging.sinks.get logging.sinks.list logging.usage.get logging.views.access logging.views.get logging.views.list observability.scopes.get resourcemanager.projects.get
Cloud Logging Service Agent (roles/logging.serviceAgent) Grants a Cloud Logging Service Account the ability to create and link datasets. Warning: Do not grant service agent roles to any principals exceptservice agents.	bigquery.datasets.create bigquery.datasets.get bigquery.datasets.link
SQL Alert WriterBeta (roles/logging.sqlAlertWriter) Ability to write SQL Alerts.	logging.sqlAlerts.* logging.sqlAlerts.create logging.sqlAlerts.update
Logs View Accessor (roles/logging.viewAccessor) Ability to read logs in a view. Lowest-level resources where you can grant this role: Project	logging.logEntries.download logging.views.access logging.views.listLogs logging.views.listResourceKeys logging.views.listResourceValues
Logs Viewer (roles/logging.viewer) Provides access to view logs. Lowest-level resources where you can grant this role: Project	logging.buckets.get logging.buckets.list logging.exclusions.get logging.exclusions.list logging.links.get logging.links.list logging.locations.* logging.locations.get logging.locations.list logging.logEntries.list logging.logMetrics.get logging.logMetrics.list logging.logScopes.get logging.logScopes.list logging.logServiceIndexes.list logging.logServices.list logging.logs.list logging.operations.get logging.operations.list logging.queries.getShared logging.queries.listShared logging.queries.usePrivate logging.sinks.get logging.sinks.list logging.usage.get logging.views.get logging.views.list observability.scopes.get resourcemanager.projects.get

The following sections provide additional information to help you decidewhichroles apply to your principals' use cases.

Logging roles

• To let a user perform all actions in Logging, grant theLogging Admin (roles/logging.admin) role.

• To let a user create and modify logging configurations,grant the Logs Configuration Writer (roles/logging.configWriter) role.This role lets you create or modify any of the following:

  • Log sinks
  • Log buckets
  • Log views
  • Linked data sets
  • Log scopes
  • Analytics views

  This role isn't sufficient to createlog-based metrics orlog-based alerting policies. For information about theroles required for these tasks, seePermissions for log-based metrics andPermissions for log-based alerting policies.

• To let a user read logs in the_Required and_Default bucketsor to use theLogs Explorer andLog Analytics pages,grant one of the following roles:

  • For access to all logs in the_Required bucket, and access to the_Default view on the_Default bucket, grant theLogs Viewer (roles/logging.viewer) role.
  • For access to all logs in the_Required and_Default buckets,including data access logs,grant the Private Logs Viewer (roles/logging.privateLogViewer) role.

• To let a user read logs in all log views that are in a project, grant themthe IAM role ofroles/logging.viewAccessor on the project.

• To let a user only read logs in a specific log view, you have two options:

  • Create an IAM policy for the log view, and then add anIAM binding to that policy which grants the principalaccess to the log view.

  • Grant the principal the IAM role ofroles/logging.viewAccessor on the project that contains the log view,but attach anIAM condition torestrict the grant to the specific log view.

  For information about creating log views and granting access, seeConfigure log views on a log bucket.

• To give a user access to restrictedLogEntry fields, if any,in a given log bucket, grant theLogs Field Accessor (roles/logging.fieldAccessor) role.For more information, seeConfigure field-level access.

• To let a user write logs by using the Logging API, grantthe Logs Writer (roles/logging.logWriter) role.This role doesn't grant viewing permissions.

• To let the service account of a sink route logs to a bucket in adifferent Google Cloud project, grant the service account theLogs Bucket Writer (roles/logging.bucketWriter) role.For instructions about granting permissions to a service account, seeSet destination permissions.

Project-level roles

Caution: The followingbasic rolesinclude thousands of permissions across all Google Cloud services. Use theseroles carefully, or consider using their corresponding Loggingpredefined roles.

• To give view access to most Google Cloud services,grant the Viewer (roles/viewer) role.

  This role includes all permissions granted by theLogs Viewer (roles/logging.viewer) role.

• To give editor access to most Google Cloud services,grant the Editor (roles/editor) role.

  This role includes all permissions granted by theLogs Viewer (roles/logging.viewer) role, and the permissions towrite log entries, delete logs, and create log-based metrics. However,this role doesn't let users createsinks, read Data Access audit logs that are in the_Default bucket,or read logs that are in user-defined log buckets.

• To give full access to most Google Cloud services,grant the Owner (roles/owner) role.

Granting roles

To learn how to grant a role to a principal, seeGranting, changing, and revoking access.

You can grant multiple roles to the same user. To get a list of the permissionscontained in a role, seeGetting the role metadata.

If you're trying to access a Google Cloud resource and lack the necessarypermissions, then contact the principal who is listed as theOwner for theresource.

Custom roles

To create a custom role with Logging permissions, do thefollowing:

• For a role granting permissions for the Logging API, choosepermissions fromAPI permissions, then follow theinstructions tocreate a custom role.

• For a role granting permissions to use the Logs Explorer, choose frompermission groups inConsole permissions, thenfollow the instructions tocreate a custom role.

• For a role granting permissions to usegcloud logging, see theCommand-line permissions section on this page, thenfollow the instructions tocreate a custom role.

For more information about custom roles, seeUnderstanding IAM custom roles.

Cloud Logging permissions

The following table is a partial list of the permissions needed for specificfeatures of Cloud Logging. This table can help you identify the permissionsthat you need to use pages like theLogs Explorer.

In the table,a.b.{x,y} meansa.b.x anda.b.y.

Console activity	Required permissions
Minimal read-only access	logging.logEntries.list logging.logs.list logging.logServiceIndexes.list logging.logServices.list resourcemanager.projects.get
View Data Access audit logs	logging.privateLogEntries.list
View log-based metrics	logging.logMetrics.{list, get}
View sinks	logging.sinks.{list, get}
View logs usage	logging.usage.get
Download logs	logging.logEntries.{list, download} Only one of these permissions is necessary to download logs. Roles containing the permissions to download logs must be granted at a project-level. You can't download logs if a role containing these permissions is granted in the IAM policy file of a log view.
List and view log scopes	logging.logScopes.{get, list}
View the default log scope	observability.scopes.get
Exclude logs	logging.exclusions.{list, create, get, update, delete} When creating a custom role that includes permissions to manage exclusion filters, add thelogging.sinks.* permissions to the role instead of adding thelogging.exclusions.* permissions.
Create and use sinks	logging.sinks.{list, create, get, update, delete} When creating a sink, you must also grant the service account an IAM role that lets it write log entries to the destination. For more information, see Set destination permissions. After your log entries have been routed to a supported destination, access to the log entries is controlled entirely by IAM permissions and roles on the destination.
Create log-based alerts	SeeRoles required to create and use log-based alerting policies.
Create log-based metrics	logging.logMetrics.{list, create, get, update, delete} For information about other IAM roles that you need to create and use log-based metrics, seeRoles required to create and use log-based metrics.
Save and use private queries	logging.queries.usePrivate logging.queries.{listShared,getShared}
Save and use shared queries	logging.queries.{share, getShared, updateShared, deleteShared, listShared}
Use recent queries	logging.queries.{create, list}
Create and manage log scopes	logging.logScopes.{create, delete, get, list, update}
Set and manage the default log scope	observability.scopes.{get, update}
Create and manage analytics views	observability.analyticsViews.{create, delete, get, list, update}
Create and manage linked datasets	logging.links.{create, delete, get, list} You might need additional IAM roles to query the linked dataset. For example, these permissions don't grant you access to the BigQuery interface. For more information, seeBigQuery: Access control with IAM.

Permissions for the command-line

gcloud logging commands arecontrolled by IAM permissions.

To use any of thegcloud logging commands, principals must have theserviceusage.services.use permission.

A principal must also have the IAM role that corresponds to thelog's resource, and to the use case. For details, seecommand-line interface permissions.

Roles required to create and use log-based metrics

Following is a summary of the common roles and permissions that a principalneeds to access log-based metrics:

• TheLogs Configuration Writer(roles/logging.configWriter) role lets principals list, create, get,update, and delete log-based metrics.

• TheLogs Viewer (roles/logging.viewer) rolecontains permissions to view existing metrics. Specifically, a principalneeds thelogging.logMetrics.get andlogging.logMetrics.list permissionsto view existing metrics.

• TheMonitoring Viewer(roles/monitoring.viewer) role contains the permissions to readTimeSeries data. Specifically, a principal needs themonitoring.timeSeries.list permission to read time series data.

• TheLogging Admin (roles/logging.admin),Project Editor (roles/editor), andProject Owner (roles/owner) rolescontain the permissions to create log-based metrics. Specifically, aprincipal needs thelogging.logMetrics.create permission to createlog-based metrics.

Note: To secure private logs data, such as Data Access audit logs andAccess Transparency audit logs, from unauthorized access, ensure that principals aregranted the minimal permissions they need to do their jobs. For example,principals that have theProject Editor(roles/editor) role can create log-based metrics with labels that can extractsensitive information.

Roles required to create and use log-based alerting policies

To create and manage log-based alerting policies, a principal needs thefollowing Logging and Monitoring roles andpermissions:

• To get the permissions that you need to create log-based alerting policies in Monitoring and to create the associated Loggingnotification rules, ask your administrator to grant you the following IAM roles on your project:

  • Monitoring AlertPolicy Editor (roles/monitoring.alertPolicyEditor)
  • Logs Configuration Writer (roles/logging.configWriter)

  For more information about granting roles, seeManage access to projects, folders, and organizations.

  These predefined roles contain the permissions required to create log-based alerting policies in Monitoring and to create the associated Loggingnotification rules. To see the exact permissions that are required, expand theRequired permissions section:

  Required permissions

  The following permissions are required to create log-based alerting policies in Monitoring and to create the associated Loggingnotification rules:

  • monitoring.alertPolicies.create
  • logging.notificationRules.create

  You might also be able to get these permissions withcustom roles or otherpredefined roles.

If you create your alerting policy in the Google Cloud CLI, then the followingrole or permission is also required:

• To get the permission that you need to create an alerting policy by using the Google Cloud CLI, ask your administrator to grant you theService Usage Consumer (roles/serviceusage.serviceUsageConsumer) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.

  This predefined role contains the serviceusage.services.use permission, which is required to create an alerting policy by using the Google Cloud CLI.

  You might also be able to get this permission withcustom roles or otherpredefined roles.

If your Google Cloud project already has notification channels, then you canconfigure your alerting policy to use an existing channel without anyadditional roles or permissions.However, if you need tocreate a notification channel foryour log-based alerting policy, then the following role or permission isrequired:

• To get the permission that you need to create a notification channel for a log-based alerting policy, ask your administrator to grant you theMonitoring NotificationChannel Editor (roles/monitoring.notificationChannelEditor) IAM role on your project.

  This predefined role contains the monitoring.notificationChannels.create permission, which is required to create a notification channel for a log-based alerting policy.

Permissions for SQL-based alerting policies

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

SQL-based alerting policies evaluate the results of a SQL query run againstdata from groups of log entries. For information about the roles required tocreate and manage SQL-based alerting policies,see theBefore you begin section inMonitor your SQL query results with an alerting policy.

Logging access scopes

Access scopes are thelegacy method of specifying permissions for the service accounts on yourCompute Engine VM instances.

The following access scopes apply to the Logging API:

Access scope	Permissions granted
https://www.googleapis.com/auth/logging.read	roles/logging.viewer
https://www.googleapis.com/auth/logging.write	roles/logging.logWriter
https://www.googleapis.com/auth/logging.admin	Full access to the Logging API.
https://www.googleapis.com/auth/cloud-platform	Full access to the Logging API and to all other enabled Google Cloud APIs.

For information on using this legacy method to set your service accounts' levelsof access, seeAccess scopes.