TheGoogle Cloud CLI has a group of commands,gcloud logging,thatprovide a command-line interface to the Logging API. A summary of theimportant commands and examples of their use are shown on this page.

For additional information, go to the following sources:

• For detailed documentation on the Logging Google Cloud CLI,read the reference pages for thegcloud logging command group. There mightalso be new or changed commands in the beta command group:gcloud beta logging.
• For documentation on the Logging API, readCloud Logging API.

Getting started

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud 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.

2. Set your default project so you don't have to supply the--project flag with each command:

   gcloud config set projectPROJECT_ID

After you've installed and initialized the Google Cloud CLI, you can rungcloud logging commands from the command line in the same way you use othercommand-line tools.

Permissions

gcloud logging commands are controlled by Identity and Access Management (IAM)permissions.

To use any of thegcloud logging commands, you must have theserviceusage.services.use permission. You must also have theIAM role that corresponds to the log's location, and to youruse case:

For additional information on required Logging IAMroles and permissions, go toAccess control.

Summary of commands

The following sections provide summaries and examples of the gcloud CLIcommand-line interface for Logging. However, some command optionsand details are omitted; the online documentation for the gcloud CLIcommands is authoritative.

From the command line, you can add--help to a partial command to get moredetails. For example:

gcloud logging --helpgcloud logging sinks --helpgcloud logging sinks create --help

In a few cases, important command features in the Beta version of thegcloud CLI are available:

gcloud beta logging metrics create --help

Over time, Beta features might be rolled into the standard release and newfeatures might be added to the Beta release.

Log entries

You can write and readlog entries usinggcloud.

Writing log entries

Use thegcloud logging write command,corresponding to the API methodentries.write.

gcloud logging writeLOG_NAME  ...

LOG_NAME can either be theLOG_ID or the full resource name of thelog with theLOG_ID URL-encoded.

For simplicity, this command makes several assumptions aboutthelog entry. For example, it always sets theresource type toglobal.

Examples

Write a log entry to logmy-test-log in the current project with a plain-textpayload and a severity ofERROR:

gcloudloggingwritemy-test-log"A simple entry"--severity=ERROR

Write a log entry with a structured (JSON) payload:

gcloudloggingwritemy-test-log'{ "message": "My second entry", "weather": "partly cloudy"}'--payload-type=json

Write a log entry to a folder, billing account, or organization. The followingcommand writes a log entry to a folder:

gcloud logging write my-folder-log "A folder log entry"  --folder=FOLDER_ID

To find your log entries, look in theLogs Explorer under theGlobal resource type.

You can alsogcloud logging read or the corresponding API method. See theexample inReading log entries.

Reading log entries

To retrieve log entries, use thegcloud logging read command, correspondingto the API methodentries.list:

gcloud logging readFILTER ...

To read log entries in folders, billing accounts, or organizations,append the--folder,--billing-account, or--organization options.

Examples

Read up to 10 log entries in your project'ssyslog log from Compute Engineinstances containing payloads that include the wordSyncAddress. The logentries are to be shown in JSON format:

gcloudloggingread"resource.type=gce_instance AND logName=projects/PROJECT_ID/logs/syslog AND textPayload:SyncAddress"--limit10--formatjson

Following is an example of one returned log entry:

{"insertId":"2024-04-07|08:56:48.137651-07|10.162.32.129|-1509625619","logName":"projects/[PROJECT_ID]/logs/syslog","resource":{"labels":{"instance_id":"15543007601548829999","zone":"global"},"type":"gce_instance"},"textPayload":"Apr  7 15:56:47 my-gce-instance google-address-manager: ERROR SyncAddresses exception: HTTP Error 503: Service Unavailable","timestamp":"2024-04-07T15:56:47.000Z"}

To list logs in a folder, add the--folder flag. That flag restricts the logentries read to only those in the folder itself. The same applies to the--organization and--billing-account flags. The following command retrievesactivity-type audit logs from a folder. Log entries are to be shown in thedefault YAML format:

gcloudloggingread"resource.type=folder AND logName:cloudaudit.googleapis.com%2Factivity"--folder=FOLDER_ID

