Design reliable workflow steps (Durable Functions)
Durable orchestration preserva el workflow progress, pero la persistencia por si sola no hace que las operaciones externas sean seguras. Los model endpoints pueden hacer throttle de requests, los storage writes pueden sufrir timeouts y un host se pueden reiniciar.
Classify failures before retrying
Los retries ayudan con los fallos que sean efimeros. Consumen recursos por lo que no se reintentar de manera indiscriminada. Clasificar los fallos ayuda a poder resolverlos:
- Transient failure Aplicar una bounded retry policy
- Permanent failure Validar early y enrutar el item a un terminal outcome
- Auth failure Revisar
- Timeout Compensar el tiempo, escalar o preservar para auditar
- Business-rule failure Una confidence score baja o un approval rechazado podemos enrutarlo a una workflow branch explicita
Las activity functions deberian raise failures que el orchestrator necesita tratar como errores técnicos. Pueden devolver outputs estructurados para distinguir casos que no se puedan cumplir de consumir retry attempts.
Apply bounded activity retries
Durable Functions pueden hacer schedule de una actividad con una retry policy. El durable runtime graba cada intento y espera entre intentos el solo. Ponemos un maximum attempt count para que un fallo persistente eventualmente llegue al orchestrator.
en python usamos la RetryOptions API
# Code fragment - focus on a bounded activity retry
import azure.durable_functions as df
retry_options = df.RetryOptions(
first_retry_interval_in_milliseconds=5_000,
max_number_of_attempts=3,
)
result = yield context.call_activity_with_retry(
"process_document",
retry_options,
{
"operation_id": operation_id,
"document_id": document["document_id"],
"blob_url": document["blob_url"],
},
)
NO debemos hacer nest de muchos retry layers no controladas. Calcular el maximo numero de retry attempts y tiempo combinado y configurar ambas capas de manera intencional
Enforce durable timeouts
Una retry policy limita los intentos, mientras que un timeout limita cuanto tiempo espera el workflow por un outcome. Durable timers permiten a un orchestrator expresar una deadline sin mantener recursos activos.
Un timer que gane a task_any() no cancela automaticamente una activity que ya ha comenzado. La activity puede todavia finalizar y producir external side effects. Usamos operation record o cancellation flag que el activity comprueba cuando es necesario, haciendo un eventual write idempotente. Diseñamos el workflow para ignorar un late result tras una terminal deadline.
Timeout scopes:
- Client request timeout Bound one HTTP o SDK call dentro de una activity
- Activity retry window Bound de attempts y delays para un durable step
- Workflow step timeout Race durable task against durable timer
- End-to-end deadline Stop or compensates workflow when the business process exceeds its allowed duration
Make activity side effects idempotent
IMPORTANTE
Durable Functions proveen de at-least-once activity execution. Una activity puede completar un external write y entonces ejecutarse de nuevo si el host falla antes de que el runtime grabe sus resultados.
La idempotencia asegura que repetir las mismas operaciones produce el mismo resultado, en vez de crear duplicados
Derivar una stable operation ID de orchestration input, o crear una con
context.new_uuid()y lo pasamos a la activity. Usamos ese ID como database key, blob name, o cualquier otra key.
NUNCA crear operation ID con
uuid.uuid4()ya que esto causaria que cada reintento parezca que es trabajo nuevo, cuando en realidad estaríamos creando duplicados
/IMPORTANTE
usamos operation ID como blob name y creamos el resultado solo cuando no exista
# Code fragment - focus on an idempotent result write
import json
from azure.core.exceptions import ResourceExistsError
def persist_result(request: dict) -> dict:
blob_name = f"results/{request['operation_id']}.json"
blob_client = results_container.get_blob_client(blob_name)
payload = json.dumps(request["result"])
try:
blob_client.upload_blob(payload, overwrite=False)
write_status = "Created"
except ResourceExistsError:
write_status = "AlreadyExists"
return {
"operation_id": request["operation_id"],
"result_url": blob_client.url,
"write_status": write_status,
}
Compoensate completed side effects
Distributed workflows por lo general no pueden hacer rollback de varios servicios como si fuera una transacción. Tenemos que compensar manualmente cualqueir side effect.
Ejemplo: una activity podria marcar como invalid un rejected claim summary, moverlo a un quarantine container, o esconderlo de downstream consumers.
La compensación debe ser idempotente.
schedule compensation when document processing exhausts its retries. La exception se vuelve a relanzar tras compensar para que el orchestrator mantenga un failed terminal status
# Code fragment - focus on compensation after a failed durable step
try:
result = yield context.call_activity_with_retry(
"process_document",
retry_options,
process_request,
)
except Exception:
yield context.call_activity(
"compensate_document",
{
"operation_id": process_request["operation_id"],
"reason": "ProcessingFailed",
},
)
raise
Expose terminal status and diagnostics
Cada workflow branch deberia llegar a un status como Completed, Rejected, TimedOut, Compensated o Failed.
Incluir IDs para poder trackear requests.
No hacer logging de document contents, prompts, model credentials o tokens.