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.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Troubleshooting a subscription with Single Message Transforms (SMTs)\n\nThis page provides some common troubleshooting tips for [subscriptions with SMTs](/pubsub/docs/smts/create-subscription-smt).\n\nMonitor SMTs\n------------\n\nTo understand the performance and impact of SMTs on a subscription,\nuse the following monitoring metrics:\n\nThe [subscription/message_transform_latencies](/monitoring/api/metrics_gcp_p_z#pubsub/subscription/message_transform_latencies)\nmetric measures how long it takes for SMTs to be applied to a message. The\nmetric measures only the SMT latency and does not include other parts of the\nmessage delivery time.\n\nThe metric provides two key labels:\n\n- `status`: reports whether the transformation is successful or encountered\n an issue.\n\n- `filtered`: indicates if the SMT caused the message to be filtered out.\n When an SMT filters a message on a subscription, Pub/Sub\n acknowledges it, and the message is never sent to subscribers. This\n `filtered` label is true only when an SMT performs the filtering. Messages\n filtered using Pub/Sub's [built-in filtering capabilities](/pubsub/docs/subscription-message-filter)\n are not reflected in this specific metric.\n\nThe [subscription/byte_cost](/monitoring/api/metrics_gcp_p_z#pubsub/subscription/byte_cost) metric\nis used to identify messages that are filtered by SMTs or where SMTs\nfailed. Look for these specific values:\n\n- When an SMT filters a message, the operation_type is `smt_subscribe_filter_drop`.\n\n- If an SMT fails to transform a message, you see a `response_code` that is not `OK`.\n\nA backlog is building up\n------------------------\n\nIf you see a backlog of messages building up in the subscription check for\n`INVALID_ARGUMENT` errors reported in\n[`subscription/message_transform_latencies`](/monitoring/api/metrics_gcp_p_z#pubsub/subscription/message_transform_latencies).\n\nTo troubleshoot `INVALID_ARGUMENT` errors, add a\n[dead-letter topic](/pubsub/docs/handling-failures#dead_letter_topic) to the\nsubscription of interest. The dead letter topic captures messages that couldn't\nbe delivered to subscribers, along with an attribute called\n`CloudPubSubDeadLetterSourceSMTErrorMessage` that explains the failure reason.\n\nWhat's next\n-----------\n\n- If you still have issues with your subscription SMTs, see [Getting support](/pubsub/docs/getting-support)."]]
