Posts Tagged - service-bus

Process messages reliably (Service Bus)

Reliable message processing asegura que la AI pipe tenga en cuenta y sepa manejar crasheos de micros, modelos que devuelven errores o payloads que contiene unexpected data.

Receive modes

Service Bus ofrece distintos receive modes que controlar como los brokers manejan el acknowledgment del message delivery. Esto es si priorizamos throughput o garantías de entrega.

Receive-and-delete mode

En receive-and-delete mode, Service Bus elimina el mensaje de la cola inmediatamente cuando se entrega el mensaje al consumidor. Si el consumer se crashea después de recibir el mensaje, pero antes de completar la entrega, el sistema pierde ese mensaje.

Este escenario ofrece el throughput más alto porque elimina el lock y el viaje de vuelta del ack.

Solo es para escenarios donde una pérdida ocasional del mensaje es aceptable y la prioridad es la velocidad de entrega

Ejemplo: telemetría en tiempo eral o non-critical logging - si perdemos algunas entradas no pasa nada

Peek-lock mode

IMPORTANTE

Es el modo por defecto y el recomendado para AI workloads

/IMPORTANTE

Service Bus pone un lock al mensaje durante una cantidad de tiempo configurable y lo envía al consumer, sin eliminarlo de la cola. El consumer debe marcar un estado explícito para el mensaje (complete, abandon, dead-letter, defer) durante la duración de este lock.

Si el lock expira antes de obtener un estado, Service Bus quita el lock y marca el mensaje como disponible para otro consumer. Este proceso en 2 fases asegura mínimo un procesamiento.

El trade-off de peek-lock es un menor throughput comparado con receive-and-delete. Para la mayoría de apps, este overhead es un mal menor.

ejemplo de peek-lock receive w. complete y dead-letter settlements

# Code fragment - focus on peek-lock receive with settlement
import json
from azure.servicebus import ServiceBusClient, ServiceBusReceiveMode
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    with client.get_queue_receiver(
        queue_name="inference-requests",
        receive_mode=ServiceBusReceiveMode.PEEK_LOCK,
        max_wait_time=30
    ) as receiver:
        for msg in receiver:
            try:
                payload = json.loads(str(msg))
                result = run_inference(payload)
                save_result(result, payload.get("document_id"))
                receiver.complete_message(msg)
            except json.JSONDecodeError:
                receiver.dead_letter_message(
                    msg,
                    reason="MalformedPayload",
                    error_description="Message body is not valid JSON"
                )
            except ModelNotFoundError:
                receiver.dead_letter_message(
                    msg,
                    reason="UnsupportedModel",
                    error_description=f"Model {payload.get('model')} is not available"
                )
            except TransientServiceError:
                receiver.abandon_message(msg)

estados disponibles

Complete

Método complete_message() lo marca como procesado OK y lo quita de la queue de manera permanente.

Abandon

Método abandon_message() hace release del lock sin quitar el mensaje de la queue, haciéndolo inmediatamente entregable a otro consumer.

Se suele abandonar un mensaje cuando hay un error transiente que se puede procesar bien en un retry, como un timeout o errores de red.

IMPORTANTE

Cada vez que un mensaje se abandona Service Bus incrementa el count de entrega, si este llega a un límite, el mensaje eventualmente se mueve a dead-letter.

/IMPORTANTE

Dead-letter

Método dead_letter_message() mueve el mensaje a la sub-queue dead-letter con una reason string y un error description.

Un mensaje se marca como dead-letter cuando hay un error no recuperable que hace que no se pueda procesar.

Marcarlo como dead-letter lo quita de la queue normal y lo preserva en otra queue para que lo investiguemos.

Ejemplo: JSON mal formado

Defer

Método defer_message() mantiene el mensaje en la queue pero lo borra de regular delivery. Solo puedes hacer retrieve de ese mensaje después por su sequence number usando receive_deferred_messages().

IMPORTANTE

Esto se utiliza para escenarios donde el consumer no puede procesar un mensaje en ese momento, pero si que podrá después más tarde, o cuando los mensajes necesitan un orden específico pero llegan desordenados.

