Command Line Interface

The Google Cloud SDK has a group of commands, gcloud logging, that provide a command-line interface to the Stackdriver Logging API. A summary of each of the commands and examples of their use are shown on this page.

For additional information, see the following sources:

  • For detailed documentation on the Stackdriver Logging command-line interface, see the SDK's reference pages for the gcloud logging command group. There might also be new or changed commands in the beta command group: gcloud beta logging.
  • For documentation on the Stackdriver Logging API, see Stackdriver Logging API.
  • For information on required Stackdriver Logging IAM roles and permissions, see Access Control.
  • For more information on Stackdriver Logging, see Stackdriver Logging.

Getting started

  1. Install and initialize the Cloud SDK.

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

    gcloud config set project [PROJECT_ID]
    

For more information, see the Getting Started section of the Logs Viewer.

Summary of commands

The following sections provide summaries and examples of the Cloud SDK command-line interface for Stackdriver Logging. However, some command options and details are omitted.

The online documentation for the Cloud SDK commands is authoritative. From the command line, you can add --help to a partial command to get more details. For example:

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

In a few cases, you will find important command features in the beta version of the SDK:

gcloud beta logging metrics create --help

Over time, beta features might be rolled into the standard release and new features might be added to the beta release.

Logs

A log, or log stream, is the set of log entries that have the same logName property. Logs are located in projects, folders, billing accounts, and organizations. Log names include the project, folder, billing account, or organization in which the log is located. For more information, see GCP Resource Hierarchy.

To manage logs, use the gcloud logging logs command group, corresponding to the API methods in projects.logs, folders.logs, billingAccounts.logs, and organizations.logs:

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

Creating logs

You create a log by writing a log entry to it. See Writing log entries.

Listing logs

Use the gcloud logging logs list command, corresponding to the API method projects.logs/list. You must have at least the Logging/Logs Viewer IAM role where the logs are located.

Only logs that contain log entries are displayed.

You cannot use gcloud logging logs list to list logs in folders, billing accounts, or organizations.

Example

List the log names in the current project:

gcloud logging logs list

Sample result:

NAME
projects/my-gcp-project-id/logs/apache-error
projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity
projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Fdata_access
projects/my-gcp-project-id/logs/compute.googleapis.com%2Factivity_log
projects/my-gcp-project-id/logs/compute.googleapis.com%2Fsystem_log
projects/my-gcp-project-id/logs/syslog

For more information on the format of log names, see the logName property in log entries.

Deleting logs

Use the gcloud logging logs delete command, corresponding to the API method projects.logs/delete You must have the Logging/Logging Admin IAM role where the log is located:

gcloud logging logs delete LOG_NAME

The command deletes all the log entries with the specified log name.

Examples

Delete a log in the current project:

gcloud logging logs delete my-new-log

Result:

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

You can also delete logs in folders, billing accounts, and organizations. For example, the following 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.

Log entries

You can write and read log entries using gcloud.

Writing log entries

Use the gcloud logging write command, corresponding to the API method entries.write. You must have at least the Logging/Logs Writer IAM role where the log entries are located:

gcloud logging write  LOG_NAME  PAYLOAD ...

For simplicity, this command makes several assumptions about the log entry. For instance, it always sets the resource type to global.

Examples

Write a log entry to log my-test-log in the current project with a plain-text payload and a severity of ERROR:

gcloud logging write my-test-log "A simple entry" --severity=ERROR

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

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

To find your log entries in a project, look in the Logs Viewer under the Global resource type for the log messages.

Custom log entries

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

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

You cannot see folder, organization, or billing account logs in the Logs Viewer. You can use gcloud logging read or the corresponding API method. To read back the log entry written by the previous command, see the example in Reading log entries.

Reading log entries

To retrieve log entries, use the gcloud logging read command, corresponding to the API method entries.list. You must have at least the Logging/Logs Viewer IAM role where the log entries are located. Reading data access audit logs requires at least the Logging/Private Logs Viewer role:

gcloud logging read FILTER ...

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

For more information about filters, see Advanced Logs Filters.

Examples

Read up to 10 log entries in your project's syslog log from Compute Engine instances containing payloads that include the word SyncAddress. The log entries are to be shown in JSON format:

gcloud logging read "resource.type=gce_instance AND logName=projects/[PROJECT_ID]/logs/syslog AND textPayload:SyncAddress" --limit 10 --format json

Following is an example of one returned log entry:

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

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

gcloud logging read "resource.type=folder AND logName:cloudaudit.googleapis.com%2Factivity" --folder=[FOLDER_ID]

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

insertId: mhcr1tc16u
logName: folders/[FOLDER_ID]/logs/cloudaudit.googleapis.com%2Factivity
protoPayload:
  '@type': type.googleapis.com/google.cloud.audit.AuditLog
  methodName: SetIamPolicy
  ...
  serviceName: cloudresourcemanager.googleapis.com
  status: {}
resource:
  labels:
    folder_id: '[FOLDER_ID]'
  type: folder