Following is an excerpt of one returned entry. It records a call toSetIamPolicy on the folder:

insertId:mhcr1tc16ulogName:folders/FOLDER_ID/logs/cloudaudit.googleapis.com%2FactivityprotoPayload:'@type':type.googleapis.com/google.cloud.audit.AuditLogmethodName:SetIamPolicy...serviceName:cloudresourcemanager.googleapis.comstatus:{}resource:labels:folder_id:'FOLDER_ID'type:folderseverity:NOTICEtimestamp:'2024-03-19T16:26:49.308Z'

The previous section,Writing log entries, contains an exampleof writing a log entry to a folder. Following is the command to read the logentry:

gcloudloggingread"resource.type=global"--folder=FOLDER_ID--limit=1

Here is the result:

insertId:1f22es3frcguajlogName:folders/FOLDER_ID/logs/my-folder-logreceiveTimestamp:'2024-03-19T18:20:19.306598482Z'resource:type:globaltextPayload:Afolderlogentrytimestamp:'2024-03-19T18:20:19.306598482Z'

Logs

A log, or log stream, is the set of log entries that have the same full resourcename. The full resource name is equivalent to theLogName field in theLogEntry.

The full resource name for a log must be one of the following:

projects/PROJECT_ID/logs/LOG_IDorganizations/ORGANIZATION_ID/logs/LOG_IDfolders/FOLDER_ID/logs/LOG_IDbillingAccounts/BILLING_ACCOUNT_ID/logs/LOG_ID

LOG_ID can only contain alphanumeric characters, forward-slash,underscore, hyphen, and period characters. For example,compute.googleapis.com/activity_log is a validLOG_ID. The full resourcename includes the project, folder, billing account, or organization in which thelog is located. For more information, go toGoogle Cloud resource hierarchy.

To manage logs, use thegcloud logging logs command group:

gcloud logging logs list  ...gcloud logging logs delete  ...

URL Encoding

When passing the full resource name of a log to agcloud logging command,you must URL-encode theLOG_ID. As an example, aLOG_ID ofcompute.googleapis.com/activity_log encodes tocompute.googleapis.com%2Factivity_log.

When passing theLOG_ID to agcloud logging command, you don't need toURL-encode theLOG_ID. In this case, thegcloud command encodes for you.

When receiving data that includes the full resource name of a log from agcloud logging command, theLOG_ID is URL-encoded.

Creating logs

You create a log by writing a log entry to it. SeeWriting log entries.

Listing log names

Use thegcloud logging logs listcommand. It executes the API methodprojects.logs/list.

Only logs that contain log entries are displayed. The display lists fullresource names of logs with theLOG_ID URL-encoded.

You can only usegcloud logging logs list to list logs in projects; you can'tuse it to list logs in folders, billing accounts, or organizations.

Example

List the logs in the current project:

gcloud logging logs list

Sample result:

NAMEprojects/my-gcp-project-id/logs/apache-errorprojects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivityprojects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Fdata_accessprojects/my-gcp-project-id/logs/compute.googleapis.com%2Factivity_logprojects/my-gcp-project-id/logs/compute.googleapis.com%2Fsystem_logprojects/my-gcp-project-id/logs/syslog

Deleting logs

To delete logs, use thegcloud logging logs deletecommand. It decides, based on the full resource name of a log,which of the followingdelete API commands to execute:projects.logs,organizations.logs,folders.logs,orbillingAccounts.logs.

Example: Delete a project log

To delete a log that exists in the current project using theLOG_ID:

gcloud logging logs delete my-new-log

Really delete all log entries from[my-new-log]?g_logsDo you want to continue (Y/n)?  YDeleted [my-new-log].

An alternative is to specify the full resource name of a log with theLOG_ID URL-encoded:

gcloud logging logs delete projects/my-gcp-project-id/logs/compute.googleapis.com%2Factivity_log

Really delete all log entries from[projects/my-gcp-project-id/logs/compute.googleapis.com%2Factivity_log]?Do you want to continue (Y/n)?  YDeleted [projects/pamstestproject1/logs/compute.googleapis.com%2Factivity_log].

