<br />

Use the `gcpdiag` tool to discover and fix potential
delivery issues for pull subscriptions.

## Use the `gcpdiag` tool

[`gcpdiag`](https://gcpdiag.dev)
is an open source tool. It is not an officially supported Google Cloud product.
You can use the `gcpdiag` tool to help you identify and fix Google Cloud
project issues. For more information, see the
[gcpdiag project on GitHub](https://github.com/GoogleCloudPlatform/gcpdiag/#gcpdiag---diagnostics-for-google-cloud-platform).
The `gcpdiag` tool helps you discover Pub/Sub
pull delivery issues by performing the following checks:

- **Quota errors:** Evaluates Logs Explorer logs to check for any quota errors in regions and zones.
- **Throughput qualification:** Performs checks on the [delivery latency health](https://docs.cloud.google.com/pubsub/docs/monitoring.md.txt#delivery_latency_health) of a subscription.

For a list of `gcpdiag` pull delivery evaluation steps, see
[Potential steps](https://gcpdiag.dev/runbook/diagnostic-trees/pubsub/pull-subscription-delivery/#potential-steps).

### Run the `gcpdiag` command

You can run the `gcpdiag` command from Google Cloud CLI or within
a [Docker](https://www.docker.com/) container.

## Google Cloud console

1. Complete and then copy the following command.

```console
gcpdiag runbook pubsub/pull-subscription-delivery \
  --project=PROJECT_ID \
  --parameter subscription_name=SUBSCRIPTION_NAME
```
2. Open the Google Cloud console and activate Cloud Shell.
[Open Cloud console](https://console.cloud.google.com/cloudpubsub/topic/list?cloudshell=true+?cloudshell%3Dtrue)
3. Paste the copied command.
4. Run the `gcpdiag` command, which downloads the `gcpdiag` docker image, and then performs diagnostic checks. If applicable, follow the output instructions to fix failed checks.

## Docker

You can [run `gcpdiag` using a wrapper](https://github.com/GoogleCloudPlatform/gcpdiag?tab=readme-ov-file#installation) that starts `gcpdiag` in a
[Docker](https://www.docker.com/) container. Docker or
[Podman](https://podman.io/) must be installed.

1. Copy and run the following command on your local workstation.

   ```console
   curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag
   ```
2. Execute the `gcpdiag` command.

   ```console
   ./gcpdiag runbook pubsub/pull-subscription-delivery \
     --project=PROJECT_ID \
     --parameter subscription_name=SUBSCRIPTION_NAME
   ```
View [available parameters](https://gcpdiag.dev/runbook/diagnostic-trees/pubsub/pull-subscription-delivery/#parameters) for this runbook.

Replace the following:

- <var class="readonly" translate="no">PROJECT_ID</var>: The ID of the project to evaluate
- <var class="readonly" translate="no">SUBSCRIPTION_NAME</var>: The name of the subscription to evaluate in your project

Useful flags:

- `--universe-domain`: If applicable, the [Trusted Partner Sovereign Cloud](https://cloud.google.com/blog/products/identity-security/new-sovereign-controls-for-gcp-via-assured-workloads) domain hosting the resource
- `--parameter` or `-p`: Runbook parameters

For a list and description of all `gcpdiag` tool flags, see the
[`gcpdiag` usage instructions](https://github.com/GoogleCloudPlatform/gcpdiag?tab=readme-ov-file#usage).

## Read related information

- [Pub/Sub pull subscription common issues](https://docs.cloud.google.com/pubsub/docs/pull-troubleshooting.md.txt)