---
title: "Google Cloud Logging data source plugin for Grafana"
description: "A Grafana data source plugin for querying and visualizing logs from Google Cloud Logging. Google Cloud Logging data source plugin for Grafana by googlecloud."
---

> This is the Markdown version of https://grafana.com/grafana/plugins/googlecloud-logging-datasource/

# Google Cloud Logging

- Developer: googlecloud
- Version: 1.8.1
- [Installation](https://grafana.com/grafana/plugins/googlecloud-logging-datasource/installation.md)
- [Change log](https://grafana.com/grafana/plugins/googlecloud-logging-datasource/changelog.md)

![cloud\_logging\_config](https://grafana.com/api/plugins/googlecloud-logging-datasource/versions/1.8.1/images/img/cloud_logging_config.png)

![cloud\_logging\_explore\_view](https://grafana.com/api/plugins/googlecloud-logging-datasource/versions/1.8.1/images/img/cloud_logging_explore_view.png)

![cloud\_logging\_dashboard\_view](https://grafana.com/api/plugins/googlecloud-logging-datasource/versions/1.8.1/images/img/cloud_logging_dashboard_view.png)

# Google Cloud Logging Data Source

## Overview

The Google Cloud Logging Data Source is a backend data source plugin for Grafana, which allows users to query and visualize their Google Cloud logs in Grafana.

![image info](https://github.com/GoogleCloudPlatform/cloud-logging-data-source-plugin/blob/main/src/img/cloud_logging_explore_view.png?raw=true)

## Setup

### Enable Cloud Resource Manager API

You need to enable the resource manager API. Otherwise, your cloud projects will not be displayed in the dropdown menu.

You can follow the steps to enable it:

1. In the Google Cloud console, open **APIs & Services > Library**, select your project and search for **Cloud Resource Manager API**
2. Press the `Enable` button

Alternatively, enable it from the command line:

```sh
gcloud services enable cloudresourcemanager.googleapis.com --project=<your-project-id>
```

See [Enabling and disabling services](https://cloud.google.com/service-usage/docs/enable-disable) for details.

### Generate a JWT file & Assign IAM Permissions

1. If you don't have a GCP project, add a new GCP project [here](https://cloud.google.com/resource-manager/docs/creating-managing-projects#console)
2. Open the [Credentials](https://console.developers.google.com/apis/credentials) page in the Google API Console
3. Click **Create Credentials** then click **Service account**
4. On the Create service account page, enter the Service account details
5. Fill in the `Service account details` and then click `Create and Continue`
6. On the `Grant this service account access to project` section, add the `Logs Viewer` role and `Logs View Accessor` role under `Logging` to the service account. Click `Done`
7. In the next step, click the service account you just created. Under the `Keys` tab and select `Add key` and `Create new key`
8. Choose key type `JSON` and click `Create`. A JSON key file will be created and downloaded to your computer

If you want to access logs in multiple cloud projects, you need to ensure the service account has permission to read logs from all of them.

If you host Grafana on a GCE VM, you can also use the [Compute Engine service account](https://cloud.google.com/compute/docs/access/service-accounts#serviceaccount). You need to make sure the service account has sufficient permissions to access the scopes and logs in all projects.

Similar to [Prometheus data sources on Google Cloud](https://cloud.google.com/stackdriver/docs/managed-prometheus/query#use-serverless), you can also configure a scheduled job to use an OAuth2 access token to view the logs. Please follow the steps in the [data source syncer README](https://github.com/GoogleCloudPlatform/cloud-logging-data-source-plugin/blob/main/datasource-syncer/README.md) to configure it.

### Service account impersonation

You can also configure the plugin to use [service account impersonation](https://cloud.google.com/iam/docs/service-account-impersonation). You need to ensure the service account used by this plugin has the `iam.serviceAccounts.getAccessToken` permission. This permission is in roles like the [Service Account Token Creator role](https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountTokenCreator) (roles/iam.serviceAccountTokenCreator). Also, the service account impersonated by this plugin needs logging read and project list permissions.

### OAuth Passthrough

You can configure the data source to use the OAuth token of the signed in user to authenticate to Google Cloud Logging. This requires a Grafana instance that is configured with [Google authentication](https://grafana.com/docs/grafana/latest/setup-grafana/configure-access/configure-authentication/google/).

Once Grafana is configured with Google authentication for signing in, ensure that the scopes set in the Grafana configuration include: `https://www.googleapis.com/auth/userinfo.profile`, `https://www.googleapis.com/auth/userinfo.email`, and `https://www.googleapis.com/auth/logging.read`. The latter will allow the signed in user to read Google Cloud Logging data.

You can then configure the data source with the `OAuth Passthrough` authentication method. Ensure that you provide a default project ID otherwise the health-check will fail.

### Universe Domain

If you are using a Google Cloud environment that uses a custom universe domain (e.g., a sovereign or isolated cloud), you can configure the **Universe Domain** in the data source settings. This tells the plugin to use a different API endpoint instead of the default `googleapis.com`.

Leave this field empty to use the default `googleapis.com` domain.

### Grafana Configuration

1. With Grafana restarted, navigate to `Configuration -> Data sources` (or the route `/datasources`)
2. Click "Add data source"
3. Select "Google Cloud Logging"
4. Provide credentials from your JWT file, either by uploading it using the file selector or by pasting its contents directly into the designated field
5. Optionally, configure the **Universe Domain** if you are using a non-default GCP environment
6. Optionally, configure the **Project List Filter** to restrict which projects appear in the project dropdown (see [Project List Filter](#project-list-filter) below)
7. Optionally, configure the **Log Bucket Filter** to include or exclude specific log buckets from the bucket dropdown (see [Log Bucket Filter](#log-bucket-filter) below)
8. Click "Save & test" to test that logs can be queried from Cloud Logging

![image info](https://github.com/GoogleCloudPlatform/cloud-logging-data-source-plugin/blob/main/src/img/cloud_logging_config.png?raw=true)

### Project List Filter

If you have access to many GCP projects, you can restrict which projects appear in the project dropdown by configuring a **Project List Filter** in the data source settings.

Enter project IDs or regex patterns in the text area, one per line. Only projects matching at least one pattern will appear in the dropdown. Leave the field empty to show all projects (the default behavior).

Each line is treated as a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) anchored to the full project ID. For example:

| Pattern           | Matches                                                  |
| ----------------- | -------------------------------------------------------- |
| `my-project-123`  | Only the exact project `my-project-123`                  |
| `team-alpha-.*`   | All projects starting with `team-alpha-`                 |
| `prod-.*-logging` | Projects like `prod-us-logging`, `prod-eu-logging`, etc. |

You can combine multiple patterns (one per line) to match the union of all patterns. If a pattern contains invalid regex syntax, it is treated as a literal string match.

### Log Bucket Filter

You can control which log buckets appear in the bucket dropdown by configuring a **Log Bucket Filter** in the data source settings. This supports both **include** and **exclude** patterns, which is especially useful for excluding default system buckets from initiative projects.

Enter patterns in the text area, one per line:

- **Include patterns** (no prefix): Only buckets matching at least one include pattern are shown.
- **Exclude patterns** (prefixed with `!`): Buckets matching any exclude pattern are removed.

When both include and exclude patterns are present, include patterns are applied first, then exclude patterns remove from the result. Leave the field empty to show all buckets (the default behavior).

Patterns are [regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) anchored to the **full bucket path** as returned by the API (e.g., `global/buckets/_Default` or `locations/us-central1/buckets/my-bucket`).

| Pattern                               | Effect                                                          |
| ------------------------------------- | --------------------------------------------------------------- |
| `!.*/_Default`                        | Exclude all `_Default` buckets across all locations             |
| `!.*/_Default`<br>`!.*/_Required`     | Exclude both `_Default` and `_Required` buckets                 |
| `.*my-app-logs`                       | Include only buckets ending with `my-app-logs`                  |
| `global/buckets/.*`<br>`!.*/_Default` | Include only `global/buckets/*` buckets, but exclude `_Default` |

If a pattern contains invalid regex syntax, it is treated as a literal string match.

### Logs to traces

You can link log entries to a [Google Cloud Trace](https://grafana.com/grafana/plugins/googlecloud-trace-datasource/) data source. In the data source settings, under **Logs to traces**, select the Google Cloud Trace data source. Once configured, any log entry written with the [LogEntry `trace` field](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry) shows a `traceId` field with a **View trace** link in the log details — clicking it opens the trace in the selected data source. The link carries the project parsed from the entry's `projects/<project>/traces/<id>` path; if the `trace` value is not in that form, the data source's default project is used, and if no project can be determined the link is omitted.

If your logs are routed through a central logging project (for example, an OpenTelemetry collector writes to one project and a [log sink](https://cloud.google.com/logging/docs/export/configure_export_v2) forwards entries to tenant projects), the `trace` path is stamped with the routing project's ID even though the trace lives in the tenant project, so the parsed project is wrong. Enable **Get trace project from the query** to make the link use the project of the query that produced the log entry instead (falling back to the data source's default project; if neither resolves, the link is omitted). Only the link target changes — the raw `trace` label in the log details still shows the original path.

Provisioning example:

```yaml
jsonData:
  logsToTraces:
    datasourceUid: my-cloud-trace-datasource-uid
    # Optional: use the queried project for View trace links instead of the
    # project in the log entry's trace path (for centrally routed logs)
    # projectIdFromQuery: true
```

> **Note: a "View trace" link is not a guarantee that the trace was recorded.** For services with automatic request tracing (Cloud Run, App Engine, GKE ingress, and other services behind Google's HTTP load balancing), every request log entry carries a trace ID, but Cloud Trace only stores traces for **sampled** requests — and the built-in sampling rate is low (roughly 0.1 traces per second per instance for Cloud Run). Clicking **View trace** for an unsampled request shows a "trace not found" result; this is expected and matches the behavior of the trace links in the Google Cloud console's Logs Explorer. To make more links resolve, increase sampling on the application side: instrument the service with [OpenTelemetry](https://cloud.google.com/trace/docs/setup) and configure your own sampling rate, or force sampling on individual requests by sending an `X-Cloud-Trace-Context: <trace-id>/<span-id>;o=1` header (or a W3C `traceparent` header with the sampled flag set). Note that Cloud Trace bills per ingested span, so consider cost before sampling at 100% on high-traffic services.

For the reverse direction (from a trace span to its logs), configure **Trace to logs** in the Google Cloud Trace data source settings.

### An alternative way to provision the data source

After the plugin is installed, you can define and configure the data source in YAML files as part of Grafana's provisioning system, similar to [the Google Cloud Monitoring plugin](https://grafana.com/docs/grafana/latest/datasources/google-cloud-monitoring/#provision-the-data-source). For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources).

The following YAML is an example.

```yaml
apiVersion: 1

datasources:
  - name: Google Cloud Logging
    type: googlecloud-logging-datasource
    access: proxy
    jsonData:
      authenticationType: gce
      # Optional: restrict the project dropdown to matching projects (regex supported)
      # projectListFilter: |
      #   my-project-123
      #   team-alpha-.*
      # Optional: filter log buckets (prefix with ! to exclude)
      # logBucketFilter: |
      #   !.*/_Default
      # Optional: custom universe domain for sovereign cloud environments
      # universeDomain: googleapis.com
```

To provision a service account key (JWT authentication) instead, supply the fields from the service account JSON file. The private key goes in `secureJsonData`, either inline or via a file path:

```yaml
apiVersion: 1

datasources:
  - name: Google Cloud Logging
    type: googlecloud-logging-datasource
    access: proxy
    jsonData:
      authenticationType: jwt
      clientEmail: my-service-account@my-project.iam.gserviceaccount.com
      defaultProject: my-project
      tokenUri: https://oauth2.googleapis.com/token
      # Alternative to secureJsonData.privateKey: read the PEM file from disk
      # privateKeyPath: /etc/secrets/gcp-logging-private-key.pem
    secureJsonData:
      privateKey: $__file{/etc/secrets/gcp-logging-private-key.pem}
```

The same `jsonData` and `secureJsonData` fields work with the Grafana Terraform provider's `grafana_data_source` resource. The `privateKey` value is the `private_key` field of the service account JSON file. It may be passed with real line breaks or with the literal `\n` escape sequences as they appear in the JSON file; both are accepted.

### Supported variables

The plugin currently supports variables for logging scopes. For example, you can define a project variable and switch between projects. The following screenshot shows an example using project, bucket, and view.

![template variables](https://github.com/GoogleCloudPlatform/cloud-logging-data-source-plugin/blob/main/src/img/template_vars.png?raw=true)

Below is an example of defining a variable for log views. ![define a variable](https://github.com/GoogleCloudPlatform/cloud-logging-data-source-plugin/blob/main/src/img/template_query_vars.png?raw=true)

### Alerting

[Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/fundamentals/data-source-alerting/) is not directly supported due to how [Logging Query Language](https://cloud.google.com/logging/docs/view/logging-query-language) works on Google Cloud. If you need to create alerts based on logs, consider using [Log-based metrics](https://cloud.google.com/logging/docs/logs-based-metrics) and a [Cloud Monitoring data source](https://grafana.com/docs/grafana/latest/datasources/google-cloud-monitoring/).

## Licenses

Cloud Logging Logo (`src/img/logo.svg`) is from Google Cloud's [Official icons and sample diagrams](https://cloud.google.com/icons)

As commented in the code, `JWTForm` and `JWTConfigEditor` are largely based on the Apache-2.0 licensed [grafana-google-sdk-react](https://github.com/grafana/grafana-google-sdk-react/).