/IMPORTANTE

Handle poison messages with max delivery count

Service Bus trackea cuantas veces se hace deliver de cada message. Cuando el delivery count se pasa del param max_delivery_count de la queue (default is 10), Service Bus automáticamente mueve el mensaje a la dead-letter queue con la razón MaxDeliveryCountExceeded.
Este mecanismo previene que mensajes que fallan constantemente bloqueen la queue.

Poniendo un valor más bajo (de 3 a 5) los poison messages se envían a la dead-letter más rápido, liberando capacidad para mensajes sanos.
Con un valor más alto los errores transientes tienen más posibilidades de arreglarse solos.

Monitor and process dead-letter queue

La dead-letter queue (DLQ) es una sub-queue que tiene toda queue y subscription

Mantiene los messages que expiran, se pasan del max delivery count, o que la app marca explicitamente como dead-letters. La DLQ existe automaticamente y no hay que crearla. Los mensajes en la DLQ persisten hasta que explicitamente los recibes y los completas.

Cada dead-letter message contiene dead_letter_reason y dead_letter_error_description que explican por qué se han movido allí. Para los mensajes que se pasan del max delivery count, la razón es MaxDeliveryCountExceeded. Para los mensajes que la app manda explicitamente a la DLQ se pasa la razón en la string dead_letter_message()

Monitorizar la DLQ es crítico ya que puede indicar cosas como un formato nuevo que no se puede procesar o un deployment de un modelo que no funciona.

Se puede poner alertas en Azure Monitor sobre la DLQ para hacer tracking del número de mensajes.

Accedes a la DLQ usando sub_queue=ServiceBusSubQueue.DEAD_LETTER

# Code fragment - focus on receiving and inspecting dead-letter messages
from azure.servicebus import ServiceBusClient, ServiceBusSubQueue
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    with client.get_queue_receiver(
        queue_name="inference-requests",
        sub_queue=ServiceBusSubQueue.DEAD_LETTER,
        max_wait_time=10
    ) as dlq_receiver:
        for msg in dlq_receiver:
            print(f"Dead-letter reason: {msg.dead_letter_reason}")
            print(f"Error description: {msg.dead_letter_error_description}")
            print(f"Correlation ID: {msg.correlation_id}")
            print(f"Delivery count: {msg.delivery_count}")
            print(f"Body: {str(msg)}")
            # Inspect and decide whether to resubmit or discard
            dlq_receiver.complete_message(msg)

Reprocess dead-lettered messages

Después de arreglar el fallo raíz del problema, se pueden volver a mandar los dead-letter messages a la cola original

El patrón conlleva

  1. leer cada mensaje de la DLQ
  2. crear UN NUEVO MENSAJE con el mismo body y properties
  3. volver a mandarlo a la queue original
  4. completar el dead-letter message para eliminarlo de la DLQ
# Code fragment - focus on resubmitting dead-lettered messages
with client.get_queue_receiver(
    queue_name="inference-requests",
    sub_queue=ServiceBusSubQueue.DEAD_LETTER,
    max_wait_time=10
) as dlq_receiver:
    with client.get_queue_sender("inference-requests") as sender:
        for msg in dlq_receiver:
            # Create a new message with the original body and properties
            new_message = ServiceBusMessage(
                body=msg.body,
                content_type=msg.content_type,
                correlation_id=msg.correlation_id,
                application_properties=msg.application_properties
            )
            sender.send_messages(new_message)
            dlq_receiver.complete_message(msg)

Con scripts de reprocesado automático podemos volver a mandar los DLQ messages en bulk o batches.

Manage lock duration for long-running AI ops

IMPORTANTE

Algunas ops como procesar docs muy grandes necesitan más tiempo del default lock duration. Este valor es configurable hasta 5 minutos, con un default de 1 minuto.

Si el lock expira antes de que el consumer resuelva el mensaje, este mensaje se marca como available para otro consumer, lo que duplica el procesamiento.

Para operaciones que se puedan pasar del lock duration hay dos opciones

  • extender el lock llamando a receiver.renew_message_lock() periodicamente durante el reprocesado
  • Usar la clase AutoLockRenewer la cual automáticamente renueva el lock en background las veces configuradas (es la opción más simple)

