---
title: Google Cloud Pubsub
description: >-
  A scalable, flexible, and reliable enterprise message-oriented middleware
  solution in Google Cloud.
breadcrumbs: Docs > Integrations > Google Cloud Pubsub
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Google Cloud Pubsub

{% callout %}
# Important note for users on the following Datadog sites: us2.ddog-gov.com

{% alert level="info" %}
To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator.

To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com).
{% /alert %}

{% /callout %}

## Overview{% #overview %}

Google Cloud Pub/Sub brings the scalability, flexibility, and reliability of enterprise message-oriented middleware to the cloud.

Get metrics from Google Pub/Sub to:

- Visualize the performance of your Pub/Sub topics and subscriptions.
- Correlate the performance of your Pub/Sub topics and subscriptions with your applications.

## Setup{% #setup %}

### Metric collection{% #metric-collection %}

#### Installation{% #installation %}

If you haven't already, set up the [Google Cloud Platform integration](https://docs.datadoghq.com/integrations/google-cloud-platform.md) first. There are no other installation steps.

#### Configuration{% #configuration %}

To collect custom Pub/Sub labels as tags, enable the cloud asset inventory permission on the Datadog service account in Google Cloud.

### Log collection{% #log-collection %}

Google Cloud Pub/Sub logs are collected with Google Cloud Logging and sent to a Dataflow job through a Cloud Pub/Sub topic. If you haven't already, [set up logging with the Datadog Dataflow template](https://docs.datadoghq.com/integrations/google-cloud-platform.md#log-collection).

Once this is done, export your Google Cloud Pub/Sub logs from Google Cloud Logging to the Pub/Sub topic:

