Platform For AI:Queue service subscription and pushing

A assinatura e o push enviam dados prontos imediatamente ao cliente, o que reduz a latência do polling via API Get e diminui a carga gerada por consultas no serviço de fila. No entanto, esse recurso apresenta certa complexidade, pois envolve diversos conceitos adicionais. Este tópico descreve como utilizar a funcionalidade de assinatura e push do serviço de fila.

Consumer

Um consumer é um programa cliente que assina dados do serviço de fila. Quando o cliente utiliza a API Watch para solicitar dados, o serviço de fila cria um objeto consumer. Os parâmetros da API (como tamanho da janela e tags) tornam-se atributos desse consumer. Para visualizar o status do consumer, utilize a API Attribute. Exemplo:

[OK] Attributes: 
consumers.list.[0] : Id: default_group.u1, Index: 0, Pending: 0, Status: Complete, Idle: 2.091s, Window: 0, Slots: 0, AutoCommit: true
consumers.list.[1] : Id: default_group.u2, Index: 0, Pending: 0, Status: Complete, Idle: 1.124s, Window: 0, Slots: 0, AutoCommit: true
consumers.stats.total : 2

consumers.stats.total indica o número total de consumers. consumers.list representa a lista de consumers. A tabela a seguir descreve as colunas:

Ao utilizar a API Watch com filtro de dados, uma coluna adicional chamada Tags será exibida. Exemplo:

consumers.list.[0] : Id: ..., Pending: 0, ..., Window: ..., Tags: tags[foo=bar]

Essa coluna mostra as tags de dados às quais o consumer está inscrito. Os dados são entregues ao consumer apenas quando atendem às condições especificadas.

Consumer group

Um consumer group é um conjunto de consumers que assinam o serviço de fila com as mesmas condições de filtro. Consumers dentro do mesmo grupo não podem ter nomes idênticos, mas consumers em grupos diferentes podem compartilhar o mesmo nome.

Dentro de um mesmo consumer group, os dados são distribuídos uniformemente entre os consumers. Entre grupos distintos, os dados são enviados em paralelo para os consumers de cada grupo. Por exemplo:

• Consumers no mesmo grupo recebem dados diferentes.

• Consumers em grupos diferentes recebem os mesmos dados.

Para visualizar o status do consumer no serviço de fila, utilize a API Attribute. Veja o exemplo abaixo:

groups.list.[0] : Id: default_group, Index: 0, Pending: 0, Delivered: 0, Consumers: 1
groups.list.[1] : Id: group, Index: 0, Pending: 0, Delivered: 1, Consumers: 0

groups.list corresponde à lista de consumers. A tabela a seguir detalha as colunas:

Não há limite para o número de consumer groups, mas eles não são limpos automaticamente. Após a criação, seu status é mantido permanentemente.

Uso de consumers e consumer groups

Declare o consumer e o consumer group por meio de cabeçalhos HTTP na API Watch ou durante a inicialização do cliente no SDK. Também é possível obter a chave do cabeçalho HTTP usando a API Attributes.

meta.header.group : X-EAS-QueueService-Gid
meta.header.user : X-EAS-QueueService-Uid

Utilize X-EAS-QueueService-Uid e X-EAS-QueueService-Gid para declarar, respectivamente, o ID do consumer e o ID do consumer group ao qual deseja ingressar.

Commit e Negative

O serviço de fila oferece dois métodos de consumo: Commit e Negative. Ambos operam sobre o Index dos dados, mas possuem semânticas distintas.

• Commit sinaliza que o consumer recebeu e processou os dados com sucesso, permitindo o envio do próximo lote.

• Negative indica que o consumer recebeu os dados, mas não conseguiu processá-los. Nesse caso, o serviço de fila decide se deve enviar o próximo lote com base no código de erro retornado. No modo Negative, declare a causa e o código de erro em texto para que os dados sejam redirecionados a outros consumers. A tabela abaixo lista os códigos de erro especiais tratados pelo serviço de fila:

  Code	Description
  Shutdown	Indica que o consumer está encerrando e o serviço de fila deve parar de enviar dados.

Rebalanceamento de dados

Em alguns cenários, pode não ser possível confirmar (commit) os dados:

• Durante uma atualização contínua (rolling update) do serviço de previsão, alguns consumers são finalizados, deixando dados em processamento sem confirmação.

• Ocorre um erro interno e o consumer falha.

• O consumer não consegue processar os dados recebidos e executa um commit do tipo Negative.

O serviço de fila redistribui dados não processados para outros consumers. Esse mecanismo é chamado de rebalanceamento de dados. O rebalanceamento ocorre nas seguintes situações:

• Qualquer consumer entra no estado Exit.

• O consumer não recebe novos dados via push mesmo havendo espaço livre na janela.

O serviço de fila mantém um contador de entregas para cada dado. Sempre que um dado é rebalanceado e redistribuído, esse contador é incrementado. Se, durante o rebalanceamento, o contador de entregas de um dado ultrapassar o limite máximo permitido, o dado é tratado como dead letter. O serviço de fila então aplica a política configurada para dead letters. Por padrão, o dado é enviado para a tail queue.

Tail queue

A tail queue é uma fila auxiliar usada para armazenar dados que não foram entregues aos consumers (como dead letters ou dados de controle personalizados). Trata-se de uma instância de fila dentro do próprio serviço de fila, compartilhando a mesma API. Cada fila de entrada e saída possui sua própria tail queue.

Ao chamar a API, adicione o seguinte cabeçalho HTTP para acessar a tail queue:

X-EAS-QueueService-Access-Rear: true