severity: NOTICE
timestamp: '2018-03-19T16:26:49.308Z'

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

gcloud logging read "resource.type=global" --folder=[FOLDER_ID] --limit=1

Here is the result:

insertId: 1f22es3frcguaj
logName: folders/[FOLDER_ID]/logs/my-folder-log
receiveTimestamp: '2018-03-19T18:20:19.306598482Z'
resource:
  type: global
textPayload: A folder log entry
timestamp: '2018-03-19T18:20:19.306598482Z'

Resource descriptors

All log entries contain an instance of one of a fixed set of monitored resource types that generally identifies the resource the log entry comes from, such as a particular Compute Engine VM instance. For a list of monitored resource types, see Monitored Resource List.

To list the current resource descriptor types, use the gcloud logging resource-descriptors list command, corresponding to the API method monitoredResourceDescriptors.list. You do not need any special permissions to list the resource types.

Examples

List all the resource types that have instance in their names:

gcloud logging resource-descriptors list --filter="type:instance"

Result:

TYPE                        DESCRIPTION                                                 KEY
gce_instance                A virtual machine instance hosted in Google Compute Engine. project_id,instance_id,zone
spanner_instance            A Cloud Spanner instance.                                   project_id,instance_id,location,instance_config
redis_instance              A Redis instance hosted on Google Cloud MemoryStore.        project_id,region,instance_id,node_id
aws_ec2_instance            A VM instance in Amazon EC2.                                project_id,instance_id,aws_account,region
gce_instance_group          A Google Compute Engine instance group resource.            project_id,instance_group_id,instance_group_name,location
gce_instance_group_manager  A Google Compute Engine instance group manager resource.    project_id,instance_group_manager_id,instance_group_manager_name,location
gce_instance_template       A Google Compute Engine instance template resource.         project_id,instance_template_id,instance_template_name

Exported logs

You export logs by creating sinks that send certain log entries to specific destinations. For more information about sinks, see Overview of Logs Export.

Use the gcloud logging sinks command group, corresponding to the API methods projects.sinks, folders.sinks, billingAccounts.sinks, and organizations.sinks.

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

Creating sinks

Use the gcloud logging sinks create command, corresponding to the API method projects.sinks.create. You must have at least the Logging/Logs Configuration Writer IAM role where the sink is located:

gcloud logging sinks create  NEW_SINK_NAME  DESTINATION  --log-filter="..." ...

Destination authorization. To determine the writer identity service account for your new sink, use the describe command in the next section to fetch the new sink's properties. You need the service account to authorize the sink to write to its destination. The gcloud logging command does not perform the authorization for you, as the Logs Viewer does. For more information, see Destination permissions.

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

  • By default, using the previous flags restricts the sink to exporting only the logs held in the named folder, organization, or billing account.
  • If you additionally add the --include-children flag, then the sink becomes an aggregated export sink and the sink exports logs from all folders and projects contained within the named resource, subject to the filter in the --log-filter flag.
  • Billing accounts do not contain folders or projects, so --include-children has no effect with --billing-account.

For more information and examples, see Aggregated Exports.

Examples

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

gcloud logging sinks create  syslog-errors  \
    storage.googleapis.com/my-third-gcs-bucket \
    --log-filter "resource.type=gce_instance AND logName=projects/[PROJECT_ID]/logs/compute.googleapis.com/syslog AND severity=ERROR"

Create a sink, folder-logs in a folder [FOLDER_ID] that exports the admin activity audit logs from the folder. The destination is an existing Cloud 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 export sink, exporting all admin activity logs from a folder and from all folders and projects containined in the folder.

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 the gcloud logging sinks list or gcloud logging sinks describe commands, corresponding to the API methods projects.sinks.list and projects.sinks.get, respectively. You must have at least the Logging/Logs Viewer role where the log entries are located.

gcloud logging sinks list
gcloud logging sinks describe SINK_NAME

Examples

List sinks in the current project:

gcloud logging sinks list

NAME                            DESTINATION                                                                   FILTER
google-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_ID]

NAME         DESTINATION                               FILTER
folder-logs  storage.googleapis.com/my-folder-bucket   logName:activity

Describe sink test-sink-v4:

gcloud logging sinks describe test-sink-v4

Result:

destination: storage.googleapis.com/my-gcs-bucket
filter: severity=CRITICAL
name: test-sink-v4
outputVersionFormat: V2
writerIdentity: serviceAccount:test-sink-v4@logging-[PROJECT_ID].iam.gserviceaccount.com

Updating sinks

Use the gcloud logging sinks update command, corresponding to the API method projects.sink.update. You must have at least the Logging/Logs Configuration Writer IAM role where the sink is located:

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

gcloud logging sinks update  SINK_NAME  NEW_DESTINATION  --log-filter=NEW_FILTER

You can omit the DESTINATION or --log-filter if those parts do not change.

Examples

Update the destination of a project sink:

gcloud logging sinks update  my-project-sink  storage.googleapis.com/my-second-gcs-bucket

Deleting sinks