/IMPORTANTE

# Code fragment - focus on automatic lock renewal for long-running processing
from azure.servicebus import ServiceBusClient, AutoLockRenewer
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    renewer = AutoLockRenewer()
    with client.get_queue_receiver(
        queue_name="inference-requests",
        max_wait_time=30
    ) as receiver:
        for msg in receiver.receive_messages():
            # Renew the lock for up to 10 minutes
            renewer.register(receiver, msg, max_lock_renewal_duration=600)
            result = run_long_inference(msg)
            receiver.complete_message(msg)
    renewer.close()

Para operaciones realmente largas que consistemente se salten el tiempo y haya que extenderlo, es recomendable un approach en 2-fases

  1. El consumer recibe el mensaje, almacena la request en algún tipo de store persistente y lo marca como completado
  2. Un proceso standalone se encarga de coger las requests de ese store persistente e ir procesándolas a su ritmo

Este approach se salta el lock management y usa la queue solo para un reliable initial delivery

Read More

Structure messages (Service Bus)

El cómo estructuramos un mensaje determina como de eficientemente podemos procesar las requests. Con una buena estructura puedes hacer debug de los fallos, incluir metadatos para routing y tracking, y mantenernos dentro de los límites de nuestro tier de Service Bus.

Message anatomy

Un message de Service Bus se compone de:

  • body: lleva el payload. primary data que quieres transmitir
  • app properties: custom key-value metadata. util para enrutar, filtrar y trackear
  • system properties: propiedades añadidas por Service Bus o el SDK. Ejemplo message_id

Serializar prompts y model params

Podemos estructurar el body de un mensaje como JSON payload con todos los campos que necesita el consumer

El campo message_id se usa para identificar mensajes dentro de Service Bus. Si se activa duplicate detection en la queue, se usa este ID para descargar duplicados. Generar siempre un ID único por mensaje para evitar problemas de duplicación

# Code fragment - focus on creating a message with a JSON payload
import json
import uuid
from azure.servicebus import ServiceBusMessage

request_payload = {
    "prompt": "Extract the contract parties and effective date from this document.",
    "model": "gpt-4o",
    "temperature": 0.1,
    "max_tokens": 2000,
    "document_id": "doc-2025-0142"
}

message = ServiceBusMessage(
    body=json.dumps(request_payload),
    content_type="application/json",
    message_id=str(uuid.uuid4()),
    correlation_id="req-abc-12345",
    application_properties={
        "model_name": "gpt-4o",
        "priority": "standard",
        "document_type": "contract"
    }
)

Track requests w. correlation IDs

El correlation_id ofrece end-to-end request tracking a lo largo de la pipe. Debemos generar un ID único para cada request, ya que el mismo ID sigue al request desde el producer que lo encola, al consumer que lo procesa y al results store.

Al hacer debug de una inferencia fallida, puedes buscar los logs, colas y result stores por el correlation_id y ver el full lifecycle de la request.

# Code fragment - focus on propagating trace context in application properties
from opentelemetry import trace

current_span = trace.get_current_span()
span_context = current_span.get_span_context()

message = ServiceBusMessage(
    body=json.dumps(request_payload),
    correlation_id=correlation_id,
    application_properties={
        "traceparent": f"00-{format(span_context.trace_id, '032x')}-{format(span_context.span_id, '016x')}-01",
        "model_name": "gpt-4o"
    }
)

Handle large payloads with the claim-check pattern

Service Bus Standard tier soporta solo mensajes de 256 KB - el premium soporta hasta 100 MB.

El claim-check pattern permite separar el payload del mensaje. El producer encola un payload demasiado grande a Azure Blob Storage (u otro storage persistente) y envía al Service Bus un mensaje que contiene solo la blob URI como referencia.

De este modo el body se mantiene pequeño y solo mandamos la URL junto a los metadatos que necesitemos. El processor obtiene la el payload del storage usando la misma URI, y opcionalmente, borra el blob.

Esto también reduce los costes del broker throughput ya que hace las transferencias realmente pequeñas, y se puede usar en el Standard tier