Example: Delete logs in folders, billing accounts or organizations

To delete a log contained in folders, billing accounts or organizations, passthe full resource name with theLOG_ID URL-encoded. For example, thefollowing command deletes a log in a folder:

gcloud logging logs delete folders/FOLDER_ID/logs/my-folder-log

FOLDER_ID must be the unique number that identifies the folder.

Live tailing log entries

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.

Live tailing lets you view your log entries in real time as Cloud Loggingwrites them, by using either the Google Cloud CLI or the Cloud Logging API.

Live tailing isn't supported for log buckets withfield-level access controls, however youcanstream logs forthose buckets in the Logs Explorer.

For information on the API method for live tailing, seetheentries.tail method.

Installinggcloud alpha logging tail

To usegcloud alpha logging tail, you need to have Python 3 andthegrpcio Python package installed.

For instructions on how toinstall Python, see thePython page.For instructions on how to install the Python package manager,pip, that isneeded to install thegrpcio package, seeThe Python Package Installer page.

Complete the following steps to installgcloud alpha logging tail:

1. Verify that you have the Google Cloud CLI installed. For instructions on howto install the Google Cloud CLI, seeInstalling Google Cloud CLI.

2. Verify that you're using version 302.0.0 or greater of thegcloud CLI.

   gcloud version

   For instructions on updating the gcloud CLI, seegcloud components update.

3. Install the gcloud CLI alpha components:

   gcloud components install alpha

4. For MacOS, Linux, and Cloud Shell users:

   1. Install gRPC client libraries:

       sudo pip3 install grpcio

   2. Set the environment variableCLOUDSDK_PYTHON_SITEPACKAGES to any value:

      exportCLOUDSDK_PYTHON_SITEPACKAGES=1

      Note: By default, the Google Cloud CLI ignores Python libraries installedon your local system. To allow the Google Cloud CLI to use thegrpciolibrary, you need to enable site packages. To enable site packages,set theCLOUDSDK_PYTHON_SITEPACKAGES environment variable to1.With site packages enabled, the gcloud CLI can use extralibraries outside of thegoogle-cloud-sdk/lib directory.

5. Use the following commands to set your Google Cloud project ID and toauthenticate:

   gcloud config set projectPROJECT_IDgcloud auth login

   To get the project ID, seeCreating and managingprojects.

6. Verify thatgcloud alpha logging tail is installed by running the followingcommand:

   gcloud alpha logging tail

   The command displays the following message:

   Initializing tail session.

   You are now viewing the log entries for your Google Cloud project as Loggingwrites them.

   

For more information on using live tailing, see thegcloud alpha logging tail reference guide.

Buffering and ordering

Because Logging can receive log entries out of chronologicalorder, live tailing provides a buffer-window setting so you can balancethe tradeoff between viewing the log entries as they are being written andviewing them in ascending order. You can set the buffer windowbetween0 and60 seconds.

Note the following characteristics of the buffer window:

• The default buffer window is two seconds.

• Logging delays writing the log entries to log buckets for theduration of the buffer window.

• If a log entry is written outside of the buffer window, thenLogging returns the log entries as they are received.

When configuring the buffer window, you make a tradeoff betweenviewing logs as they are written and viewing the entries out of order.

Limits and quotas

The following table lists the limits and quotas for live tailing:

Client limitations

For a Google Cloud project that writes lots of entries quickly, your clientmight be unable to consume them as quickly as they're being written. Inthis case, Logging limits the total number of entries sent,prioritizing the most recent entries. At the end of the tail session,Logging returns the number of entries that were not displayeddue to the limits of the client.

Resource descriptors

All log entries contain an instance of one of a fixed set of monitored resourcetypes that generally identifies the resource the log entry comes from, such as aparticular Compute Engine VM instance. For a list of monitored resourcetypes, go toMonitored Resource List.

To list the current resource descriptor types, use thegcloud logging resource-descriptors listcommand, corresponding to the API methodmonitoredResourceDescriptors.list.You don't need any special permissions to list the resource types.

