This guide shows examples of how to replay 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 Pub/Sub gcloud commands.
Create and Seek to Snapshots
Create a topic and a subscription. For better interactivity, use a short acknowledgement deadline:
gcloud pubsub topics create seek-demo-topic gcloud 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:
gcloud pubsub snapshots create my-snapshot --subscription=seek-demo-sub gcloud pubsub snapshots list
Now publish, pull, and acknowledge a message:
gcloud pubsub topics publish seek-demo-topic --message 'hello, world' gcloud pubsub subscriptions pull --auto-ack seek-demo-sub
Note that subsequent pulls yield no new messages (some transient duplicates are possible):
gcloud 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:
gcloud pubsub subscriptions seek seek-demo-sub --snapshot=my-snapshot gcloud 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:
gcloud pubsub subscriptions create seek-demo-sub2 --topic=seek-demo-topic --ack-deadline=10 gcloud 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:
gcloud pubsub subscriptions pull seek-demo-sub2 --auto-ack
When you are done with the snapshot, clean up:
gcloud 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. If
retain-acked-messages is set, Pub/Sub retains acknowledged
messages for 7 days.
You only need to do this step if you intend to seek to a timestamp, not to a snapshot.
gcloud pubsub subscriptions update seek-demo-sub --retain-acked-messages
Now publish, pull, and acknowledge a message:
gcloud pubsub topics publish seek-demo-topic --message 'hello, world' gcloud pubsub subscriptions pull --auto-ack seek-demo-sub
The next pull should return no messages:
gcloud 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:
export TS_FORMAT=%Y-%m-%dT%H:%M:%SZ gcloud pubsub subscriptions seek seek-demo-sub --time=$(date -u -d '-10 min' +$TS_FORMAT)
A subsequent pull should yield the message again:
gcloud 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:
gcloud pubsub topics publish seek-demo-topic --message 'hello, world' gcloud 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:
gcloud 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:
How did it go?
Note that additional resources and links are available on the Pub/Sub support page.
What's next?
See Replaying and discarding messages.