Send and verify events with Google Cloud Pub/Sub telemetry
Use Google Cloud Pub/Sub telemetry where your app knows the final result. Collect only the fields you need, then verify a test event before building charts.
- 1
Choose the outcome
Pub/Sub delivery reliability
- 2
Define the contract
message_id, message_type, topic, subscription, ordering_key_category, and release
- 3
Log the final result
Pub/Sub can redeliver messages; keep the provider message ID and delivery attempt separate from the final business outcome.
- 4
Check the stored event
Exercise a known fixture, then inspect pubsub_message_completed for one correctly typed terminal row.
Before you start
Before you start
- @google-cloud/pubsub and telemetry-sh initialized in a trusted publisher or subscriber
- Stable topic, subscription, message type, and logical outcome definitions
- An idempotent consumer and a documented acknowledgement or exactly-once policy
Delivery setup
Install and initialize server-side
Import telemetry-sh in server-only code and initialize it once with process.env.TELEMETRY_API_KEY. Keep ingestion credentials out of browser bundles, client-visible environment variables, source control, logs, and exception messages.
npm installation
npm install telemetry-sh- 1Create one reusable server-side client. Set its timeout and retry limit.
- 2Log an event when the operation succeeds, fails, retries, or times out.
- 3Send test events with known results and inspect the stored rows before enabling an alert.
Snippet
Start with one structured event
Add this shape where the workflow completes, fails, or retries. Then build the dashboard from real fields.
Google Cloud Pub/Sub telemetry event
await telemetry.log("pubsub_message_completed", {
message_id: message.id,
message_type: "account_export",
topic: "account-exports",
subscription: "account-export-worker",
status: "success",
delivery_attempt: message.deliveryAttempt ?? 1,
wait_ms: Date.now() - Number(message.publishTime.getTime()),
duration_ms: Math.round(performance.now() - startedAt),
acknowledged: true,
dead_lettered: false,
service: "export-worker",
release: process.env.APP_RELEASE,
});Event schema
message_id, message_type, topic, subscription, ordering_key_category, and release
status, delivery_attempt, wait_ms, duration_ms, acknowledged, and error_type
dead_lettered, published_at, account_id, service, region, and environment
Check your setup
Checkpoint 1
Pub/Sub can redeliver messages; keep the provider message ID and delivery attempt separate from the final business outcome.
Checkpoint 2
Exactly-once delivery has subscription and regional constraints, so verify the actual configuration instead of inferring it from an acknowledgement call.
Checkpoint 3
Monitor provider backlog metrics beside application outcomes, and do not copy message data, attributes with private content, or unrestricted errors into events.
Verification
Prove the event arrived
Run this after exercising known success and failure cases. Replace the fallback table name if your final event contract differs from the snippet.
Google Cloud Pub/Sub telemetry verification query
SELECT *
FROM pubsub_message_completed
ORDER BY timestamp_utc DESC
LIMIT 20;Implementation references
Review the event contract, data-safety guidance, and upstream primary documentation before enabling a new production path.
Where to log
Keep the outcome event small and recoverable
This pattern provides
- Record the outcome as an event you can query with SQL.
- Stable fields for dashboards, alerts, and cross-event correlation.
- Test events for checking success, failure, retries, and timeouts.
This pattern does not provide
- An OTLP exporter, automatic collection pipeline, or replacement for detailed traces and diagnostic logs.
- Exactly-once delivery merely because the payload contains an event ID.
- Permission to collect raw provider payloads, user content, credentials, or regulated data.
Example event schemas
Event schemas for this workflow
Check what each event records, when to send it, and which field types it needs. Review the example payload and privacy checklist before using it in production.
Use these queries in Telemetry
Learn about Alerts
Add a threshold and recipients to your reliability query to get alerts.
Related SQL recipes
More SQL recipes
Run the query using this workflow's event fields and check the example result. Save the result to a dashboard or set up an alert.
Measure queue wait time by job
Which jobs wait longest before a worker starts them?
Open recipeMeasure background job retry and failure rate
Which background jobs consume the most retries or still fail?
Open recipeMeasure dead-letter queue growth
Which queues are adding dead-letter jobs faster than they are resolving them?
Open recipeMeasure late-arriving events
Which event producers deliver data late enough to distort analysis?
Open recipeBrowse by implementation family
Compare related integration patterns
Templates to pair with this integration
Background job failure monitor
Capture queue, cron, import, billing sync, and webhook job health from the first run through retries and failures.
Open templateEvent tracking plan template
Document what each event means, who owns it, which fields it contains, and which queries depend on it. Include privacy, retention, and validation rules.
Open templateMore integrations
BullMQ queue monitoring
Measure BullMQ queue wait, execution duration, retries, failures, and dead-letter growth with SQL-ready lifecycle events.
Open guideRabbitMQ queue telemetry
Track RabbitMQ publish confirmation, delivery, acknowledgement, redelivery, queue wait, retries, and dead-letter outcomes with structured events.
Open guideAzure Service Bus telemetry
Track Azure Service Bus sends, receives, lock renewal, settlement, redelivery, deferral, and dead-letter outcomes without collecting message bodies.
Open guide