push 구독자는 메시지가 Pub/Sub에서 사용자 지정 HTTPS 엔드포인트로 전송되는 Pub/Sub 구독자 유형입니다. 사용자는 Push 서버 요청에 HTTP 200 응답을 반환하여 push 메시지를 확인합니다. 이 문서에서는 Pub/Sub push 구독에 대한 일반적인 문제 해결 팁을 제공합니다. push 구독자 가이드에서 push 구독에 대해 자세히 알아보세요.
엔드포인트가 오류 응답 코드를 반환하면 메시지 전송이 실패한 것으로 간주되고 나중에 다시 시도됩니다. 그 결과 엔드포인트에 중복 메시지가 수신될 수 있습니다.
push 구독 모니터링에 사용할 수 있는 측정항목은 여러 개가 있습니다. Cloud Metrics의 subscription/push_request_count 측정항목은 push 엔드포인트의 응답을 response_code 및 response_class로 분류합니다. 응답은 잠재적 엔드포인트 오작동을 식별하는 데 유용합니다. 이 측정항목에 ack가 아닌 response_class 데이터가 포함된 경우 push 엔드포인트가 Pub/Sub에 오류를 반환 중임을 나타냅니다. 가장 일반적인 오류는 다음과 같습니다.
deadline_exceeded 응답 클래스는 push 엔드포인트가 필요한 확인(ack) 기한 내에 응답하지 않았음을 나타냅니다. subscription/push_request_latencies 측정항목은 push 확인 지연 시간을 추적하는 데 도움이 됩니다.
invalid 응답 클래스는 엔드포인트에서 Pub/Sub가 올바르게 이해하거나 처리할 수 없는 응답이 전송되었음을 나타냅니다.
remote_server_4xx 응답 클래스는 일반적으로 인증 또는 권한 문제를 나타냅니다. 이것들은 엔드포인트에서 반환된 HTTP 응답 코드이므로, 이 응답 코드가 반환된 시나리오를 조사해야 합니다. 인증이 사용 설정되었으면 계정에 엔드포인트에 대해 올바른 권한이 있는지 확인합니다. push 구독에서 인증 작동 방식을 자세히 알아보세요.
remote_server_5xx 응답 클래스는 엔드포인트 측면의 서버 측 문제를 나타냅니다. 엔드포인트가 요청을 처리할 수 없습니다. 지속적인 유지보수 또는 중단 때문일 수 있습니다. 엔드포인트를 호스팅하는 서버 상태를 검토하세요.
unreachable 응답은 엔드포인트 서버에 전혀 연결할 수 없음을 나타냅니다. 엔드포인트 URL에 오타가 없는지 확인합니다.
VPC 서비스 제어(VPC-SC) 보호가 프로젝트에 사용 설정된 경우 push 구독 만들기에 제한이 있습니다. 기존 push 구독은 계속 작동하지만 새 push 구독을 만들 때 Request is prohibited by organization's policy 오류가 표시됩니다. 특히 push 엔드포인트가 기본 run.app URL을 사용하는 Cloud Run 서비스인 경우에만 새 push 구독을 만들 수 있습니다. 자세한 내용 및 특정 제한사항은 Pub/Sub 문서 및 VPC-SC 문서를 참조하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Troubleshooting a push subscription\n\nPush subscribers are a type of Pub/Sub subscriber where messages are sent from Pub/Sub to a user-specified HTTPS endpoint. The user acknowledges a pushed message by returning an HTTP 200 response to the push server's request. This document provides some common troubleshooting tips for Pub/Sub push subscriptions. Read more about push subscriptions in the [Push subscriber guide](/pubsub/docs/push).\n\nTo effectively monitor your Pub/Sub subscription, it is recommended to first look at the [delivery latency health score](/pubsub/docs/monitoring#delivery_latency_health) ([`subscription/delivery_latency_health_score`](/monitoring/api/metrics_gcp_p_z#pubsub/subscription/delivery_latency_health_score)) to check which factors could be contributing to an unexpected latency.\n\nFailing or slow push endpoints\n------------------------------\n\nIf the endpoint returns an error response code, then the message delivery is considered to have failed and is retried later. This can potentially lead to the endpoint receiving duplicate messages.\n\nThere are multiple metrics that you can use to [monitor push subscriptions](/pubsub/docs/monitoring#monitoring_push_subscriptions). The [`subscription/push_request_count`](/monitoring/api/metrics_gcp_p_z#pubsub/subscription/push_request_count) metric in Cloud Metrics categorizes responses from the push endpoint by `response_code` and `response_class`. The responses are useful for the identification of potential endpoint malfunctions. If this metric has data with a `response_class` other than `ack`, this indicates that the push endpoint is returning errors to Pub/Sub. Some of the most common errors include:\n\n- A `deadline_exceeded` response class indicates that the push endpoint didn't respond within the required acknowledgment (ack) deadline. The [`subscription/push_request_latencies`](/monitoring/api/metrics_gcp_p_z#pubsub/subscription/push_request_latencies) metric helps to track push ack latency.\n\n- An `invalid` response class indicates that the endpoint sent back a response that Pub/Sub couldn't understand or process correctly.\n\n- A `remote_server_4xx` response class usually indicates authentication or permission issues. These are HTTP response codes returned by the endpoint, so look at the scenarios under which this response code is returned. If authentication is enabled, confirm your account has the right permission on the endpoint. Learn more about how [authentication](/pubsub/docs/create-push-subscription#authentication) works in push subscriptions.\n\n- A `remote_server_5xx` response class indicates a server-side problem on the endpoint side. The endpoint is unable to process the request. This might be due to an ongoing maintenance or outage. Review the status of the server hosting the endpoint.\n\n- An `unreachable` response class indicates that the endpoint server cannot be reached at all. Verify the endpoint URL for typos.\n\nLearn more about the most common [error codes](/pubsub/docs/reference/error-codes) of the Pub/Sub API.\n\nRestrictions on push subscriptions inside a VPC-SC perimeter\n------------------------------------------------------------\n\nIf VPC Service Controls (VPC-SC) protection is enabled in a project, there are limitations on creating push subscriptions. Existing push subscriptions continue to work, but when you create a new push subscription, you see the error: `Request is prohibited by organization's policy`. Specifically, new push subscriptions can only be created if the push endpoint is a Cloud Run service using the default `run.app` URL. For more details and specific limitations, see [Pub/Sub documentation](/pubsub/docs/create-push-subscription#vpc-service-control) and [VPC-SC documentation](/vpc-service-controls/docs/supported-products#table_pubsub)."]]
