Politika ta' Retrying
F'din il-paġna
Għaliex ir-retrying huwa essenzjali
F’sistema distribwita, l-iżbalji tranżitorji huma inevitabbli: time-outs tan-network, limiti ta’ rata (rate limits) maqbura, servizzi mhux disponibbli temporanjament. L-ebda waħda minn dawn il-fallimenti ma tindika bug fil-kodiċi tiegħek, madankollu kwalunkwe waħda minnhom tista’ tikkawża li proċess ifalli jekk xejn ma jassorbi x-xokk. Politika ta’ retrying (retry policy) tippermetti lill-attivitajiet tiegħek jissopravvivenzu dawn l-iżbalji mingħajr intervent manwali, billi l-pjattaforma terġa’ tniedihom awtomatikament skont il-konfigurazzjoni li tiddefinixxi għal kull attività.
Konfigurazzjoni ta’ politika ta’ retrying
Id-dekoratur @workflows.activity() jaċċetta parametri li jirregolaw dan l-imġiba. Hawnhekk hemm attività ta’ sejħa ta’ API esterna armata sew għar-reżiljenza.
from datetime import timedelta
import mistralai.workflows as workflows
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5),
retry_policy_max_attempts=3,
retry_policy_backoff_coefficient=2.0,
)
async def call_external_api(url: str, data: dict) -> dict:
"""Issejjaħ API esterna b'retrying awtomatiku."""
async with httpx.AsyncClient(timeout=60) as client:
response = await client.post(url, json=data)
response.raise_for_status()
return response.json()
Tliet parametri, tliet rwoli komplementari.
-
start_to_close_timeout— It-tul massimu ta’ żmien għal tentattiv wieħed ta’ eżekuzzjoni. Jekk l-attività ma titlestix f’dan il-perjodu ta’ żmien, titqies bħala falluta u jinbeda tentattiv ġdid. -
retry_policy_max_attempts— In-numru massimu ta’ tentattivi. Il-valur predefinit jiddependi mill-pjattaforma. Wara dan in-numru ta’ tentattivi, l-attività tfalli definittivament u l-workflow jirċievi żball. -
retry_policy_backoff_coefficient— Il-multiplikatur għad-dewmien bejn it-tentattivi. B’koeffiċjent ta’ 2.0, id-dewmien jirdoppja ma’ kull tentattiv (1s, 2s, 4s, 8s…). Dan huwa “exponential backoff”.
Dan il-mekkaniżmu ta’ backoff jixraq attenzjoni għax l-għan tiegħu mhux biss li tistenna: jagħti lis-servizz li qed isofri ħin biex jirkupra minflok ma tħabbtu bla waqfien. Il-progressjoni ta’ sejħa li eventwalment tirnexxi turi dan b’mod ċar.
Tentattiv 1: eżekuzzjoni immedjata
→ Falliment (network timeout)
→ Stenna sekonda waħda
Tentattiv 2: eżekuzzjoni
→ Falliment (servizz mhux disponibbli)
→ Stenna 2 sekondi (1 × 2.0)
Tentattiv 3: eżekuzzjoni
→ Falliment (limitu ta' rata)
→ Stenna 4 sekondi (2 × 2.0)
Tentattiv 4: eżekuzzjoni
→ Suċċess!
Quddiem tweġiba “429 Too Many Requests”, dan il-mekkaniżmu huwa partikolarment effettiv: politika li tipprova mill-ġdid immedjatament biss iżżomm is-saturazzjoni, filwaqt li ż-żieda fl-ispazjar eventwalment tinżel taħt il-limitu tal-fornitur.
Qatt ma tħalli barra start_to_close_timeout
Dan it-timeout huwa kritiku u għandu jidher fuq kull attività, mingħajr eċċezzjoni. Mingħajru, attività li tispiċċa mblukkata—deadlock, konnessjoni mdendla, servizz li jaċċetta t-talba iżda qatt ma jwieġeb—tistenna għal żmien indefinit u tibblokka l-workflow kollu. Agħar minn hekk: ma jipprovoka l-ebda retry, peress li mill-perspettiva tiegħu għadu ma falliex.
# PRATTIKA ĦŻIENA: l-ebda timeout
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
# Jekk is-servizz qatt ma jwieġeb, l-attività tistenna għal żmien indefinit
async with httpx.AsyncClient() as client:
response = await client.get("https://api.lente.example.com/data")
return response.json()
# PRATTIKA TAJBA: timeout espliċitu
@workflows.activity(
start_to_close_timeout=timedelta(minutes=2)
)
async def safe_activity(params: dict) -> dict:
async with httpx.AsyncClient(timeout=90) as client:
response = await client.get("https://api.lente.example.com/data")
return response.json()
Biex tissettja l-valur, l-ewwel kejjel il-ħin normali ta’ eżekuzzjoni tal-attività, imbagħad żid marġni ta’ żewġ sa tliet darbiet biex tkopri każijiet bil-mod. Fl-aħħar nett, żgura li t-timeout tal-klijent HTTP intern jibqa’ aktar baxx mill-start_to_close_timeout—fl-eżempju ta’ hawn fuq, 90 sekonda meta mqabbla ma’ 2 minuti—sabiex l-iżball jinxtered b’mod nadif mill-kodiċi tiegħek minflok ma jiġi maqtugħ mill-pjattaforma.
Idempotenza: kundizzjoni mhux negozjabbli
Peress li attività tista’ terġa’ tiġi riprodotta diversi drabi bl-istess parametri, trid tipproduċi l-istess effett irrispettivament min-numru ta’ eżekuzzjonijiet. Din il-proprjetà tissejjaħ idempotenza, u n-nuqqas tagħha jħawwel politika ta’ retrying f’ġeneratur ta’ inċidenti.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
"""PERIKLUŻ: jekk jerġa' jsir, il-kreditu jiżdied diversi drabi!"""
async with httpx.AsyncClient() as client:
response = await client.post(
f"https://api.billing.com/credits/add",
json={"user_id": user_id, "amount": amount}
)
return response.json()
L-ixraħ xenarju huwa komuni: l-API tal-fatturar tipproċessa t-talba korrettament, iżda t-tweġiba tintilef fin-network. L-attività tikkonkludi li falliet, il-pjattaforma tipprova mill-ġdid, u l-klijent jiġi akkreditat darbtejn. Ċavetta ta’ idempotenza (idempotency key) telimina l-problema billi tagħti lis-servizz remot mod biex jirrikonoxxi talba diġà pproċessata.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
"""KORRETT: iċ-ċavetta ta' idempotenza tevita d-duplikazzjoni."""
async with httpx.AsyncClient() as client:
response = await client.post(
f"https://api.billing.com/credits/add",
json={
"user_id": user_id,
"amount": amount,
"idempotency_key": idempotency_key
}
)
return response.json()
Iġġenera ċ-ċavetta fil-workflow bl-użu ta’ workflow.uuid4(), li jiggarantixxi li tibqa’ identika minn replay għal ieħor—uuid.uuid4() klassiku jipproduċi valur ġdid fuq kull tentattiv u jikkanċella l-protezzjoni kollha. Meta s-servizz remot ma joffrix dan il-mekkaniżmu, jeżistu żewġ triqat oħra: upsert fil-bażi tad-data, bl-użu ta’ INSERT ... ON CONFLICT UPDATE minflok INSERT biss, jew verifika ta’ pre-check, li tinvolvi l-ikkonsultar tal-istat qabel ma taġixxi.
Tliet profili ta’ konfigurazzjoni
Il-valuri jiġu kkwalibrati skont in-natura tal-operazzjoni. Pagament jew notifika trid tirnexxi malajr jew tfalli malajr: timeout qasir, tliet tentattivi, backoff moderat.
@workflows.activity(
start_to_close_timeout=timedelta(seconds=30),
retry_policy_max_attempts=3,
retry_policy_backoff_coefficient=2.0,
)
async def process_payment(params: dict) -> dict:
# ...
pass
Ipproċessar fit-tul, bħall-ġenerazzjoni ta’ rapporti jew inferenza tqila, jinverti l-loġika: kull tentattiv jispiċċa ħin ta’ komputazzjoni sinifikanti, għalhekk tawtorizza inqas tentattivi b’ispazjar usa’.
@workflows.activity(
start_to_close_timeout=timedelta(minutes=15),
retry_policy_max_attempts=2,
retry_policy_backoff_coefficient=3.0,
)
async def generate_ml_report(params: dict) -> dict:
# ...
pass
Quddiem API ta’ parti terza instabbli soġġetta għal limitazzjoni ta’ rata (rate limiting), finalment tassumi l-persistenza: ħames tentattivi, anke jekk dan ifittex diversi minuti.
@workflows.activity(
start_to_close_timeout=timedelta(minutes=2),
retry_policy_max_attempts=5,
retry_policy_backoff_coefficient=2.0,
)
async def call_third_party_api(params: dict) -> dict:
# ...
pass
Punti Ewlenin
- Dejjem ikkonfigura
start_to_close_timeoutbiex tevita attivitajiet imblukkati - Exponential backoff (
retry_policy_backoff_coefficient) jiżdied id-dewmien bejn it-tentattivi retry_policy_max_attemptsjiddefinixxi n-numru massimu ta’ tentattivi qabel il-falliment definittiv- Attivitajiet b’retrying iridu jkunu idempotenti—l-istess riżultat jekk jiġu eżegwiti diversi drabi
- Uża ċwievet ta’ idempotenza jew upserts biex tiggarantixxi l-idempotenza
- Adatta t-timeouts u n-numru ta’ tentattivi għat-tip ta’ operazzjoni (mgħaġġla vs twila, stabbli vs instabbli)