# Code fragment - focus on the claim-check pattern for large payloads
import json
from azure.storage.blob import BlobServiceClient
from azure.servicebus import ServiceBusMessage

# Producer: upload the large payload to Blob Storage
blob_service = BlobServiceClient(
    account_url="https://<storage-account>.blob.core.windows.net",
    credential=credential
)
container_client = blob_service.get_container_client("documents")
blob_client = container_client.get_blob_client("doc-2025-0142.pdf")
blob_client.upload_blob(large_document_bytes)

# Send a claim-check message with the blob URI
claim_check = {
    "blob_uri": f"https://<storage-account>.blob.core.windows.net/documents/doc-2025-0142.pdf",
    "document_id": "doc-2025-0142",
    "model": "gpt-4o",
    "operation": "extract"
}

message = ServiceBusMessage(
    body=json.dumps(claim_check),
    content_type="application/json",
    correlation_id="req-abc-12345",
    application_properties={"pattern": "claim-check"}
)

Message TTL

La propiedad time_to_live define el tiempo de expiracion de un mensaje.

Cuando los mensajes expiran se pueden enrutar a la dead-letter queue paras ver los mensajes que no se procesaron a tiempo

# Code fragment - focus on setting time-to-live
from datetime import timedelta
from azure.servicebus import ServiceBusMessage

# Real-time classification: expire after five minutes
urgent_message = ServiceBusMessage(
    body=json.dumps(request_payload),
    time_to_live=timedelta(minutes=5)
)

# Batch processing: expire after 24 hours
batch_message = ServiceBusMessage(
    body=json.dumps(batch_payload),
    time_to_live=timedelta(hours=24)
)

Para batch processing donde la latencia no importa tanto es importante poner un TTL grande u omitirlo y usar el default de la queue

Batch messages for throughput

Cuando necesitamos enviar varias requests de a una usamos ServiceBusMessageBatch para agrupar mensajes en una única operación. Batchear reduce el numero de network round trips entre la app y el Service Bus broker.

El SDK administra el batch size automáticamente, asegurando que el total batch no se pasa del maximum size para tu tier.

El add_message() lanza MessageSizeExceededError cuando el mensaje se pasaría del batch size limit.

# Code fragment - focus on batch message sending
from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.servicebus.exceptions import MessageSizeExceededError
import json

with client.get_queue_sender("inference-requests") as sender:
    batch = sender.create_message_batch()

    for request in pending_requests:
        message = ServiceBusMessage(
            body=json.dumps(request),
            content_type="application/json"
        )
        try:
            batch.add_message(message)
        except MessageSizeExceededError:
            # Batch is full, send the current batch and start a new one
            sender.send_messages(batch)
            batch = sender.create_message_batch()
            batch.add_message(message)

    # Send any remaining messages in the last batch
    if len(batch) > 0:
        sender.send_messages(batch)

Read More

Queues vs topics & subscriptions (Service Bus)

La primera decisión de ARQ con Azure Service Bus debe ser si usamos queues o topics + subscriptions.

Queues vs Topics

IMPORTANTE

Usamos queues cuando:

  • un único consumer necesita actuar en cada mensaje: Una pipe de doc extraction recibe un prompt, ejecuta un modelo, devuelve resultados
  • we want competing consumers for horizontal scaling: multiples consumers hacen pull de la misma queue. Service Bus asegura que cada mensaje solo es entregado a un único worker
  • no hay otros servicios que necesiten el mismo mensaje: el mensaje representa una task que se da por completado cuando un consumer lo ha procesado

Usamos topics + subscriptions cuando:

  • multiples servicios independientes reaccionan al mismo mensaje: una inferencia completa hace trigger de notificaciones, audit logs, dashboards y KPIs que se actualizan simultaneamente
  • necesitas content-based routing: Diferentes consumers reciben diferentes subsets de mensajes basándose en propiedades como priority level o document type
  • quieres añadir nuevos consumers sin modificar el producer: podemos crear nuevas subscriptions en cualquier momento sin tener que tocar el código del producer

/IMPORTANTE

Queues (single consumer)