Examples

List all the resource types that haveinstance in their names:

gcloudloggingresource-descriptorslist--filter="type:instance"

Result:

TYPEDESCRIPTIONKEYgce_instanceAvirtualmachineinstancehostedinComputeEngine.project_id,instance_id,zonespanner_instanceACloudSpannerinstance.project_id,instance_id,location,instance_configredis_instanceARedisinstancehostedonGoogleCloudMemoryStore.project_id,region,instance_id,node_idgce_instance_groupAComputeEngineinstancegroupresource.project_id,instance_group_id,instance_group_name,locationgce_instance_group_managerAComputeEngineinstancegroupmanagerresource.project_id,instance_group_manager_id,instance_group_manager_name,locationgce_instance_templateAComputeEngineinstancetemplateresource.project_id,instance_template_id,instance_template_name

Routing logs

You route logs by creatingsinks that send certain log entries tosupported destinations. For more information about sinks, seeRouting and storage overview: Sinks.

Use thegcloud logging sinks command group,corresponding to the API methodsprojects.sinks,folders.sinks,billingAccounts.sinks,andorganizations.sinks.

Sinks can be located wherever logs are located: projects, folders, billingaccounts, and organizations. Use thegcloud logging flags--folder,--billing-account, or--organization to refer to those locations.Omitting them defaults to the project specified by--project orthe current project.

Creating sinks

Use thegcloud logging sinks createcommand, corresponding to the API methodprojects.sinks.create:

gcloud logging sinks createSINK_NAMESINK_DESTINATION  --log-filter="..." ...

Destination authorization. To determine the writer identity service accountfor your new sink, use thedescribe command in the next section to fetch thenew sink's properties. You need the service account to authorize the sink towrite to its destination. Thegcloud logging command doesn't perform theauthorization for you, as the Logs Explorer does. For more information,seeDestination permissions.

Aggregated sinks. You can use one of the--folder,--billing-account, and--organization flags if you want to route the logsfrom that resource. You have the following options:

• By default, using the previous flags restricts the sink to routing onlythe logs held in the named folder, organization, or billing account.
• If you additionally add the--include-children flag, then the sink becomesanaggregated sink and the sink routes logs from all folders andprojects contained within the named resource, subject to the filter in the--log-filter flag.
• Billing accounts don't contain folders or projects, so--include-childrenhas no effect with--billing-account.

For more information, seeAggregated sinks overview.

Examples

Create a sink,syslog-errors, in the current project that routessyslogentries with severity ERROR from Compute Engine VM instances. Thedestination is an existing Cloud Storage bucket in the current project:

gcloudloggingsinkscreatesyslog-errors\storage.googleapis.com/my-third-gcs-bucket\--log-filter"resource.type=gce_instance AND logName=projects/PROJECT_ID/logs/compute.googleapis.com%2Fsyslog AND severity=ERROR"

Create a sink,syslog-sink, in the current project that routes allsyslogentries with severityWARNING or higher. The destination is a newPub/Sub topic in the current project, and the sink service account,shown in the output of thelogging sinks create command, is granted anIAM role that lets the service account publish content to thetopic.

gcloud pubsub topics create syslog-sink-topicgcloud logging sinks create syslog-sink pubsub.googleapis.com/projects/MY-PROJECT/topics/syslog-sink-topic \     --log-filter="severity>=WARNING"gcloud pubsub topics add-iam-policy-binding syslog-sink-topic \     --member serviceAccount:LOG-SINK-SERVICE-ACCOUNT --role roles/pubsub.publisher

Create a sink,folder-logs in a folderFOLDER_ID that routes the AdminActivity audit logs from the folder. The destination is an existingCloud Storage bucket in the current project.

gcloud logging sinks create folder-logs  \    storage.googleapis.com/my-folder-bucket \    --folder=FOLDER_ID --log-filter="logName:logs/cloudaudit.googleapis.com%2Factivity"

The following command creates an aggregated sink, routing all Admin Activityaudit logs from a folderand from all folders and projects contained in thefolder:

