Command Line Interface

The Google Cloud SDK command, gcloud logging, is a command-line interface that uses Stackdriver Logging API v2. If you find that you need to use the actual API, try the APIs Explorer for Stackdriver Logging API v2.

Before you begin

  1. Go to the Stackdriver > Logging page in the GCP Console, select a project, and verify that you can see logs in your project. For more information, see the Getting Started section of the Logs Viewer.

    Go to Stackdriver > Logging

  2. Install and initialize the Cloud SDK.

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

    gcloud config set project PROJECT_ID
    

Summary of commands

For a summary of commands and documentation for individual commands, see the gcloud logging reference.

From a command line, you can also add --help to a partial command to get more details. For example:

gcloud logging sinks create --help

Listing logs

List all of the logs in your project that have any log entries:

gcloud logging logs list

Example:

gcloud logging logs list
NAME
apache-access
apache-error
appengine.googleapis.com/request_log
compute.googleapis.com/activity_log
pubsubtestlog
syslog

Creating logs

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

Deleting logs

Delete all entries in a log:

gcloud logging logs delete LOG

A log with no entries is effectively deleted and does not appear in the list of project logs. Individual log entries cannot be explicitly deleted, but they expire and are deleted according to the Stackdriver Logging retention policy. If you write new entries to the log, it will reappear. Audit logs cannot be deleted.

Example:

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

Stackdriver Error Reporting: Deleting log entries does not delete the error samples collected from logs by Stackdriver Error Reporting. To delete the samples, use the deleteEvents method of the Error Reporting API.

Writing log entries

Write a log entry. If the log does not exist, it is created. You can specify a severity for the log entry, and you can write a structured log entry by specifying --payload-type=json and writing your message as a JSON string:

gcloud logging write LOG STRING
gcloud logging write LOG JSON-STRING --payload-type=json

The write command takes the following flags:

--payload-type=(text|json)
Optional. Specifies the payload type of a new log entry.
--severity=SEVERITY
Optional. Adds a severity to a new log entry. Values are DEFAULT (default), DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, or EMERGENCY. The DEFAULT value means no severity is assigned.

Example:

gcloud logging write my-test-log "A simple entry"

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

To find these log entries, look in the Logs Viewer under the Global resource for the log messages:

Custom log entries

Reading log entries

Reads (lists) log entries. The filter specifies the log entries to return. The returned log entries are in the log entry format, and the filter must also be in that format:

gcloud logging read FILTER

This command can take additional flags; use --help for information about them:

--freshness=FRESHNESS
Optional. Return entries that are not older than this value.
--order=ORDER
Optional. Ordering of returned log entries based on timestamp field. Default is newest-first.
--organization=ORGANIZATION_ID
Optional. Read log entries associated with the specified organization, rather than the default project.
--limit=LIMIT
Optional. The maximum number of log entries to list.

Example:

gcloud logging read "resource.type=gce_instance AND logName=projects/my-gcp-project-id/logs/syslog AND textPayload:SyncAddress" --limit 10 --format json

Following is an example of a returned log entry:

{
  "insertId": "2016-04-07|08:56:48.137651-07|10.162.32.129|-1509625619",
  "logName": "projects/my-gcp-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"
}

Exporting logs

Manage export sinks. You can get the documentation by using the --help command. For example:

gcloud logging sinks create --help

Once a sink is created, it exports new log entries received by Stackdriver Logging. Sinks do not export log entries received before the sink was created.

Workflow for creating sinks

Creating a sink to export logs requires a few steps. The gcloud logging command uses unique writer identities in the sinks it creates, which means there is a unique service account associated with every sink which you must grant appropriate permissions in the sink destination.

Follow these steps to create an export sink:

  1. Create the destination Cloud Storage bucket, Cloud Pub/Sub topic, or BigQuery dataset that will receive the logs.
  2. Create the sink. Exporting of logs begins immediately, but export attempts will fail until the following steps are completed.
  3. If needed, use the sinks describe command to fetch the sink's service account.
  4. Add the service account to the destination's permission list and give it write access. The sink's exports will then stop failing.

Creating sinks

This section describes how to create a sink. For information on the sink creation workflow, see Workflow for creating sinks on this page.

To export log entries use the following command.

gcloud logging sinks create  SINK_NAME  DESTINATION  --log-filter FILTER

Examples:

Create a sink, syslog-errors, that exports syslog log entries with severity ERROR from Compute Engine VM instances:

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"

Listing sinks

List your project's sinks.

gcloud logging sinks list

Example:

gcloud logging sinks list
NAME                            DESTINATION                                  FILTER
test-sink-1                     storage.googleapis.com/my-gcs-bucket         severity>WARNING

Describing sinks

Show the name, destination, service account, and filter assigned to a sink:

gcloud logging sinks describe  SINK_NAME

Example (project sink):

gcloud logging sinks describe my-project-sink
destination: storage.googleapis.com/my-second-gcs-bucket
filter: severity=ERROR
name: my-project-sink
outputVersionFormat: V2
writer_identity: serviceAccount:my-project-sink@logging-123456654-6.iam.gserviceaccount.com

Updating sinks

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

gcloud logging sinks update  SINK_NAME  DESTINATION
gcloud logging sinks update  SINK_NAME  --log-filter FILTER
gcloud logging sinks update  SINK_NAME  DESTINATION  --log-filter FILTER

Example:

Update the destination of a project sink.

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

Deleting sinks

Stop exporting a log, a log service, or log entries matching a filter by deleting the sink:

gcloud logging sinks delete SINK_NAME

Example:

gcloud logging sinks delete syslog-sink-1
...

Logs-based metrics

Manage logs-based metrics.

Example: Create a logs-based metric called error_count.

gcloud logging metrics create error_count \
    "Syslog error counts." \
    "resource.type=gce_instance AND severity>=ERROR"

Example: List the project's logs-based metrics.

gcloud logging metrics list
NAME         DESCRIPTION           FILTER
error_count  Syslog error counts.  resource.type=gce_instance AND severity>=ERROR

Example: Delete the error_count metric.

gcloud logging metrics delete error_count

What's next

See the Stackdriver Logging API v2.

Send feedback about...

Stackdriver Logging