Acara dapat ditolak karena beberapa alasan. Misalnya, layanan penerima peristiwa mungkin tidak tersedia untuk sementara karena gangguan; error mungkin terjadi pada layanan saat memproses peristiwa; atau resource layanan mungkin habis. Error sementara seperti ini dapat dicoba lagi.
Acara juga dapat gagal dikirim ke penerima acara. Misalnya, peristiwa mungkin tidak cocok dengan skema yang diharapkan yang dikonfigurasi, atau mediasi peristiwa mungkin gagal sebelum pesan peristiwa dapat dirutekan ke tujuan akhirnya. Kasus seperti itu akan menyebabkan error persisten.
Error sementara
Eventarc Advanced memberi Anda kemampuan untuk menangani
error sementara. Error sementara ini dapat dicoba lagi dan mencakup error dengan kode error berikut:
HTTP 408 Request Timeout
HTTP 409 Conflict
HTTP 429 Too Many Requests
HTTP 500 Internal Server Error
HTTP 502 Bad Gateway
HTTP 503 Service Unavailable
HTTP 504 Gateway Time-out
Error persisten
Berbeda dengan error sementara, error persisten mencakup hal berikut:
Error yang terjadi saat jumlah percobaan ulang yang dikonfigurasi habis
Error yang terjadi saat peristiwa gagal sebelum dapat dirutekan ke
tujuannya
Error yang menghasilkan kode error yang dianggap tidak dapat dicoba lagi; misalnya, kode error selain yang tercantum untuk error sementara
Eventarc Advanced menggunakan penundaan backoff eksponensial untuk menangani error yang dapat dicoba ulang. Kebijakan percobaan ulang default dimulai dengan penundaan satu detik, dan penundaan akan digandakan setelah setiap upaya gagal (hingga maksimum 60 detik dan lima upaya).
Anda dapat mengubah kebijakan percobaan ulang default menggunakan konsol Google Cloud atau perintah
gcloud eventarc pipelines update.
Perhatikan bahwa faktor penundaan default 2 tidak dapat diubah.
Konsol
Di konsol Google Cloud , buka halaman Eventarc>Pipelines.
Di halaman Edit pipeline, di bagian Kebijakan percobaan ulang, ubah
kolom berikut:
Upaya maksimal: jumlah percobaan ulang; defaultnya adalah 5 upaya. Dapat berupa
bilangan riil positif apa pun. Jika disetel ke 1, tidak ada kebijakan percobaan ulang yang diterapkan dan hanya satu upaya yang dilakukan untuk mengirimkan pesan.
Penundaan minimum (detik): penundaan awal dalam detik; defaultnya adalah 1 detik. Harus antara 1 dan 600.
Penundaan maksimum (detik): penundaan maksimum dalam detik; defaultnya adalah 60 detik. Harus antara 1 dan 600.
Anda dapat mengonfigurasi penundaan linier dengan menetapkan penundaan minimum dan maksimum ke nilai yang sama.
PIPELINE_NAME: ID atau ID yang memenuhi syarat sepenuhnya dari pipeline.
MIN_DELAY: penundaan awal dalam detik; defaultnya
adalah 1 detik. Harus antara 1 dan 600.
MAX_DELAY: penundaan maksimum dalam detik; defaultnya
adalah 60 detik. Harus antara 1 dan 600.
MAX_ATTEMPTS: jumlah percobaan ulang; default-nya adalah
5 upaya. Dapat berupa bilangan riil positif apa pun. Jika disetel ke 1, tidak ada kebijakan percobaan ulang yang diterapkan dan hanya satu upaya yang dilakukan untuk mengirimkan pesan.
Contoh berikut mengonfigurasi backoff linear dengan menyetel penundaan minimum dan
maksimum ke nilai yang sama:
Mengarsipkan pesan untuk menangani error persisten
Anda dapat menulis pesan ke tabel BigQuery saat pesan diterima. Dengan demikian, Anda dapat mengidentifikasi error persisten secara manual dan menanganinya dengan tepat.
Berikut ringkasan langkah-langkah yang diperlukan untuk mengarsipkan pesan acara, mengidentifikasi error persisten, dan mencoba lagi acara yang terpengaruh.
Buat topik Pub/Sub. Topik Pub/Sub ini akan menjadi tujuan target untuk pipeline Anda.
Buat langganan BigQuery untuk
topik Pub/Sub. Langganan BigQuery adalah jenis langganan ekspor yang menulis pesan ke tabel BigQuery yang sudah ada saat pesan diterima. Atau, Anda dapat
membuat tabel saat membuat langganan BigQuery.
Buat pipeline dan pendaftaran
yang merutekan setiap pesan yang diterima oleh bus (menggunakan --cel-match="true") ke
topik Pub/Sub. Konfigurasi kebijakan percobaan ulang untuk pipeline.
Misalnya, perintah berikut membuat pipeline dan pendaftaran:
Sekarang Anda akan memiliki dua set data BigQuery terpisah: satu yang menyimpan setiap pesan yang diterima oleh bus Eventarc Advanced dan satu yang menyimpan log pipeline Anda.
Pengendali peristiwa yang dapat dicoba ulang harus bersifat idempoten, menggunakan panduan umum berikut:
Banyak API eksternal yang dapat Anda gunakan untuk menyuplai kunci idempotensi sebagai parameter. Jika Anda menggunakan API seperti itu, Anda harus menggunakan sumber dan ID peristiwa sebagai kunci idempotensi. (Produsen harus memastikan bahwa
source + id bersifat
unik untuk setiap peristiwa yang berbeda.)
Selain itu, Anda dapat menggunakan atribut CloudEvents, xgooglemessageuid, untuk
menyediakan idempotensi. Nilai atribut ini sama dengan kolom message_uid di pesan Lanjutan Eventarc. Secara unik
mengidentifikasi tindakan memublikasikan acara. Misalnya, jika peristiwa yang sama dipublikasikan dua kali ke bus, setiap peristiwa akan memiliki nilai xgooglemessageuid yang berbeda saat dikirim ke pengendali peristiwa.
Idempotensi berfungsi dengan baik pada pengiriman "setidaknya sekali" karena memberikan keamanan untuk mencoba ulang. Jadi, salah satu praktik terbaik yang umum untuk menulis kode tepercaya adalah dengan menggabungkan idempotensi dengan percobaan ulang.
Pastikan kode Anda idempoten secara internal. Contoh:
Pastikan mutasi bisa terjadi lebih dari sekali tanpa mengubah hasilnya.
Jalankan kueri pada status database dalam transaksi sebelum memutasikan status tersebut.
Pastikan semua efek samping bersifat idempoten.
Lakukan pemeriksaan transaksi di luar layanan Anda, terlepas dari kode.
Sebagai contoh, pertahankan status di suatu tempat yang mencatat bahwa ID peristiwa tertentu telah diproses.
Tangani panggilan duplikat yang tidak umum. Misalnya, jalankan proses pembersihan terpisah yang akan melakukan pembersihan setelah panggilan duplikat.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-08-18 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)"]]
