Forwarding to dead-letter topics

You can configure subscriptions with dead-letter topics (also known as dead-letter queues). When a message can't be acknowledged, Pub/Sub can forward the message to a dead-letter topic. The dead-letter topic stores the message for you to access later.

To forward messages to a dead-letter topic, complete the following steps:

  1. Create a topic.
  2. Add the topic to a subscription as a dead-letter topic.
  3. Permit Pub/Sub to publish messages to the dead-letter topic and remove forwarded messages from the subscription.

Adding dead-letter topics

You can add a dead-letter topic to a subscription when you create or update subscriptions. If you set a dead-letter topic, you can also specify the following options:

  • Maximum number of delivery attempts. The default is 5 delivery attempts and you can specify between 5-100 delivery attempts.

  • Project with the dead-letter topic. This option is required if the dead-letter topic is in a different project than the subscription.

You can create a subscription with a dead-letter topic using the Cloud Console or gcloud command-line tool.

Console

To create a subscription with a dead-letter topic, complete the following steps.

  1. In the Cloud Console, go to the Subscriptions page.

    Go to the Subscriptions page

  2. Click Create subscription.

  3. Enter the Subscription ID.

  4. Choose or create a topic from the drop-down menu. The subscription receives messages from the topic.

  5. In the Dead lettering section, select Enable dead lettering.

  6. Choose or create a dead-letter topic from the drop-down menu.

  7. Optional: In the Maximum delivery attempts field, specify an integer between 5 and 100.

  8. Click Create.

gcloud

To create subscription with a dead-letter topic, run the gcloud pubsub subscriptions create command:

gcloud pubsub subscriptions create subscription-id \
  --topic=topic-id \
  --dead-letter-topic=dead-letter-topic-id \
  --max-delivery-attempts=max-delivery-attempts \
  [--dead-letter-topic-project=dead-letter-topic-project]

You can update subscription with a dead-letter topic using the Cloud Console or gcloud command-line tool.

Console

To add a dead-letter topic to a subscription, complete the following steps.

  1. In the Cloud Console, go to the Subscriptions page.

    Go to the Subscriptions page

  2. Next to the subscription to update, click More actions.

  3. In the context menu, select Edit.

    The context menu with the Edit option highlighted.

  4. In the Dead lettering section, select Enable dead lettering.

  5. Choose or create a dead-letter topic from the drop-down menu.

  6. Optional: In the Maximum delivery attempts field, specify an integer between 5 and 100.

  7. Click Update.

gcloud

To update subscription with a dead-letter topic, run the gcloud pubsub subscriptions update command:

gcloud pubsub subscriptions update subscription-id \
  --dead-letter-topic=dead-letter-topic-id \
  [--max-delivery-attempts=max-delivery-attempts] \
  [--dead-letter-topic-project=dead-letter-topic-project]

Granting forwarding permissions

To forward messages to dead-letter topics, Pub/Sub must have permission to do the following:

Pub/Sub creates and maintains a service account for each project: service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com. You can grant forwarding permissions by assigning publisher and subscriber roles to this service account. If you configured the subscription using Cloud Console, the roles are granted automatically.

Assigning Pub/Sub the publisher role

To grant Pub/Sub permission to publish messages to the dead-letter topic, run the following command:

PUBSUB_SERVICE_ACCOUNT="service-${project-number}@gcp-sa-pubsub.iam.gserviceaccount.com"

gcloud pubsub topics add-iam-policy-binding dead-letter-topic-id \
    --member="serviceAccount:$PUBSUB_SERVICE_ACCOUNT"\
    --role="roles/pubsub.publisher"

Assigning Pub/Sub the subscriber role

To grant Pub/Sub permission to acknowledge forwarded messages and remove them from the subscription, run the following command:

PUBSUB_SERVICE_ACCOUNT="service-${project-number}@gcp-sa-pubsub.iam.gserviceaccount.com"

gcloud pubsub subscriptions add-iam-policy-binding subscription-id \
    --member="serviceAccount:$PUBSUB_SERVICE_ACCOUNT"\
    --role="roles/pubsub.subscriber"

Tracking delivery attempts

After adding a dead-letter topic to a subscription, messages include the delivery_attempt field. The delivery_attempt field tallies the number of delivery attempts to subscribers.

Managing forwarded messages

After forwarding messages, the Pub/Sub service removes the forwarded messages from the subscription with the dead-letter topic. You can monitor forwarded messages with Cloud Monitoring.

Forwarded messages adhere to the expiration policies of the subscriptions to the dead-letter topic instead of the expiration policy of the subscription from which the message was forwarded.

Monitoring forwarded messages

The subscription/dead_letter_message_count metric from the subscription with the dead-letter topic records the number of messages forwarded to the dead-letter topic.

For details, see Monitoring dead-letter topics.

Removing dead-letter topics

You can remove dead-letter topics from a subscription with the Cloud Console or gcloud command-line tool.

Console

To remove dead-letters topic from a subscription, complete the following steps.

  1. In the Cloud Console, go to the Subscriptions page.

    Go to the Subscriptions page

  2. In the list of subscriptions, click next to the subscription to update.

  3. From the context menu, select Edit.

    The context menu with the Edit option highlighted.

  4. In the Dead lettering section, clear Enable dead lettering.

  5. Click Update.

gcloud

To remove dead-letter topics from a subscription, run the gcloud pubsub subscriptions update command:

gcloud pubsub subscriptions update subscription-id \
  --clear-dead-letter-policy

Pricing

The Pub/Sub service forwards messages to dead-letter topics, which incurs the following fees:

  • Publish fees billed to the billing account associated with the project containing the dead-letter topic.
  • Subscription egress fees billed to the billing account associated with the project containing the subscription with the dead-letter topic.

If the message storage location policy of the dead-letter topic does not allow the region containing the subscription with the dead-letter topic, publish egress fees also apply. Publish egress fees are billed to the billing account associated with the project containing the dead-letter topic.

For more information, see Pricing.

What's next