Quickstart

This Quickstart introduces you to some of the capabilities of Stackdriver Logging. This page shows you how to:

  • Write log entries using the Cloud SDK.
  • View and filter log entries using the Logs Viewer.
  • List log entries using the Cloud SDK.
  • List log entries using the Logging API.

In this Quickstart, you use the Cloud Shell environment for the Cloud SDK commands.

Before you begin

To use Cloud Shell you must have a GCP project with billing enabled. If you do not have a GCP project, or if you do not have billing enabled for your project, do the following:
  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a GCP project.

    Go to the Manage resources page

  3. Make sure that billing is enabled for your project.

    Learn how to enable billing

The Cloud SDK is pre-installed in the Cloud Shell environment. You do not need to install or configure any other software.

This Quickstart uses a project name of MyLoggingProject and a project ID of myloggingproject.

Open the Cloud Shell

From the GCP Console, click the Activate Cloud Shell button in the upper right-hand corner:

Activate Cloud Shell

The Cloud Shell opens in a window and displays a welcome banner:

Welcome to Cloud Shell

The welcome message echos the configured project ID. Verify, and correct if necessary, the project ID.

Write log entries using the Cloud SDK

Stackdriver Logging supports log entries with structured and unstructured data. Structured data consists of one or more key-value pairs, for example {"weather": "partly cloudy"}. In contrast, unstructured data is a string of characters, for example, A simple entry. In the next steps, you use the Cloud SDK to write a log entry with unstructured data and a log entry with structured data:

  1. Write a log entry with unstructured data to the log my-test-log:

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

    After the command completes, you see the message: Created log entry.

  2. Write a log entry with structured data to my-test-log:

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

    When you send structured data, you must include --payload-type=json. If you omit this field, the payload is interpreted as unstructured text.

If the log my-test-log does not exist, Stackdriver Logging creates the log when the log entry is received.

View logs in the Logs Viewer

The Logs Viewer is a powerful tool to view, filter, and download log entries:

  1. Go to the Logs Viewer page in the Google Cloud Platform Console:

    Go to the Logs Viewer page

  2. You see the Logs Viewer page:

    Logs Viewer

    Make sure your project is selected in the top navigation bar.

  3. In the drop-down menu above the log entries, choose Global to see the log entries you wrote:

    Logs Viewer Global

    If you don't see the Global menu option or if you don't see your log entries, wait a few minutes and refresh the page. It can take a few minutes for log entries to be received by Logging.

  4. The disclosure button (arrow_right) next to each log entry indicates that a summary of the log entry is displayed. Click the disclosure buttons to expand the log entries:

    Logs Viewer

    The first log entry has its data stored in a textPayload. The second log entry contains structured data that is stored in a jsonPayload. The structured payload contains the keys message and weather.

For more information on log entry data formats, see Datatypes common to all logs.

Filter log entries

You can filter log entries using a text field, and, with structured logs, by the key and value. For example, to display all log entries that contain the text simple:

  • In the filter box above the logs selector, enter the string simple. The logs display shows only the log entry A simple entry.

  • After you have viewed your log, remove the filter string you added and click the Refresh button (refresh) above the logs selector. Both log entries reappear in the display.

To display all log entries with structured data that have a key of weather where the value field contains partly:

  • Switch to the advanced filter mode by clicking the disclosure button (arrow_drop_down) at the far right of the filter box and then selecting Convert to advanced filter.
  • The filter box contains resource.type="global". Below this line, enter:

    jsonPayload.weather:partly
    
  • Click Submit filter.

  • The result is the single log entry My second entry:

    Advanced filter for log entries

For more information on filters, see Searching and filtering logs.

List log entries using the Cloud SDK

You can retrieve log entries from Stackdriver Logging and display them using the Cloud SDK. For example, to retrieve and display the log entries with a resource type of global, run the following command:

gcloud logging read "resource.type=global"

The command returns a result similar to the following:

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

List log entries using API Explorer

You can use API Explorer to run Logging API methods without writing any code. To read from Stackdriver Logging a list of log entries:

  1. Go to the API reference page for the entries.list API method:

    Go to entries.list API page

  2. The API Explorer widget is attached to the right or bottom of the page. It has a header Try this API. In the Request body field, fill in the resourceNames and filter fields as shown in the following screenshot. Be sure to replace myloggingproject with your project ID:

    Try this API

  3. Click Execute. The method returns a response similar to the following:

    {
      "entries": [
        {
          "textPayload": "A simple entry",
          "insertId": "vd4m1if7h7u1a",
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:19.718100792Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
        },
        {
          "insertId": "jpj9zjf73t1mn",
          "jsonPayload": {
            "message": "My second entry",
            "weather": "partly cloudy"
          },
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:31.114507977Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
        }
      ]
    }
    

Troubleshooting API Explorer

There are different types of errors that can occur when you are using API Explorer:

  • If you have an incorrect project ID, the command completes with a 404 error code and the message Project does not exist.
  • If you have an error in the filter value, the command completes with a 400 error code and the message identifies the specific error. For example, if you misspell global as gloobal, the message is Unsupported resource type: gloobal.
  • If the command completes with a status of 200, there are no entries but the message nextPageToken appears, this indicates that the search found no log entries but it did not have time to search all the possible entries. Add a pageToken to your request, with the value the same as that given with the key nextPageToken, and then retry the command.

Lastly, you might be asked to sign into your Google account and permit API Explorer to access your account.

Clean up

To avoid incurring charges to your GCP account for the resources used in this quickstart:

  1. (Optional) To delete the log entries you created, run the following gcloud command:

    gcloud logging logs delete my-test-log
    

    If you do not delete your log entries, they will expire and be removed. See Quota Policy.

What's next

  • See Logs Viewer for a more detailed discussion of the Logs Viewer.
  • See Exporting logs to learn how to export your log entries to Google Cloud Storage, Google BigQuery, and Google Cloud Pub/Sub.
  • See Logging Agent to learn how to collect log entries from your virtual machine instances in Logging.
  • See Audit Logs for your auditing and compliance needs.
  • See Stackdriver Logging API to learn how to read, write, and configure logs from your applications.
Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Logging