Azure Service Bus: monitorar filas, dead letter e purge
O menu Azure Service Bus monitora as filas e assinaturas de cada cliente num dashboard, mostra as mensagens dead letter (DLQ) sem travar nada e faz o purge com confirmação. Ele aparece no cliente que tem a connection string do namespace cadastrada.
O que faz
| Plano | O que mostra e faz |
|---|---|
| Free | O painel de filas e as filas e tópicos com as assinaturas, e as contagens de mensagens ativas, na DLQ e agendadas. Só leitura. |
| Pro e Team | Espiar as primeiras mensagens da fila, da assinatura ou da DLQ, com propriedades, motivo da DLQ e corpo. Purgar a fila, a assinatura ou só a DLQ. |
Painel de filas do Azure Service Bus: o dashboard
A aba Painel é a que abre primeiro no menu Azure Service Bus: todas as filas e assinaturas do cliente numa tela, atualizada a cada 15 segundos (dá para trocar para 30 s ou 60 s, ou pausar). Só contagens e nomes: o conteúdo das mensagens nunca entra no painel.
| Plano | O que mostra |
|---|---|
| Free | Os totais (filas, mensagens prontas, DLQ e filas com DLQ) e a tabela de contagens (ativas, DLQ, agendadas e em transferência), com busca, ordenação (DLQ e depois prontas, da maior para a menor), o filtro "Só com DLQ" e "Agrupar variantes", que junta filas irmãs pelo nome (-retry, -dlq, -error, -memory-error, -resume, -reprocessing). |
| Pro e Team | A variação líquida das mensagens ativas por minuto (a API do Service Bus não informa entradas e saídas separadas), a tendência do backlog nos últimos 5 minutos, o gráfico do cliente e o de cada fila, e os alertas abaixo. |
Clicar numa fila abre o detalhe numa gaveta, como o do pod. Espiar a fila ou a DLQ abre as mensagens no painel inferior, como os logs, e purgar pede o nome digitado, com as regras desta página.
Painel de filas: alertas e limites
- O limite de backlog de cada fila muda na gaveta da fila (Limite de mensagens ativas, ou Usar o padrão). Na web, só o admin define, no Pro e no Team; o limite vale para a organização e cada mudança vai para a auditoria (definir_limiar, remover_limiar). No desktop, o limite fica só na sua máquina, por cliente e fila.
- O histórico dos gráficos fica só na memória: na web, no navegador, e no desktop, no app. São os últimos 60 minutos desde que a tela abriu; recarregar ou fechar recomeça.
- A leitura do serviço tem cache de 10 segundos por cliente e serviço, com uma leitura por vez; purgar limpa o cache. O painel lê no máximo 1.000 filas e avisa quando a lista foi cortada.
- Depois de 3 erros seguidos, o painel passa a tentar a cada 60 segundos e mostra um aviso.
| Alerta | Quando aparece | Nível |
|---|---|---|
| DLQ | A DLQ tem mensagens: de 1 a 99 | Atenção (100 ou mais: crítico) |
| DLQ crescendo | A DLQ subiu nos últimos 5 minutos, contando desde a última queda, com pelo menos 60 s de histórico | Crítico |
| Pico na DLQ | A DLQ ganhou 200 ou mais mensagens entre duas amostras com menos de 60 s entre elas, nos últimos 5 minutos | Crítico |
| Sem consumo | O backlog só subiu nos últimos 10 minutos e a saída ficou abaixo de 0,1 mensagem por minuto | Crítico |
| Backlog alto | Mensagens prontas acima do limite da fila (padrão 1.000) | Atenção (10 vezes o limite: crítico) |
Ver mensagens dead letter sem travar nada (peek)
O Kubepier usa o peek do protocolo AMQP (o peekMessages do SDK oficial): a mensagem não é travada, a contagem de entregas não muda e funciona na DLQ.
Como o purge da fila e da DLQ funciona
- O Service Bus não tem operação de purga. O Kubepier recebe e apaga (receive-and-delete) em lotes, até a quantidade que havia quando o purge começou, nunca mais que isso.
- Mensagens agendadas e mensagens travadas por um consumidor não são alcançadas e ficam.
- Os corpos recebidos são descartados sem ser lidos.
- O resultado diz quantas foram removidas e, se o purge parou antes do fim, quantas restaram. Rode de novo para continuar.
- Em fila ou assinatura com sessões, só a DLQ pode ser purgada: receber a fila principal exigiria aceitar sessão por sessão.
Limites e tempos
| Limite | Valor |
|---|---|
| Mensagens por espiada | 20 por padrão, de 1 a 100 |
| Corpo de cada mensagem | até 64 KB |
| Lote do purge | 250 mensagens |
| Teto de um purge | 50.000 mensagens ou 5 minutos |
| Purgas por cliente e serviço | 5 a cada 10 minutos |
| Entidades listadas | até 1.000 filas, 1.000 tópicos e 1.000 assinaturas por tópico |
| Espera vazia que encerra o purge | 2 esperas seguidas de 3 segundos |
| Tempo de cada chamada à API de gerenciamento | 15 segundos |
Confirmações
Purgar pede que você digite o nome: o da fila, ou tópico/assinatura numa assinatura.
Auditoria
- Web: cada purga vai para a auditoria da organização, no banco: quem, quando, cliente, entidade, se foi a DLQ, quantas havia antes, quantas foram removidas, por que parou e o erro, se houve.
- Desktop: cada purga vai para o arquivo kubepier-audit.log, na pasta de dados do app, com a entidade (e /$deadletterqueue na DLQ), o resultado e quantas foram removidas.
- Web: cada limite de backlog definido ou removido no painel (definir_limiar, remover_limiar).
- Espiar não é auditado.
Permissões necessárias do seu lado
| Função | Direito da política SAS |
|---|---|
| Listar filas, tópicos e contagens | Manage (a API de gerenciamento não aceita só Listen) |
| Espiar | Listen |
| Purgar | Listen para receber e apagar, e Manage para ler a contagem inicial |
Como a listagem exige Manage, na prática o menu precisa de uma política com Manage (que inclui Listen e Send). Crie uma política só para o Kubepier no namespace.
O que não é aceito
- Espiar ou purgar no Free.
- Purgar sem digitar o nome, ou como membro (na web; no desktop, a partir da 2.7.0).
- Purgar a fila principal de uma entidade com sessões (só a DLQ).
- Connection string que não é de namespace Service Bus.
Rede e rota de conexão
No cadastro do Service Bus, escolha a Rota de conexão. Direta: se o namespace restringe IPs, libere os IPs de saída em Networking → Selected networks. Pelo cluster: para namespace com private endpoint; pela rota, o Service Bus usa AMQP sobre WebSocket na porta 443. Na rota Direta, um host que resolve só para IP privado responde host_privado na hora, sem tentar conectar. Conexão encerrada pelo servidor (conexao_encerrada) em geral é firewall sem os IPs de saída, TLS ou porta errados, ou limite de conexões: libere os IPs ou troque para Pelo cluster.
Erros comuns
- 401 ou 403: a política SAS não tem Manage (listar) ou Listen (espiar e purgar).
- "Fila ou assinatura não encontrada": a entidade foi apagada ou o nome mudou.
- Purge parou com mensagens restantes: atingiu o teto de quantidade ou de tempo; rode de novo.
- "muitas purgas" (429 na web): são 5 purgas por cliente e serviço a cada 10 minutos.