This document introduces you to some of the capabilities of Cloud Loggingand shows you how to do the following:

• Write log entries by using the Google Cloud CLI.
• List log entries by using the gcloud CLI.
• List log entries by using the Logging API.
• View and query log entries by using the Logs Explorer.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects createPROJECT_ID

  ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set projectPROJECT_ID

  ReplacePROJECT_ID with your Google Cloud project name.

If you're using an existing project for this guide,verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects createPROJECT_ID

  ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set projectPROJECT_ID

  ReplacePROJECT_ID with your Google Cloud project name.

If you're using an existing project for this guide,verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Required roles

To get the permissions that you need to create, list, and delete log entries, ask your administrator to grant you theLogging Admin (roles/logging.admin) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

The Logs Writer (roles/logging.logWriter) and Logs Viewer(roles/logging.viewer) roles contain the permissions to create and listlog entries. To delete log entries, grant the Logging Admin(roles/logging.admin) role, which contains the permissions to create, list,and delete log entries. Note that the Logging Admin(roles/logging.admin) role also grants permissions to perform all actionsin Logging.

Write log entries by using the gcloud CLI

Logging supports log entries with structured and unstructureddata. Structured data consists of a JSON data structure; for example,{"weather": "partly cloudy"}. Unstructured datais a string of characters; for example,"A simple entry".

In the next steps, you use the gcloud CLI to write a log entry withunstructured data and a log entry with structured data.Thegcloud CLI provide a command-line interface tothe Cloud Logging API.

1. Write a log entry with unstructured data to the logmy-test-log, runthegcloud logging write command:

   gcloudloggingwritemy-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 the logmy-test-log:

   gcloudloggingwrite--payload-type=jsonmy-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, then Logginginterprets the payload as unstructured data.

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

List log entries by using the gcloud CLI

You can retrieve log entries from Logging and display themby using the gcloud CLI. For example, to retrieve and display the logentries with a resource type ofglobal, run the following command:

gcloudloggingread"resource.type=global"

The command returns a result similar to the following:

---insertId:jpj9zjf73t1mnjsonPayload:message:Mysecondentryweather:partlycloudylogName:projects/myloggingproject/logs/my-test-logreceiveTimestamp:'2018-11-01T18:39:31.114507977Z'resource:labels:project_id:myloggingprojecttype:globaltimestamp:'2018-11-01T18:39:31.114507977Z'---insertId:vd4m1if7h7u1alogName:projects/myloggingproject/logs/my-test-logreceiveTimestamp:'2018-11-01T18:39:19.718100792Z'resource:labels:project_id:myloggingprojecttype:globaltextPayload:Asimpleentrytimestamp:'2018-11-01T18:39:19.718100792Z'

For information about reading logs, see thegcloud logging read reference documentation.

List log entries by using APIs Explorer

To run Logging API methods without writing any code, seeUsing the APIs Explorer. To read a list of log entriesfrom Logging, do the following:

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

   Go to entries.list API page

2. Configure and run the API command:

   1. ReplacePROJECT_ID in the following text:

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

   2. Copy the updated text from the previous step, and paste it intotheRequest body field of APIs Explorer.

   3. ClickExecute.

   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 log entries in the Logs Explorer

To view log entries in the Google Cloud console, you can use theLogs Explorer. Most Google Cloud projects store a large number of logs;you can select certain log entries by writing a query.

To view the log entries that you wrote using the Logs Explorer, do thefollowing:

1. In the Google Cloud console, go to theLogs Explorer page:

   Go toLogs Explorer

   If you use the search bar to find this page, then select the result whose subheading isLogging.

   Ensure your Google Cloud project is selected in the Google Cloudnavigation bar. If necessary, use the Google Cloud project drop-down listto select your Google Cloud project.

2. In theResource menu, selectGlobal.

   If you don't see theGlobal menu option or if you don't see your logentries, then wait a few minutes and refresh the page. It can take afew minutes for Logging to receive log entries.

3. To view the details of a log entry, click itschevron_rightMenu.

   The first log entry has its data stored intextPayload. The second logentry contains structured data that is stored injsonPayload. Thestructured payload contains the keysmessage andweather.

   Note: Whenmessage is a key for a structured log entry,Logging uses it as the summary of the log entry when theentry isn't expanded.

For information about the data format of log entries, see theLogEntry type.

Query log entries in the Logs Explorer

You can query log entries by using the query editor and, with structured logs,by the key and value. For example, to display all log entries that contain thetextsimple, do the following:

1. In the Google Cloud console, go to theLogs Explorer page:

   Go toLogs Explorer

   If you use the search bar to find this page, then select the result whose subheading isLogging.

2. In theResource menu, selectGlobal.

3. In the query editor, enter the stringsimple in quotation marks.The logs display shows only the log entryA simple entry.

4. After you have viewed your log, remove the query string you added andclickRun query. Both log entries reappear in the display.

To display all log entries with structured data that have a key ofweatherwhere thevalue field containspartly, do the following:

1. The query editor contains the lineresource.type="global". Enter the following command:

   jsonPayload.weather:partly

2. ClickRun query. The result is the single log entryMy second entry.

Logs Explorer also offers saved, suggested, and recent queries. For more information about queries, seeBuild queries in the Logs Explorer.

For sample queries, seeSample queries using the Logs Explorer.

Troubleshooting

• Typographical errors and unknown field names result in the gcloud CLI commands completing withinvalid argument messages. For example, if you forget the period inresource.type, then it results in the error:

  ERROR:(gcloud.logging.read)INVALID_ARGUMENT:Fieldnotfound:'resourcetype'.

• When Cloud Logging hasn't been granted the necessary access permissions, the gcloud CLI commands complete withpermission denied messages. For example, if a Compute Engine VM instance is configured with the default API settings, then thelist command completes with a permission denied error:

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

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

  1. Go to theVM instance details page for your VM instance. ClickStop. This action might take a minute or two to complete.
  2. To modify the configuration, clickEdit.
  3. Search for the headerCloud API access scopes, and clickDetails to display the settings for each API. Change the entry from Cloud Logging API toFull. ClickSave.
  4. To restart your VM instance, clickStart. After a few moments, your VM is ready to use.

• When APIs Explorer can't complete your command, or requires additionalauthorization, it displays a message or error code:

  • 200 response code and no entries: If the messagenextPageToken isdisplayed, then it indicates that APIs Explorer didn't have time tocomplete the search. Add apageToken to your request, set the value tobe the same as that given with the keynextPageToken, and then retrythe command.
  • 400 response code: The query value is invalid. For example, if youmisspellglobal asgloobal, then the message isUnsupported resource type: gloobal.
  • 404 response code: The project ID is invalid. Check the spellingof your project identifier.
  • You might be asked to sign into yourGoogle Cloud project and permit APIs Explorer to access your account.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, delete the Google Cloud project with the resources.

1. (Optional) To delete the log entries you created, run the followinggcloudcommand:

   gcloud logging logs delete my-test-log

   If you don't delete your log entries, then they expire and are removed.For retention information, seeQuotas & limits.

What's next

• For details on the Logging command-line interface, read thereference pages for thegcloud logging command group.
• For documentation on the Logging API, seeCloud Logging API.
• For details on the Logs Explorer, seeUsing the Logs Explorer.

• To learn how to collect log entries from your VM instances inLogging, seeGoogle Cloud Observability agents.