Troubleshooting a subscription with Single Message Transforms (SMTs)

This page provides some common troubleshooting tips for subscriptions with SMTs.

Monitor SMTs

To understand the performance and impact of SMTs on a subscription, use the following monitoring metrics:

The subscription/message_transform_latencies metric measures how long it takes for SMTs to be applied to a message. The metric measures only the SMT latency and does not include other parts of the message delivery time.

The metric provides two key labels:

  • status: reports whether the transformation is successful or encountered an issue.

  • filtered: indicates if the SMT caused the message to be filtered out. When an SMT filters a message on a subscription, Pub/Sub acknowledges it, and the message is never sent to subscribers. This filtered label is true only when an SMT performs the filtering. Messages filtered using Pub/Sub's built-in filtering capabilities are not reflected in this specific metric.

The subscription/byte_cost metric is used to identify messages that are filtered by SMTs or where SMTs failed. Look for these specific values:

  • When an SMT filters a message, the operation_type is smt_subscribe_filter_drop.

  • If an SMT fails to transform a message, you see a response_code that is not OK.

A backlog is building up

If you see a backlog of messages building up in the subscription check for INVALID_ARGUMENT errors reported in subscription/message_transform_latencies.

To troubleshoot INVALID_ARGUMENT errors, add a dead-letter topic to the subscription of interest. The dead letter topic captures messages that couldn't be delivered to subscribers, along with an attribute called CloudPubSubDeadLetterSourceSMTErrorMessage that explains the failure reason.

What's next

  • If you still have issues with your subscription SMTs, see Getting support.