Quickstart using Cloud SDK

This quickstart introduces you to some of the capabilities of Stackdriver Logging and shows you how to:

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

Before you begin

You must have a Google Cloud Platform project with billing enabled to complete this quickstart. If you don't have a GCP project, or if you don't 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 project selector page

  3. Make sure that billing is enabled for your Google Cloud Platform project.

    Learn how to enable billing

Getting started

You can use the Cloud Shell environment or a Compute Engine virtual machine (VM) instance for the Cloud SDK commands in this quickstart.

Cloud Shell

  1. The Cloud SDK is pre-installed in the Cloud Shell environment. You don't need to install or configure any other software.

  2. Open the Cloud Shell and verify your project configuration:

    1. From the GCP Console, click Activate Cloud Shell:

      Activate Cloud Shell

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

      Welcome to Cloud Shell

    2. The welcome message echoes the configured project ID. If this isn't the project that you want to use, run the following command after replacing [PROJECT_ID] with your project ID:

       gcloud config set project [PROJECT_ID]
      

VM Instance

  1. Create a Compute Engine VM instance:

    1. From the GCP Console, select Compute Engine > VM instances. Select Create. If you see the following message, wait until your Compute Engine is ready before proceeding:

      Compute Getting Ready

    2. In Identity and API access, select Set access for each API. Scroll through the listings until you find the Stackdriver Logging API. Toggle the access from Write only to Full:

      Compute Getting Ready

    3. Leave all other settings at their default values and click Create. After a moment, your VM instance is ready for your use.

  2. To connect to your VM instance shell, go to SSH > Open in browser window. After a moment, a Debian GNU/Linux shell opens in a window and displays a welcome message.

  3. The Cloud SDK is pre-installed in your GCM VM instance. To verify that your Cloud SDK is configured for your Compute Engine project, run this command:

     gcloud config list
    
  4. If the listed project isn't the one that you want to use, run the following command after replacing [PROJECT_ID] with your project ID:

     gcloud config set project [PROJECT_ID]
    

Write log entries by using the Cloud SDK

Logging supports log entries with structured and unstructured data. Structured data consists of a JSON data structure; for example {"weather": "partly cloudy"}. 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 write a log entry with structured data, you must include --payload-type=json. If you omit this field, Logging interprets the payload as unstructured text.

If the log my-test-log doesn't exist, then Logging creates the log when the log entry is received.

List log entries by using the Cloud SDK

You can retrieve log entries from Logging and display them by 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 by using API Explorer

You can use API Explorer to run Logging API methods without writing any code. To read from 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 displays. It has a header Try this API. Copy the following text and paste it into the Request body. Before you click Execute, replace the [PROJECT_ID].

      "resourceNames": [
        "projects/[PROJECT_ID]"
      ],
      "filter": "resource.type=global"
    

    An example of a completed Request body with these settings is shown below:

    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"
        }
      ]
    }
    

View logs in the Logs Viewer

The Logs Viewer is a tool to view, query, and download log entries. To view logs in the Logs Viewer, do the following:

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

    Go to Logs Viewer

    You see the Logs Viewer page:

    Logs Viewer

    Check the Google Cloud Platform navigation bar and make sure your project is selected. Use the project drop-down list to select your project if necessary.

  2. In the resource-type drop-down list, select Global to view 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 Logging to receive log entries.

  3. To expand a log entry, click its menu .

    Logs Viewer

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

For more information on log entry data formats, see the LogEntry type.

Query log entries in the Logs Viewer

You can query log entries by 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, do the following:

  1. In the search-query box, enter the string simple. The logs display shows only the log entry A simple entry.

  2. After you have viewed your log, remove the query string you added and click refresh (refresh). 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, do the following:

  1. Switch to the advanced query mode by clicking the drop-down menu in the query box and then selecting Convert to advanced filter.
  2. The query box contains the line resource.type="global". Under that line, enter this line:

    jsonPayload.weather:partly
    
  3. Click Submit filter. The result is the single log entry My second entry:

    Advanced query for log entries

For more information on queries, go to Advanced logs queries.

Troubleshooting

  • Typographical errors and unknown field names result in Cloud SDK commands completing with invalid argument messages. For example, if you forget the period in resource.type, it results in the error:

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
    
  • When Stackdriver Logging hasn't been granted the necessary access permissions, Cloud SDK commands complete with permission denied messages. For example, if a Compute Engine VM instance is configured with the default API settings, the list command completes with a permission denied error:

     ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
    

    To resolve this condition, modify your Compute Engine VM instance permissions to grant Stackdriver Logging read permission by doing the following:

    1. Go to the VM instance details page for your VM instance. Click Stop. This action might take a minute or two to complete.
    2. To modify the configuration, click Edit.
    3. Search for the header Cloud API access scopes, and click Details to display the settings for each API. Change the entry from Stackdriver Logging API to Full. Click Save.
    4. To restart your VM instance, click Start. After a few moments, your VM is ready to use.
  • When API Explorer can't complete your command, or requires additional authorization, it displays a message or error code:

    • 200 response code and no entries: If the message nextPageToken is displayed, it indicates that API Explorer didn't have time to complete the search. Add a pageToken to your request, set the value to be the same as that given with the key nextPageToken, and then retry the command.
    • 400 response code: The query value is invalid. For example, if you misspell global as gloobal, the message is Unsupported resource type: gloobal.
    • 404 response code: The project ID is invalid. Check the spelling of your project identifier.
    • 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 don't delete your log entries, they expire and be removed. For retention information, go to Quotas & limits.

What's next

Apakah halaman ini membantu? Beri tahu kami pendapat Anda:

Kirim masukan tentang...

Stackdriver Logging
Butuh bantuan? Kunjungi halaman dukungan kami.