재시도할 수 있는 이벤트 핸들러는 다음 일반 가이드라인을 사용하여 멱등성을 가져야 합니다.
다양한 외부 API를 사용하면 매개변수로 멱등 키를 제공할 수 있습니다. 이러한 API를 사용한다면 이벤트 소스와 ID를 멱등 키로 사용해야 합니다. (제작자는 source + id가 고유한 이벤트마다 고유해야 합니다.)
또한 CloudEvents 속성 xgooglemessageuid를 사용하여 무관성을 제공할 수 있습니다. 이 속성의 값은 Eventarc Advanced 메시지의 message_uid 필드와 동일합니다. 이벤트 게시 작업을 고유하게 식별합니다. 예를 들어 동일한 이벤트가 버스에 두 번 게시되면 각 이벤트가 이벤트 핸들러로 전송될 때 서로 다른 xgooglemessageuid 값을 갖게 됩니다.
멱등성이 있으면 재시도해도 안전하므로 최소 1회 전송 시 잘 작동합니다. 따라서 안정적인 코드를 작성하기 위한 일반적인 권장사항은
재시도와 멱등성을 결합하는 것입니다.
코드에 내부적으로 멱등성이 있어야 합니다. 예를 들면 다음과 같습니다.
결과에 변화 없이 변형이 2번 이상 발생할 수 있는지 확인합니다.
상태가 변형되기 전에 트랜잭션에서 데이터베이스 상태를 쿼리합니다.
모든 부가적인 결과에 자체적으로 멱등성이 있는지 확인합니다.
코드에 관계없이 서비스 외부에서 트랜잭션 검사를 시행합니다.
예를 들어 특정 이벤트 ID가 이미 처리되었음을 어딘가에 기록하는
상태를 유지합니다.
중복 호출을 대역 외로 처리합니다. 예를 들어 중복 호출 후 삭제하는 별도의 삭제 프로세스를 둡니다.
[[["이해하기 쉬움","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)"],[[["\u003cp\u003eEventarc Advanced handles transient errors, such as temporary service unavailability, by automatically retrying them using an exponential backoff delay, with default settings of up to 5 attempts and a maximum 60-second delay, starting from a 1-second delay.\u003c/p\u003e\n"],["\u003cp\u003ePersistent errors, including those where retries are exhausted or events fail before routing, require manual identification and handling, and these errors can be found through error codes that are considered non-retryable.\u003c/p\u003e\n"],["\u003cp\u003eUsers can customize the retry policy for transient errors in Eventarc Advanced by adjusting the maximum attempts, minimum delay, and maximum delay through the Google Cloud console or the gcloud command-line tool.\u003c/p\u003e\n"],["\u003cp\u003eTo manage persistent errors, Eventarc Advanced allows for the archiving of event messages to a BigQuery table, where users can then identify and re-publish failed messages using the Eventarc Publishing API.\u003c/p\u003e\n"],["\u003cp\u003eEvent handlers should be designed to be idempotent, ensuring that multiple executions of the same event do not lead to unintended changes, often achievable through the use of idempotency keys or attributes like \u003ccode\u003exgooglemessageuid\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Retry events\n\n[Advanced](/eventarc/advanced/docs/overview)\n\nAn event can be rejected for multiple reasons. For example, the event receiver\nservice might be temporarily unavailable due to an outage; an error might be\nencountered by the service when processing an event; or service resources\nmight become exhausted. *Transient errors* like this can be retried.\n\nAn event can also fail to be delivered to the event receiver. For example, the\nevent might not match the expected schema that is configured, or the mediation\nof the event might fail before the event message can be routed to its final\ndestination. Such cases result in *persistent errors*.\n\nTransient errors\n----------------\n\nEventarc Advanced provides you with the capability to handle\ntransient errors. These transient errors can be retried and include those with\nthe following error codes:\n\n- HTTP `408 Request Timeout`\n- HTTP `409 Conflict`\n- HTTP `429 Too Many Requests`\n- HTTP `500 Internal Server Error`\n- HTTP `502 Bad Gateway`\n- HTTP `503 Service Unavailable`\n- HTTP `504 Gateway Time-out`\n\nPersistent errors\n-----------------\n\nIn contrast to transient errors, persistent errors include the following:\n\n- Errors that occur when the number of configured retries is exhausted\n- Errors that occur when an event fails before it can be routed to its destination\n- Errors that result in an error code that is considered non-retryable; for example, error codes other than those listed for transient errors\n\nYou can [manually identify persistent errors and handle them](#handle-persistent)\nappropriately.\n\nRetry transient errors\n----------------------\n\nEventarc Advanced uses an exponential backoff delay to handle\nerrors that can be retried. The default retry policy starts with a one-second\ndelay, and the delay is doubled after each failed attempt (up to a maximum of 60\nseconds and five attempts).\n\nYou can change the default retry policy using the Google Cloud console or the\n[`gcloud eventarc pipelines update`](/sdk/gcloud/reference/eventarc/pipelines/update)\ncommand.\n\nNote that the default backoff factor of `2` can't be changed. \n\n### Console\n\n1. In the Google Cloud console, go to the **Eventarc**\n \\\u003e **Pipelines** page.\n\n\n [Go to Pipelines](https://console.cloud.google.com/eventarc/pipelines)\n\n \u003cbr /\u003e\n\n2. Click the name of the pipeline.\n\n3. In the **Pipeline details** page, click **Edit**.\n\n4. On the **Edit pipeline** page, in the **Retry policy** section, modify\n the following fields:\n\n - **Max attempts** : the number of retries; default is `5` attempts. Can be any positive real number. If set to `1`, no retry policy is applied and only one attempt is made to deliver a message.\n - **Min delay (seconds)** : the initial delay in seconds; default is `1` second. Must be between `1` and `600`.\n - **Max delay (seconds)** : the maximum delay in seconds; default is `60` seconds. Must be between `1` and `600`.\n\n You can configure a linear backoff by setting the minimum and maximum\n delays to the same value.\n5. Click **Save**.\n\n### gcloud\n\n gcloud eventarc pipelines update \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e \\\n --min-retry-delay=\u003cvar translate=\"no\"\u003eMIN_DELAY\u003c/var\u003e \\\n --max-retry-delay=\u003cvar translate=\"no\"\u003eMAX_DELAY\u003c/var\u003e \\\n --max-retry-attempts=\u003cvar translate=\"no\"\u003eMAX_ATTEMPTS\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e: the ID or fully qualified identifier of the pipeline.\n- \u003cvar translate=\"no\"\u003eMIN_DELAY\u003c/var\u003e: the initial delay in seconds; default is `1` second. Must be between `1` and `600`.\n- \u003cvar translate=\"no\"\u003eMAX_DELAY\u003c/var\u003e: the maximum delay in seconds; default is `60` seconds. Must be between `1` and `600`.\n- \u003cvar translate=\"no\"\u003eMAX_ATTEMPTS\u003c/var\u003e: the number of retries; default is `5` attempts. Can be any positive real number. If set to `1`, no retry policy is applied and only one attempt is made to deliver a message.\n\nThe following example configures a linear backoff by setting the minimum and\nmaximum delays to the same value: \n\n gcloud eventarc pipelines update my-pipeline \\\n --min-retry-delay=4 \\\n --max-retry-delay=4 \\\n --max-retry-attempts=5\n\nArchive messages to handle persistent errors\n--------------------------------------------\n\nYou can write messages to a BigQuery table as they are received. This\nlets you manually identify persistent errors and handle them appropriately.\n\nThe following provides an overview of the steps required to archive your event\nmessages, identify persistent errors, and retry the affected events.\n\n1. [Create a bus](/eventarc/advanced/docs/publish-events/create-bus). Configure the bus appropriately; for example, to [publish events from Google sources](/eventarc/advanced/docs/publish-events/publish-events-google-sources).\n2. [Create a Pub/Sub topic](/pubsub/docs/create-topic). This Pub/Sub topic will be the target destination for your pipeline.\n3. [Create a BigQuery subscription](/pubsub/docs/bigquery) for the Pub/Sub topic. A BigQuery subscription is a type of export subscription that writes messages to an existing BigQuery table as they are received. Alternatively, you can create the table when you create the BigQuery subscription.\n4. [Create a pipeline and enrollment](/eventarc/advanced/docs/receive-events/create-enrollment)\n that routes every message received by the bus (using `--cel-match=\"true\"`) to\n the Pub/Sub topic. Configure a retry policy for the pipeline.\n\n For example, the following commands create a pipeline and an enrollment: \n\n gcloud eventarc pipelines create my-archive-pipeline \\\n --destinations=pubsub_topic='my-archive-topic' \\\n --min-retry-delay=1 \\\n --max-retry-delay=20 \\\n --max-retry-attempts=6 \\\n --location=us-central1\n\n gcloud eventarc enrollments create my-archive-enrollment \\\n --cel-match=\"true\" \\\n --destination-pipeline=my-archive-pipeline \\\n --message-bus=my-message-bus \\\n --message-bus-project=my-google-cloud-project \\\n --location=us-central1\n\n5. [Route your pipeline logs](/logging/docs/export/configure_export_v2) to\n another BigQuery dataset.\n\n You should now have two separate BigQuery datasets: one that\n stores every message received by your Eventarc Advanced bus and one\n that stores your pipeline logs.\n6. To identify messages that have failed, use a\n [query statement to join](/bigquery/docs/reference/standard-sql/query-syntax#join_types)\n both BigQuery datasets on the `message_uid` field.\n\n7. After identifying any failed messages, you can publish them to your bus again\n using the [Eventarc Publishing API](/eventarc/docs/reference/publishing/rest).\n For example, you can\n [deploy a Cloud Run service or job](/run/docs/overview/what-is-cloud-run)\n to read the messages from BigQuery and\n [publish them directly](/eventarc/advanced/docs/publish-events/publish-events-direct-format)\n to the Eventarc Advanced bus.\n\nMake event handlers idempotent\n------------------------------\n\nEvent handlers that can be retried should be idempotent, using the following\ngeneral guidelines:\n\n- Many external APIs let you supply an idempotency key as a parameter. If you are using such an API, you should use the event source and ID as the idempotency key. (Producers must ensure that [source + id](/eventarc/advanced/docs/receive-events/use-cel#attributes) is unique for each distinct event.)\n- Additionally, you can use a CloudEvents attribute, `xgooglemessageuid`, to provide idempotency. The value of this attribute is the same as the `message_uid` field in Eventarc Advanced messages. It uniquely identifies the action of publishing an event. For example, if the same event is published twice to a bus, each event will have a different `xgooglemessageuid` value when sent to an event handler.\n- Idempotency works well with at-least-once delivery, because it makes it safe to retry. So a general best practice for writing reliable code is to combine idempotency with retries.\n- Make sure that your code is internally idempotent. For example:\n - Make sure that mutations can happen more than once without changing the outcome.\n - Query database state in a transaction before mutating the state.\n - Make sure that all side effects are themselves idempotent.\n- Impose a transactional check outside your service, independent of the code. For example, persist state somewhere recording that a given event ID has already been processed.\n- Deal with duplicate calls out-of-band. For example, have a separate clean up process that cleans up after duplicate calls.\n\nWhat's next\n-----------\n\n- [Troubleshoot issues](/eventarc/advanced/docs/troubleshoot)\n- [View audit logs](/eventarc/advanced/docs/audit-logs)"]]
