Using Seek to Replay Messages

This guide shows examples of how to replay Cloud Pub/Sub API messages.

Using the gcloud Command-Line Interface

The easiest way to use gcloud is in the Cloud Shell . You can also use the command line tool that comes with the Cloud SDK. Setup prerequisites are met automatically for the Cloud SDK if you create a brand new Compute Engine machine instance with access scopes including all Cloud APIs and the default Debian image. The simplest way to create it is via the Compute Engine UI. For the rest of this document, we will assume that you are using one of these command line tools.

For more information about using gcloud, see the gcloud quickstart. Also see the gcloud pubsub section in the gcloud reference for a complete list of Cloud Pub/Sub gcloud commands.

Create and Seek to Snapshots

Create a topic and a subscription. For better interactivity, use a short acknowledgement deadline:

alias pubsub='gcloud beta pubsub'
pubsub topics create seek-demo-topic
pubsub subscriptions create seek-demo-sub --topic=seek-demo-topic --ack-deadline=10

So far, no messages in the subscription have been acknowledged. Capture this state by creating a snapshot:

pubsub snapshots create my-snapshot --subscription=seek-demo-sub
pubsub snapshots list

Now publish, pull, and acknowledge a message:

pubsub topics publish seek-demo-topic --message 'hello, world'
pubsub subscriptions pull --auto-ack seek-demo-sub

Note that subsequent pulls yield no new messages (some transient duplicates are possible):

pubsub subscriptions pull --auto-ack seek-demo-sub

You can recover the message by seeking the subscription to the snapshot. Note that the message may not be delivered instantly: Pub/Sub does not guarantee message delivery latency. However, what is guaranteed is that the messages retained in the snapshot will be eventually delivered at least once:

pubsub subscriptions seek seek-demo-sub --snapshot=my-snapshot
pubsub subscriptions pull seek-demo-sub --auto-ack

Note that you can seek other subscriptions to the same snapshot, as long as the subscription’s topic is the same as the snapshot’s topic:

pubsub subscriptions create seek-demo-sub2 --topic=seek-demo-topic --ack-deadline=10
pubsub subscriptions seek seek-demo-sub2 --snapshot=my-snapshot

Pulling from seek-demo-sub2 will now yield messages which were published before seek-demo-sub2 was created:

pubsub subscriptions pull seek-demo-sub2 --auto-ack

When you are done with the snapshot, clean up:

pubsub snapshots delete my-snapshot

Seek to a timestamp

Another way to replay messages that have been acknowledged is to seek to a timestamp. To seek to a timestamp, you must first configure the subscription to retain acknowledged messages using retain-acked-messages. By default, messages are retained for 7 days. You can set the duration to be shorter (but not shorter than 10 minutes) by using message-retention-duration. For more information, see subscription configuration in Replaying & Discarding Messages.

You only need to do this step if you intend to seek to a timestamp, not to a snapshot.

pubsub subscriptions update seek-demo-sub --retain-acked-messages

Now publish, pull, and acknowledge a message:

pubsub topics publish seek-demo-topic --message 'hello, world'
pubsub subscriptions pull --auto-ack seek-demo-sub

The next pull should return no messages:

pubsub subscriptions pull seek-demo-sub

Now seek the subscription back in time to recover the message. Note that the date arithmetic flags differ between the GNU and BSD (MacOS) versions of the date command:

TS_FORMAT=%Y-%m-%dT%H:%M:%SZ
pubsub subscriptions seek seek-demo-sub --time=$(date -u -d '-10 min' +$TS_FORMAT)

A subsequent pull should yield the message again:

pubsub subscriptions pull --auto-ack seek-demo-sub

You can also use seek to skip delivery of all messages published before some point in time, such as the current time. To do this, seek the subscription to the current time to mark as acknowledged all past messages:

pubsub topics publish seek-demo-topic --message 'hello, world'
pubsub subscriptions seek seek-demo-sub --time=$(date -u +$TS_FORMAT)

After some propagation delay (~60 seconds), the message will no longer be delivered. You can check this by repeatedly executing the pull command without acknowledging the message:

pubsub subscriptions pull seek-demo-sub

Using the Cloud Console

You can create snapshots, or seek to existing snapshots, in the subscription detail page of the Cloud Console. For snapshot naming rules, see Resource names.

The seek dialog offers a choice of seeking to a time or to a snapshot:

You can also manage snapshots in the details page of an individual topic:

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Pub/Sub Documentation