Una queue de Service Bus entrega cada message a un único consumidor. Cuando tienes múltiples consumidores leyendo de la misma cola, Service Bus se asegura que cada mensaje sea procesado por un único consumidor.

Puedes escalar horizontalmente añadiendo más consumidores sin cambiar código. Cada consumidor se conecta de manera independiente a la queue, hace pull de los mensajes y los procesa.

Hay dos modos para controlar el ack:

  • Receive-and-delete mode: Service Bus borra el mensaje de la queue tan pronto como ha sido entregado
  • Peek-lock mode (default): Service Bus bloquea el message por una cantidad de tiempo y espera a que el consumidor explicitamente la complete, la abandone o lo marque como dead. Es el modo recomendado ya que provee at-least-once delivery. Si un consumer se crashea durante el procesado, el lock expira y el Service Bus lo vuelve a mandar a otro consumer

Las queues usan FIFO y se pueden usar para multi-step pipelines donde todos los pasos se deben ejecutar en orden

Topics + subscriptions (multiple consumers independientes)

Un Service Bus topic acepta mensajes de producers y distribuye copias a cada consumer subscrito. Cada subscripcion actua como una cola virtual independiente con sus propios consumidores.

Esté patrón se usa para escenarios donde múltiples servicios necesitan reaccionar al mismo evento de manera independiente. Ejemplo: terminamos el análisis de un documento y necesitamos notificar una alerta al usuario, un log para la BBDD para poder auditar, un aviso para el sistema de KPIs, etc. Cada subscripción procesa la copia del mensaje de manera independiente, por lo que un fallo en un sistema no afecta al resto.

Los Topics desacoplan los producers de los consumers. El producer publica mensajes a un topic sin saber cuantas subscripciones existen o lo que cada consumer hace con los mensajes. Puedes añadir nuevas subscripciones sin modificar código. Es muy util para comenzar con las necesidades y requisitos actuales y añadir nuevos servicios a medida que los necesitas sin modificar el código del resto.

Filter messages with subscription rules

Las subscriptions soportan filter rules que seleccionan messages según basándose en propiedades, permitiendo enrutar mensajes selectivamente sin escribir esa lógica en cada consumer.

IMPORTANTE

Service Bus evalúa filter rules al broken level, por lo que los mensajes que no hagan match con los filtros de una subscripción nunca se entregan a la subscripción de ese consumer.

Hay 3 tipos de filtros

  • Boolean filters: TrueFilter (default) acepta todos los mensajes; FalseFilter rechaza todos los mensajes
  • SQL filters: usa SQL-like expressions para evaluar contra app y system properties del mensaje
  • Correlation filters: matchean contra specific property values. Son más eficientes que los filtros SQL para exact-match scenarios

Se puede hacer tag de messages con app properties como model_name, priority o document_type y cada subscripción recibe solo mensajes que hacen match de ese filtro.

/IMPORTANTE

Ejemplo: filtramos por priority=high para enrutar peticiones urgentes a una VM con capacidad de GPU reservada.

# Code fragment - focus on creating a subscription rule with the management client
from azure.servicebus.management import ServiceBusAdministrationClient, SqlRuleFilter

admin_client = ServiceBusAdministrationClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
)

admin_client.create_rule(
    topic_name="inference-results",
    subscription_name="high-priority",
    rule_name="filter-high-priority",
    filter=SqlRuleFilter("priority = 'high'")
)

Send messages with queue/topic senders

El SDK azure-servicebus usa el mismo ServiceBusClient para ambos queues y topics.

  • get_queue_sender() envía a una queue
  • get_queue_receiver() queue el consumer

  • get_topic_sender() publica en un topic
  • get_subscription_receiver() subscribe el consumer

En el receiving side, un subscription consumer se conecta a una subscripción específica en un topic. Cada subscripcion mantiene su propia copia de los mensajes, por lo que consumir de una subscripcion no afecta a la disponibilidad de mensajes de otras subscripciones.

ServiceBusClient se usa junto a with statements para asegurar que las conexiones se cierran. Es lo mismo que llamar manualmente a client.close()