1. Go to the [Google Cloud Logging page](https://console.cloud.google.com/logs/viewer) and filter the Google Cloud Pub/Sub logs.
1. Click **Create Sink** and name the sink accordingly.
1. Choose "Cloud Pub/Sub" as the destination and select the Pub/Sub topic that was created for that purpose. **Note**: The Pub/Sub topic can be located in a different project.
1. Click **Create** and wait for the confirmation message to show up.

## Data Collected{% #data-collected %}

### Metrics{% #metrics %}

|  |
|  |
| **gcp.pubsub.snapshot.backlog_bytes**(gauge)                                          | Total byte size of the messages retained in a snapshot.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **gcp.pubsub.snapshot.backlog_bytes_by_region**(gauge)                              | Total byte size of the messages retained in a snapshot, broken down by Cloud region.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **gcp.pubsub.snapshot.config_updates_count**(count)                                  | Cumulative count of configuration operations, grouped by operation type and result.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **gcp.pubsub.snapshot.num_messages**(gauge)                                           | Number of messages retained in a snapshot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **gcp.pubsub.snapshot.num_messages_by_region**(gauge)                               | Number of messages retained in a snapshot, broken down by Cloud region.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **gcp.pubsub.snapshot.oldest_message_age**(gauge)                                    | Age (in seconds) of the oldest message retained in a snapshot.*Shown as second*                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **gcp.pubsub.snapshot.oldest_message_age_by_region**(gauge)                        | Age (in seconds) of the oldest message retained in a snapshot, broken down by Cloud region.*Shown as second*                                                                                                                                                                                                                                                                                                                                                                                                          |
| **gcp.pubsub.subscription.ack_latencies.avg**(gauge)                                  | Distribution of ack latencies in milliseconds. The ack latency is the time between when Cloud Pub/Sub sends a message to a subscriber client and when Cloud Pub/Sub receives an Acknowledge request for that message.*Shown as millisecond*                                                                                                                                                                                                                                                                           |
| **gcp.pubsub.subscription.ack_latencies.samplecount**(count)                          | Distribution of ack latencies in milliseconds. The ack latency is the time between when Cloud Pub/Sub sends a message to a subscriber client and when Cloud Pub/Sub receives an Acknowledge request for that message.                                                                                                                                                                                                                                                                                                 |
| **gcp.pubsub.subscription.ack_latencies.sumsqdev**(gauge)                             | Sum of Squared Deviation for ack latencies.*Shown as millisecond*                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **gcp.pubsub.subscription.ack_message_count**(count)                                 | Cumulative count of messages acknowledged by Acknowledge requests, grouped by delivery type. Dead-lettered messages may show up as pull acks.                                                                                                                                                                                                                                                                                                                                                                         |
| **gcp.pubsub.subscription.backlog_bytes**(gauge)                                      | Total byte size of the unacknowledged messages (a.k.a. backlog messages) in a subscription.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                            |
| **gcp.pubsub.subscription.billable_bytes_by_region**(gauge)                         | Total byte size of the billable messages in a subscription, broken down by Cloud region and type. Please refer to [https://cloud.google.com/pubsub/pricing#storage_costs](https://cloud.google.com/pubsub/pricing#storage_costs) to understand the pricing for retaining unacknowledged messages in subscriptions for more than 24 hours.*Shown as byte*                                                                                                                                                              |
| **gcp.pubsub.subscription.byte_cost**(count)                                          | Cumulative cost of operations, measured in bytes. This is used to measure quota utilization.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                           |
| **gcp.pubsub.subscription.config_updates_count**(count)                              | Cumulative count of configuration operations for each subscription, grouped by operation type and result.                                                                                                                                                                                                                                                                                                                                                                                                             |
| **gcp.pubsub.subscription.dead_letter_message_count**(count)                        | Cumulative count of messages published to dead letter topic, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **gcp.pubsub.subscription.delivery_latency_health_score**(gauge)                    | A score that measures the health of a subscription over a 10 minute rolling window.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **gcp.pubsub.subscription.exactly_once_warning_count**(count)                       | Count of instances (acks and modacks that may have failed) that may lead to message redeliveries.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **gcp.pubsub.subscription.expired_ack_deadlines_count**(count)                      | Cumulative count of messages whose ack deadline expired while the message was outstanding to a subscriber client.                                                                                                                                                                                                                                                                                                                                                                                                     |
| **gcp.pubsub.subscription.export_push_subscription_details**(gauge)                 | Type and state of the export push subscription.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **gcp.pubsub.subscription.mod_ack_deadline_message_count**(count)                  | Cumulative count of messages whose deadline was updated by ModifyAckDeadline requests, grouped by delivery type.                                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.subscription.mod_ack_deadline_request_count**(count)                  | Cumulative count of ModifyAckDeadline requests, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **gcp.pubsub.subscription.mod_ack_latencies.avg**(count)                             | The average distribution of ModAck latencies. For each message delivery attempt, the ModAck latency is the duration between when the CPS service delivers the message to a subscriber client and when the CPS service receives a ModAck request for that message.*Shown as millisecond*                                                                                                                                                                                                                               |
| **gcp.pubsub.subscription.mod_ack_latencies.samplecount**(count)                     | Distribution of ModAck latencies. For each message delivery attempt, the ModAck latency is the duration between when the CPS service delivers the message to a subscriber client and when the CPS service receives a ModAck request for that message (note that this means this metric may be recorded multiple times per delivery attempt). If this metric is growing, it indicates that the subscriber is repeatedly extending the acknowledgement deadline for a message (i.e., it is holding on to that message). |
| **gcp.pubsub.subscription.mod_ack_latencies.sumsqdev**(count)                        | Distribution of ModAck latencies. For each message delivery attempt, the ModAck latency is the duration between when the CPS service delivers the message to a subscriber client and when the CPS service receives a ModAck request for that message (note that this means this metric may be recorded multiple times per delivery attempt). If this metric is growing, it indicates that the subscriber is repeatedly extending the acknowledgement deadline for a message (i.e., it is holding on to that message). |
| **gcp.pubsub.subscription.nack_requests**(gauge)                                      | Cumulative count of messages that were nacked. One message nacked multiple times will be counted multiple times.                                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.subscription.num_outstanding_messages**(gauge)                          | Number of messages delivered to a subscription's push endpoint, but not yet acknowledged.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **gcp.pubsub.subscription.num_retained_acked_messages**(gauge)                      | Number of acknowledged messages retained in a subscription.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **gcp.pubsub.subscription.num_retained_acked_messages_by_region**(gauge)          | Number of acknowledged messages retained in a subscription, broken down by Cloud region.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **gcp.pubsub.subscription.num_unacked_messages_by_region**(gauge)                  | Number of unacknowledged messages in a subscription, broken down by Cloud region.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **gcp.pubsub.subscription.num_undelivered_messages**(gauge)                          | Number of unacknowledged messages (a.k.a. backlog messages) in a subscription.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **gcp.pubsub.subscription.oldest_retained_acked_message_age**(gauge)               | Age (in seconds) of the oldest acknowledged message retained in a subscription.*Shown as second*                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.subscription.oldest_retained_acked_message_age_by_region**(gauge)   | Age (in seconds) of the oldest acknowledged message retained in a subscription, broken down by Cloud region.*Shown as second*                                                                                                                                                                                                                                                                                                                                                                                         |
| **gcp.pubsub.subscription.oldest_unacked_message_age**(gauge)                       | Age (in seconds) of the oldest unacknowledged message (a.k.a. backlog message) in a subscription.*Shown as second*                                                                                                                                                                                                                                                                                                                                                                                                    |
| **gcp.pubsub.subscription.oldest_unacked_message_age_by_region**(gauge)           | Age (in seconds) of the oldest unacknowledged message in a subscription, broken down by Cloud region.*Shown as second*                                                                                                                                                                                                                                                                                                                                                                                                |
| **gcp.pubsub.subscription.open_streaming_pulls**(gauge)                              | Number of open StreamingPull streams per subscription, grouped by status.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **gcp.pubsub.subscription.pull_ack_request_count**(count)                           | Cumulative count of acknowledge requests, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **gcp.pubsub.subscription.pull_request_count**(count)                                | Cumulative count of pull requests, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **gcp.pubsub.subscription.push_request_count**(count)                                | Cumulative count of push attempts, grouped by result. Unlike pulls, the push server implementation does not batch user messages. So each request only contains one user message. The push server retries on errors, so a given user message can appear multiple times.                                                                                                                                                                                                                                                |
| **gcp.pubsub.subscription.push_request_latencies.avg**(gauge)                        | Distribution of push request latencies (in microseconds), grouped by result.*Shown as microsecond*                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **gcp.pubsub.subscription.push_request_latencies.samplecount**(count)                | Distribution of push request latencies (in microseconds), grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **gcp.pubsub.subscription.push_request_latencies.sumsqdev**(gauge)                   | Sum of Squared Deviation for push request latencies.*Shown as microsecond*                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **gcp.pubsub.subscription.retained_acked_bytes**(gauge)                              | Total byte size of the acknowledged messages retained in a subscription.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **gcp.pubsub.subscription.retained_acked_bytes_by_region**(gauge)                  | Total byte size of the acknowledged messages retained in a subscription, broken down by Cloud region.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                  |
| **gcp.pubsub.subscription.seek_request_count**(count)                                | Cumulative count of seek attempts, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **gcp.pubsub.subscription.sent_message_count**(count)                                | Cumulative count of messages sent by Cloud Pub/Sub to subscriber clients.*Shown as message*                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **gcp.pubsub.subscription.streaming_pull_ack_request_count**(count)                | Cumulative count of streaming pull requests with non-empty acknowledge ids, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **gcp.pubsub.subscription.streaming_pull_mod_ack_deadline_request_count**(count) | Cumulative count of streaming pull requests with non-empty ModifyAckDeadline fields, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                               |
| **gcp.pubsub.subscription.streaming_pull_response_count**(count)                    | Cumulative count of streaming pull responses, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.subscription.unacked_bytes_by_region**(gauge)                          | Total byte size of the unacknowledged messages in a subscription, broken down by Cloud region.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                         |
| **gcp.pubsub.topic.byte_cost**(count)                                                 | Cost of operations, measured in bytes. This is used to measure utilization for quotas.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **gcp.pubsub.topic.config_updates_count**(count)                                     | Cumulative count of configuration operations, grouped by operation type and result.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **gcp.pubsub.topic.ingestion_byte_count**(count)                                     | Byte count of ingested messages per ingestion source type and import partition (e.g. AWS Kinesis shard id).*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                            |
| **gcp.pubsub.topic.ingestion_data_source_state**(gauge)                             | State of the ingestion data source per ingestion source type.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **gcp.pubsub.topic.ingestion_failure_count**(count)                                  | Number of errors encountered when ingesting data per ingestion source type, source name, import partition, and reason for error.                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.topic.ingestion_message_count**(count)                                  | Number of ingested messages per ingestion source type and import partition (e.g. AWS Kinesis shard id).                                                                                                                                                                                                                                                                                                                                                                                                               |
| **gcp.pubsub.topic.message_sizes.avg**(gauge)                                         | Distribution of publish message sizes (in bytes).*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.topic.message_sizes.samplecount**(count)                                 | Distribution of publish message sizes (in bytes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **gcp.pubsub.topic.message_sizes.sumsqdev**(gauge)                                    | Sum of Squared Deviation for publish message sizes.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **gcp.pubsub.topic.num_retained_acked_messages_by_region**(gauge)                 | Number of acknowledged messages retained across all subscriptions and snapshots attached to the topic, broken down by Cloud region.                                                                                                                                                                                                                                                                                                                                                                                   |
| **gcp.pubsub.topic.num_retained_messages**(gauge)                                    | Number of messages retained in a topic.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **gcp.pubsub.topic.num_unacked_messages_by_region**(gauge)                         | Number of unacknowledged messages across all subscriptions and snapshots attached to a topic, broken down by Cloud region.                                                                                                                                                                                                                                                                                                                                                                                            |
| **gcp.pubsub.topic.oldest_retained_acked_message_age_by_region**(gauge)          | Age (in seconds) of the oldest acknowledged message retained across all subscriptions and snapshots attached to a topic, broken down by Cloud region.*Shown as second*                                                                                                                                                                                                                                                                                                                                                |
| **gcp.pubsub.topic.oldest_retained_message_age**(gauge)                             | Age (in seconds) of the oldest message retained in a topic.*Shown as second*                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **gcp.pubsub.topic.oldest_unacked_message_age_by_region**(gauge)                  | Age (in seconds) of the oldest unacknowledged message across all subscriptions and snapshots attached to a topic, broken down by Cloud region.*Shown as second*                                                                                                                                                                                                                                                                                                                                                       |
| **gcp.pubsub.topic.retained_acked_bytes_by_region**(gauge)                         | Total byte size of the acknowledged messages retained across all subscriptions and snapshots attached to a topic, broken down by Cloud region.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                         |
| **gcp.pubsub.topic.retained_bytes**(gauge)                                            | Total byte size of the messages retained in a topic.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **gcp.pubsub.topic.schema_validation_latencies.avg**(count)                          | The average distribution of schema validation latencies in milliseconds.*Shown as millisecond*                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **gcp.pubsub.topic.schema_validation_latencies.samplecount**(count)                  | Distribution of schema validation latencies in milliseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **gcp.pubsub.topic.schema_validation_latencies.sumsqdev**(count)                     | Distribution of schema validation latencies in milliseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **gcp.pubsub.topic.send_request_count**(count)                                       | Cumulative count of publish requests, grouped by result.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **gcp.pubsub.topic.send_request_latencies.avg**(gauge)                               | Distribution of publish request latencies in microseconds.*Shown as microsecond*                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.topic.send_request_latencies.samplecount**(count)                       | Distribution of publish request latencies in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **gcp.pubsub.topic.send_request_latencies.sumsqdev**(gauge)                          | Sum of Squared Deviation for topic send request latencies.*Shown as microsecond*                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **gcp.pubsub.topic.unacked_bytes_by_region**(gauge)                                 | Total byte size of the unacknowledged messages across all subscriptions and snapshots attached to the topic, broken down by Cloud region.*Shown as byte*                                                                                                                                                                                                                                                                                                                                                              |

### Events{% #events %}

The Google Cloud Pub/Sub integration does not include any events.

### Service Checks{% #service-checks %}

The Google Cloud Pub/Sub integration does not include any service checks.

## Troubleshooting{% #troubleshooting %}

Need help? Contact [Datadog support](https://docs.datadoghq.com/help/).