gcloud logging sinks create folder-logs  --include-children \    storage.googleapis.com/my-folder-bucket \    --folder=FOLDER_ID --log-filter="logName:logs/cloudaudit.googleapis.com%2Factivity"

Listing or describing sinks

Use thegcloud logging sinks listorgcloud logging sinks describe commands,corresponding to the API methodsprojects.sinks.listandprojects.sinks.get,respectively:

gcloud logging sinks listgcloud logging sinks describeSINK_NAME

Examples

List sinks in the current project:

gcloud logging sinks listNAME                            DESTINATION                                                                   FILTERgoogle-sink-1481139614360-9906  storage.googleapis.com/my-second-gcs-bucket                                   logName = "projects/my-gcp-project-id/logs/syslog"pubsub-logs-sink                pubsub.googleapis.com/projects/my-gcp-project-id/topics/my-pubsub-logs-topic  logName = "projects/my-gcp-project-id/logs/pubsubtestlog"test-sink-v4                    storage.googleapis.com/my-gcs-bucket                                          severity=CRITICAL

List sinks in a folder:

gcloud logging sinks list --folder=FOLDER_IDNAME         DESTINATION                               FILTERfolder-logs  storage.googleapis.com/my-folder-bucket   logName:activity

List sinks in an organization:

gcloud logging sinks list --organization=ORGANIZATION_IDNAME               DESTINATION                            FILTERorganization-logs  storage.googleapis.com/my-org-bucket   logName:activity

Describe sinks in the current projecttest-sink-v4:

gcloud logging sinks describe test-sink-v4

Output:

destination:storage.googleapis.com/my-gcs-bucketfilter:severity=CRITICALname:test-sink-v4outputVersionFormat:V2writerIdentity:serviceAccount:test-sink-v4@logging-PROJECT_ID.iam.gserviceaccount.com

Describe sinks in a folder:

gcloud logging sinks describe test-sink-v4 --folder=FOLDER_ID

Output:

destination:storage.googleapis.com/my-gcs-bucketfilter:severity=CRITICALname:test-sink-v4

Describe sinks in an organization:

gcloud logging sinks describe test-sink-v4 --organization=ORGANIZATION_ID

Output:

createTime:[TIMESTAMP]description:TestSinkdestination:storage.googleapis.com/my-gcs-bucketfilter:severity=CRITICALname:test-sink-v4updateTime:[TIMESTAMP]writerIdentity:serviceAccount:test-sink-v4@logging-PROJECT_ID.iam.gserviceaccount.com

Updating sinks

Use thegcloud logging sinks updatecommand, corresponding to the API methodprojects.sink.update:

You can update a sink to change the destination or the query:

gcloud logging sinks updateSINK_NAMENEW_DESTINATION  --log-filter=NEW_FILTER

You can omit theNEW_DESTINATION or--log-filter if those parts don't change.

Examples

Update the destination of a project sink:

gcloud logging sinks updatePROJECT_ID storage.googleapis.com/my-second-gcs-bucket

Deleting sinks

Use thegcloud logging sinks delete command,corresponding to the API methodprojects.sinks.delete:You stop routing its log entries when you delete a sink:

gcloud logging sinks deleteSINK_NAME

Examples

Delete sinksyslog-sink-1 in the current project:

gcloud logging sinks delete syslog-sink-1

Log-based metrics

To manage log-based metrics, use thegcloud logging metrics command group,corresponding to the API methods atprojects.metrics.

Log-based metrics are located only in projects.

Creating basic metrics

Use thegcloud logging metrics createcommand, corresponding to the API methodprojects.metrics.create:

gcloud logging metrics createMETRIC_NAME  --description=... --log-filter=...

For more complex counter metrics with labels, use thecreate command asdescribed in the sectionCreating advanced metrics.

Examples

Create a log-based metric that counts the number of log entrieswith severity of at leastERROR from Compute Engine instances:

gcloudloggingmetricscreateerror_count\--description="Syslog error counts."\--log-filter="resource.type=gce_instance AND severity>=ERROR"

