Publishers send messages to a topic. Each subscription represents an independent delivery stream, so adding a second subscription creates another consumer view rather than competing with the first subscription.
Subscribers must assume a message can arrive more than once. Acknowledgment deadlines, retries, ordering keys, retention, dead-letter handling, and idempotent side effects belong in the design before traffic grows.
Include an event ID, type, version, occurrence time, producer, subject, and payload whose meaning is documented. Consumers should ignore unknown additive fields and route incompatible versions deliberately.
Do not publish a database row dump as a permanent contract. Events should express a domain fact while respecting data minimization, retention, regional, and access requirements.
A subscriber should acknowledge only after the durable side effect succeeds. If work exceeds the deadline, use client lease management or redesign the task; acknowledging first can lose work, while never acknowledging creates a retry loop.
Store processed event IDs, use a unique business key, or perform a conditional write so a redelivery cannot charge, email, or mutate inventory twice. Exactly-once delivery features do not remove the need to reason about external side effects.
gcloud pubsub topics create orders-created
gcloud pubsub topics create orders-dead-letter
gcloud pubsub subscriptions create orders-worker \
--topic=orders-created \
--dead-letter-topic=orders-dead-letter \
--max-delivery-attempts=5 \
--min-retry-delay=10s \
--max-retry-delay=300s
gcloud pubsub subscriptions describe orders-workerMonitor oldest unacked message age, undelivered count, acknowledgment latency, push response codes, dead-letter volume, and subscriber errors. A flat publish rate can still overwhelm a consumer after a dependency slows.
Ordering keys preserve order only within a key and can concentrate throughput. Use them for a real per-entity ordering requirement, not as a global queue lock.
A Pub/Sub topic is an event address, while each subscription owns an independent delivery contract and backlog. Publishing successfully means Pub/Sub accepted the message; it does not prove that inventory changed, an email was sent, or any subscriber completed. Define the business event, producer, schema owner, event time, stable identifier, ordering key if needed, sensitivity, retention, and compatibility policy before creating the topic.
Prefer facts such as `OrderConfirmed` over commands disguised as events when multiple consumers may react independently. Include enough stable identifiers for consumers to fetch authorized state, but avoid copying sensitive records into every message without a retention and access reason. Attributes are useful for routing and filtering; the payload should remain the durable contract.
Version schemas through additive compatible changes when possible. Consumers must tolerate fields they do not know, and producers should not silently change meaning or units. Validate schemas in CI, keep representative fixtures, and announce deprecation with observed consumer inventory. A new topic is justified when authorization, retention, delivery, ownership, or compatibility boundaries genuinely differ.
By default, Pub/Sub delivery is at least once and unordered. A message can be redelivered when its acknowledgment deadline expires, the client loses connectivity, processing fails, or an acknowledgment outcome is uncertain. A subscriber should acknowledge only after the durable business effect is complete or safely recorded. Acknowledging first can lose work; acknowledging after an unsafe side effect can repeat it.
Make processing idempotent with a message or business-operation identifier stored in the same transaction as the state change where possible. Another option is an inbox table that records accepted events before work continues. Do not rely on an in-memory set because restarts and parallel consumers erase or race it. Set deduplication retention from the maximum plausible redelivery and replay window.
Exactly-once delivery is an optional pull-subscription capability with regional semantics and acknowledgment requirements. It helps subscribers determine successful acknowledgments and suppress duplicate deliveries after success, but application-side side effects still need a correct transaction boundary. It does not make calls to external payment, email, or database systems atomic with the acknowledgment.
Ordering applies among messages with the same ordering key when publishers use the feature correctly; it is not total ordering across a topic. One slow or repeatedly failing message can delay later messages for that key. Choose a key granular enough for parallelism and meaningful enough for the invariant, such as an account or aggregate ID, and avoid a constant key that serializes the entire workload.
Retry policy controls delivery delay, while retention bounds how long unacknowledged data remains available. A dead-letter topic receives messages only after forwarding is configured with the required service-agent permissions, and forwarding is best effort. The dead-letter message needs enough context for diagnosis, but operators should inspect the source event, delivery attempts, consumer release, and dependency status before replay.
Classify failures as transient, permanent for this message, poison data, dependency overload, or operator cancellation. Retry transient work with bounded exponential backoff and jitter. Send permanent failures to a review workflow promptly instead of consuming the full retry window. Replay through an idempotent path, in controlled batches, with current schema and authorization checks.
Subscriber throughput depends on message size, pull or push delivery, flow control, callback concurrency, acknowledgment behavior, quotas, and downstream capacity. Client libraries can lease acknowledgment deadlines and stream messages efficiently, but unbounded concurrency can exhaust database connections or memory. Set outstanding-message and byte limits from the slowest protected dependency.
Use push when an HTTPS endpoint can respond within the delivery contract and authenticate Pub/Sub requests. Use pull or StreamingPull when the consumer needs explicit flow control, long processing, or exactly-once support. Export subscriptions to BigQuery or Cloud Storage remove consumer code for supported sinks but have their own schema, batching, ordering, and failure behavior.
Operate from backlog age, delivery attempt patterns, expired acknowledgment deadlines, negative acknowledgments, push response codes, throughput, dead-letter volume, and end-to-end business latency. A flat backlog can still be unhealthy if no new messages arrive, while a large count may be acceptable if age stays within objective during a planned burst. Test subscriber shutdown so outstanding work is either completed and acknowledged or safely redelivered.
A replay intentionally delivers historical events to current consumers, so it needs a change plan. Define the source snapshot or retained range, destination subscription, event-time window, schema versions, affected consumers, idempotency evidence, rate limit, stop condition, and owner. Never point an untested replay directly at every production subscriber.
Run a dry sample in isolation and compare expected state changes with actual output. Consumers may have changed since the event was first published, and an old message can now violate validation or trigger a newer side effect. Route incompatible records to review rather than weakening current safeguards globally.
During production replay, cap throughput below downstream spare capacity and monitor backlog age, errors, deduplication hits, database pressure, and business totals. Pause on divergence. After completion, reconcile counts from source messages through durable effects and remove temporary subscriptions, snapshots, and elevated access.
Mark replay traffic with an attribute or isolated subscription context when consumers need separate rate limits and dashboards. Do not alter the original event meaning merely to identify the operation.
A subscriber bug requires replaying one hour of retained order events.
Constraints: Delivery is at least once and downstream email and billing calls are externally visible.
Decision: Fix the subscriber, use stable event IDs as idempotency keys, seek a test subscription first, then perform the bounded replay.
Verification: Every event is processed, duplicate counters increase harmlessly, and no order is billed or emailed twice.
Failure test: Replay the same window again and confirm state and external side effects remain unchanged.Expected evidence: Every event is processed, duplicate counters increase harmlessly, and no order is billed or emailed twice.No. Each subscription receives its own delivery stream for messages published to the topic. Multiple subscribers on one subscription share that subscription backlog.
Cloud Tasks fits explicit task dispatch to an HTTP target with scheduling and per-task control. Pub/Sub fits event distribution where publishers should not own a specific consumer endpoint.
Explore 500+ free tutorials across 20+ languages and frameworks.