Use the gcloud logging sinks delete command, correpsonding to the API method projects.sinks.delete. You must have at least the Logging/Logs Configuration Writer IAM role where the sink is located:

You stop exporting its log entries when you delete a sink:

gcloud logging sinks delete SINK_NAME

Examples

Delete sink syslog-sink-1 in the current project:

gcloud logging sinks delete syslog-sink-1

Logs exclusion

The gcloud logging commands do not yet support the creation or management of log exclusions.

Logs-based metrics

To manage logs-based metrics, use the gcloud logging metrics command group, corresponding to the API methods at projects.metrics.

Logs-based metrics are located only in projects.

Creating simple metrics

Use the gcloud logging metrics create command, corresponding to the API method projects.metrics.create. You must have at least the Logging/Logs Configuration Writer IAM role in the project containing the metric:

gcloud logging metrics create METRIC_NAME  --description=... --log-filter=...

For more advanced counter metrics with labels, use the create command as described in the section Creating distribution metrics.

Examples

Create a logs-based metric that counts the number of log entries with severity ERROR and above from Compute Engine instances:

gcloud logging metrics create error_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 the gcloud beta logging metrics create command, corresponding to the API method projects.metrics.create. You must have at least the Logging/Logs Configuration Writer IAM role where the metric is located:

gcloud beta logging metrics create METRIC_NAME  --config-from-file=FILE_NAME

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

Examples

Create a distribution metric to record request latencies:

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

where logmetric.dat contains the following:

bucketOptions:
  exponentialBuckets:
    growthFactor: 2.0
    numFiniteBuckets: 64
    scale: 0.01
description: App Engine Request Latency
filter: |
  resource.type="gae_app"
  logName="projects/[PROJECT_ID]/logs/appengine.googleapis.com%2Fnginx.request"
labelExtractors:
  path: EXTRACT(httpRequest.requestUrl)
metricDescriptor:
  labels:
  - description: HTTP Path
    key: path
  metricKind: DELTA
  name: projects/[PROJECT_ID]/metricDescriptors/logging.googleapis.com/user/my-distribution-metric
  type: logging.googleapis.com/user/my-distribution-metric
  valueType: DISTRIBUTION
name: my-distribution-metric
valueExtractor: EXTRACT(jsonPayload.latencySeconds)

Result:

Created [my-distribution-metric].

Updating metrics

Use gcloud beta logging metrics update, corresponding to the API method projects.metrics.update, You must have at least the Logging/Logs Configuration Writer IAM role in the project containing the metric:

gcloud beta logging metrics update METRIC_NAME ...

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

Examples

Change the filter in my-distribution-metric:

gcloud beta logging metrics update my-distribution-metric --log-filter="[NEW_LOG_FILTER]"

Listing and describing metrics

Use gcloud beta logging metrics list, corresponding to the API method projects.metrics.list, and gcloud beta logging metrics describe, corresponding to the API method projects.metrics.get. You must have at least the Logging/Logs Viewer IAM role in the project containing the metric:

gcloud beta logging metrics list ...
gcloud beta logging metrics describe METRIC_NAME

The metrics list command by defaults shows the full description of every listed metric. Use the --format flag to control how much information is listed.

Examples

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

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

Result:

NAME                       DESCRIPTION
myapp/request_latency      Request latency for myapp
bigquery_billed_bytes      Billed Bytes
food_latency               How long does it take to service all food requests
healthz_latencies          /healthz latencies in microseconds
latency_on_food            Tracking latency on food requests
lines_written
my_latency_metric
no-match-dist-metric
pizza_latency              How long does it take to service pizza requests?

Describe a user-defined distribution metric named myapp/request_latency. Show the information in the default YAML format:

gcloud logging metrics describe "myapp/request_latency"

Result:

bucketOptions:
  exponentialBuckets:
    growthFactor: 2.0
    numFiniteBuckets: 64
    scale: 0.01
description: Request latency for myapp
filter: |
  resource.type="gae_app"
  logName="projects/[PROJECT_ID]/logs/appengine.googleapis.com%2Fnginx.request"
labelExtractors:
  path: EXTRACT(httpRequest.requestUrl)
metricDescriptor:
  description: Request latency for myapp
  labels:
  - description: HTTP Path
    key: path
  metricKind: DELTA
  name: projects/[PROJECT_ID]/metricDescriptors/logging.googleapis.com/user/myapp/request_latency
  type: logging.googleapis.com/user/myapp/request_latency
  valueType: DISTRIBUTION
name: myapp/request_latency
valueExtractor: EXTRACT(jsonPayload.latencySeconds)

Deleting metrics

Use the gcloud beta logging metrics delete command, corresponding to the API method projects.metrics.delete. You must have at least the Logging/Logs Configuration Writer IAM role in the project containing the metric:

gcloud beta logging metrics delete METRIC_NAME

Examples

Delete the metric my-distribution-metric from the current project

gcloud beta logging metrics delete "my-distribution-metric"

Result

Really delete metric [my-distribution-metric]?
Do you want to continue (Y/n)?  Y
Deleted [my-distribution-metric].
Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Logging