Creating advanced metrics

To create complex metrics with labels, including distribution metrics,use thegcloud logging metrics createcommand, corresponding to the API methodprojects.metrics.create:

gcloud logging metrics createMETRIC_NAME  --config-from-file=FILE_NAME

FILE_NAME is the path to a file containing a YAML (or JSON) specification of aLogMetric object.

Examples

Create a distribution metric to record request latencies:

gcloud logging metrics create my-distribution-metric --config-from-file=logmetric.dat

wherelogmetric.dat contains the following:

bucketOptions:exponentialBuckets:growthFactor:2.0numFiniteBuckets:64scale:0.01description:AppEngineRequestLatencyfilter:|resource.type="gae_app"logName="projects/PROJECT_ID/logs/appengine.googleapis.com%2Fnginx.request"labelExtractors:path:EXTRACT(httpRequest.requestUrl)metricDescriptor:labels:-description:HTTPPathkey:pathmetricKind:DELTAname:projects/PROJECT_ID/metricDescriptors/logging.googleapis.com/user/my-distribution-metrictype:logging.googleapis.com/user/my-distribution-metricvalueType:DISTRIBUTIONname:my-distribution-metricvalueExtractor:EXTRACT(jsonPayload.latencySeconds)

Result:

Created [my-distribution-metric].

Updating metrics

Usegcloud logging metrics update,corresponding to the API methodprojects.metrics.update:

gcloud logging metrics updateMETRIC_NAME ...

To change the query, use--log-filter. To change the description, use--description. To change more items, use--config-from-file.

Examples

Change the query inmy-distribution-metric:

gcloudloggingmetricsupdatemy-distribution-metric--log-filter="[NEW_LOG_FILTER]"

Listing and describing metrics

Usegcloud logging metrics list,corresponding to the API methodprojects.metrics.list,andgcloud logging metrics describe,corresponding to the API methodprojects.metrics.get:

gcloud logging metrics list ...gcloud logging metrics describeMETRIC_NAME

Themetrics list command by defaults shows the full description of everylisted metric. Use the--format flag to control how much information islisted.

Examples

List the distribution-type logging metrics in the current project. Show only themetric name and its description:

gcloud logging metrics list --filter="metricDescriptor.valueType=DISTRIBUTION" --format="table(name,description)"

Result:

NAME                       DESCRIPTIONmyapp/request_latency      Request latency for myappbigquery_billed_bytes      Billed Bytesfood_latency               How long does it take to service all food requestshealthz_latencies          /healthz latencies in microsecondslatency_on_food            Tracking latency on food requestslines_writtenmy_latency_metricno-match-dist-metricpizza_latency              How long does it take to service pizza requests?

Describe a user-defined distribution metric namedmyapp/request_latency. Showthe information in the default YAML format:

gcloud logging metrics describe "myapp/request_latency"

Result:

bucketOptions:exponentialBuckets:growthFactor:2.0numFiniteBuckets:64scale:0.01description:Requestlatencyformyappfilter:|resource.type="gae_app"logName="projects/[PROJECT_ID]/logs/appengine.googleapis.com%2Fnginx.request"labelExtractors:path:EXTRACT(httpRequest.requestUrl)metricDescriptor:description:Requestlatencyformyapplabels:-description:HTTPPathkey:pathmetricKind:DELTAname:projects/[PROJECT_ID]/metricDescriptors/logging.googleapis.com/user/myapp/request_latencytype:logging.googleapis.com/user/myapp/request_latencyvalueType:DISTRIBUTIONname:myapp/request_latencyvalueExtractor:EXTRACT(jsonPayload.latencySeconds)

Deleting metrics

Use thegcloud logging metrics deletecommand, corresponding to the API methodprojects.metrics.delete:

gcloud logging metrics deleteMETRIC_NAME

Examples

Delete the metricmy-distribution-metric from the current project:

gcloud logging metrics delete "my-distribution-metric"

Result:

Really delete metric [my-distribution-metric]?Do you want to continue (Y/n)?  YDeleted [my-distribution-metric].