> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Googlecloudspanner

> OpenTelemetry receiver for Googlecloudspanner

# Googlecloudspanner Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@dashpole](https://github.com/dashpole), [@KiranmayiB](https://github.com/KiranmayiB), [@nsj07](https://github.com/nsj07)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/googlecloudspannerreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-beta-green)

## Overview

> **Note:** The receiver type has been renamed from `googlecloudspanner` to `google_cloud_spanner` to follow the
> snake\_case naming convention. The old name `googlecloudspanner` is preserved as a deprecated alias and
> will continue to work, but a deprecation warning will be logged at startup. Please update your
> configuration to use `google_cloud_spanner:`.

Google Cloud Spanner enable you to investigate issues with your database
by exposing via [Total and Top N built-in tables](https://cloud.google.com/spanner/docs/introspection):

* Query statistics
* Read statistics
* Transaction statistics
* Lock statistics
* and others

*Note*: Total and Top N built-in tables are used with 1 minute statistics granularity.

The ultimate goal of Google Cloud Spanner Receiver is to collect and transform those statistics into metrics
that would be convenient for further analysis by users.

## Getting Started

The following configuration example is:

```yaml theme={null}
receivers:
  google_cloud_spanner:
    collection_interval: 60s
    initial_delay: 1s
    top_metrics_query_max_rows: 100
    backfill_enabled: true
    cardinality_total_limit: 200000
    hide_topn_lockstats_rowrangestartkey: false
    truncate_text: false
    projects:
      - project_id: "spanner project 1"
        service_account_key: "path to spanner project 1 service account json key"
        instances:
          - instance_id: "id1"
            databases:
              - "db11"
              - "db12"
          - instance_id: "id2"
            databases:
              - "db21"
              - "db22"
      - project_id: "spanner project 2"
        service_account_key: "path to spanner project 2 service account json key"
        instances:
          - instance_id: "id3"
            databases:
              - "db31"
              - "db32"
          - instance_id: "id4"
            databases:
              - "db41"
              - "db42"
```

Brief description of configuration properties:

* **google\_cloud\_spanner** - name of the Cloud Spanner Receiver related section in OpenTelemetry collector configuration file
* **collection\_interval** - this receiver runs periodically. Each time it runs, it queries Google Cloud Spanner, creates metrics, and sends them to the next consumer (default: 1 minute). **It is not recommended to change the default value of collection interval, since new values for metrics in the Spanner database appear only once a minute.**
* **initial\_delay**  defines how long this receiver waits before starting.
* **top\_metrics\_query\_max\_rows** - max number of rows to fetch from Top N built-in table(100 by default)
* **backfill\_enabled** - turn on/off 1-hour data backfill(by default it is turned off)
* **cardinality\_total\_limit** - limit of active series per 24 hours period. If specified, turns on cardinality filtering and handling. If zero or not specified, cardinality is not handled. You can read [this document](cardinality.md) for more information about cardinality handling and filtering.
* **hide\_topn\_lockstats\_rowrangestartkey** - if true, masks PII (key values) in row\_range\_start\_key label for the "top minute lock stats" metric
* **truncate\_text** - if true, the query text is truncated to 1024 characters.
* **projects** - list of GCP projects
  * **project\_id** - identifier of GCP project
  * **service\_account\_key** - path to service account JSON key It is highly recommended to set this property to the correct value. In case it is empty, the [Application Default Credentials](https://google.aip.dev/auth/4110) will be used for the database connection.
  * **instances** - list of Google Cloud Spanner instance for connection
    * **instance\_id** - identifier of Google Cloud Spanner instance
    * **databases** - list of databases used from this instance

## Configuration

### Example Configuration

```yaml theme={null}
google_cloud_spanner:
  collection_interval: 120s
  top_metrics_query_max_rows: 10
  backfill_enabled: true
  cardinality_total_limit: 200000
  hide_topn_lockstats_rowrangestartkey: true
  truncate_text: true
  projects:
    - project_id: "spanner project 1"
      service_account_key: "path to spanner project 1 service account json key"
      instances:
        - instance_id: "id1"
          databases:
            - "db11"
            - "db12"
        - instance_id: "id2"
          databases:
            - "db21"
            - "db22"
    - project_id: "spanner project 2"
      service_account_key: "path to spanner project 2 service account json key"
      instances:
        - instance_id: "id3"
          databases:
            - "db31"
            - "db32"
        - instance_id: "id4"
          databases:
            - "db41"
            - "db42"
```

***

*Last generated: 2026-07-06*