# Code fragment - focus on sending to a queue versus a topic
from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with ServiceBusClient(
    fully_qualified_namespace="<namespace>.servicebus.windows.net",
    credential=credential
) as client:
    # Send to a queue (point-to-point)
    with client.get_queue_sender("inference-requests") as queue_sender:
        queue_sender.send_messages(
            ServiceBusMessage("queue message body")
        )

    # Send to a topic (publish-subscribe)
    with client.get_topic_sender("inference-results") as topic_sender:
        topic_sender.send_messages(
            ServiceBusMessage("topic message body")
        )
# Code fragment - focus on receiving from a subscription
with client.get_subscription_receiver(
    topic_name="inference-results",
    subscription_name="notifications"
) as receiver:
    for msg in receiver:
        print(str(msg))
        receiver.complete_message(msg)

Read More

Azure Service Bus

Azure Service Bus es un broker managed que provee de queuing y pub/sub para apps distribuidas. Sirve de capa de conexión media entre productores y consumidores. Por debajo usa AMQP (Advanced Message Queuing Protocol). Soporta ordering y detecta duplicados.

Tiene dos tipos de funcionamiento:

  • queues (point-to-point delivery)
  • topics + subscriptions (pub/sub o broadcast)

Cada service bus reside dentro de un namespace que sirve como contenedor y provee de allocation capacity. Puedes crear múltiples queues y topics dentro de un mismo namespace, y cada namespace tiene su propio endpoint en la forma <namespace-name>.servicebus.windows.net.

Para autenticar usa SAS (Shared Access Signatures) o Entra ID.

Why to use messaging

Las AI inference ops tienen una latencia no predecible, lo cual no está hecho para sync requests. Un documento simple puede tardar 2s y uno complejo 5m.

Messaging provee de un desacoplamiento entre producer y consumer. El producer envía un message al Service Bus queue y devuelve directamente un acknowledgment (ack) al cliente.
El consumer hace retrieve de los mensajes de la queue a su propio ritmo.

Este desacoplamiento permite escalar horizontalmente de manera independiente.

Core messaging patterns

Load leveling

El load leveling pattern usa una queue para absorber burst de requests, permitiendo a los consumidores que procesen a un ritmo estable.

Durante un pico de tráfico los mensajes se acumulan en la cola en vez de poner estrés a los consumers. Simplemente trabajan en el backlog independientemente del tamaño de este.

Competing consumers

El competing consumers pattern pone varios consumers como recibidores de una misma queue. El Service Bus entrega cada mensaje a un solo consumidor, por lo que los consumers leen de la misma cola sin procesar duplicar trabajo.

Cada consumer procesa a su propio maximum rate y podemos añadir más consumidores para incrementar el throughput sin ahcer cambios de código.

Si un consumer se crashea, como no ha hecho ack de la task, esta se pone como disponible para otros workers.

Temporal decoupling

El temporal decoupling pattern significa que los productores y los consumidores no tienen que estar online de manera simultánea. Un producer puede encolar requests con todos los consumers offline (por mantenimiento, deployment, etc).

Los mensajes se persisten en la cola hasta que los consumers vuelven y los procesan.

Esto se usa para critical AI platforms.

Manage backpressure with queue depth monitoring

Si la queue incrementa demasiado los mensajes se acumulan. En vez de tratar esto como un problema, podemos usarlo como nuestro trigger que nos indique cuando tenemos que escalar consumers.

Azure Monitor provee de métricas para revisar active message count para cada queue, y puedes activar alertas cuando superen un umbral custom

Azure Container Apps y Azure Functions soportan KEDA-based scalers que automáticamente añaden processing instances basandose en el Service Bus queue length

Service Bus Tiers

Standard Tier

Soporta queues, topics y subscriptions con recursos compartidos con otros tenants. Mensajes hasta 256 KB y variable throughput basado en la carga. Versión cost-effective.

Premium Tier

Ofrece recursos dedicados, por lo que tu workload no comparte con otros tenants. Soporta mensajes hasta 100 MB al usar AMQP (1 MB para HTTP). Ofrece latencia predecible y VNET integration / private endpoints. También ofrece availability zones.

Read More