Runbook de incidentes A2P SMS: detetar, delimitar e gerir degradações de entrega

O que constitui uma degradação de entrega A2P SMS

Um incidente A2P SMS não tem de ser uma interrupção total. Pode surgir como um aumento de mensagens pendentes, uma redução dos estados finais de entrega, mais erros antes do envio, maior latência até ao estado final ou um comportamento diferente numa combinação específica de destino, remetente, codificação ou rota.

O objetivo de um runbook não é transformar um sinal inicial numa conclusão precipitada. É criar um processo repetível para determinar que parte do serviço está afetada, que evidências existem e que medidas podem ser aplicadas sem agravar a situação nem violar requisitos locais, controlos antiabuso ou regras de consentimento.

A primeira disciplina operacional consiste em não usar “entregue” como sinónimo de “enviado”. Uma mensagem aceite por um fornecedor ou operadora a montante não equivale, por si só, a uma confirmação de entrega ao utilizador final.

• Degradação de conectividade: a interface HTTP ou SMPP não responde de forma fiável, apresenta erros ou aumenta a sua latência.
• Degradação de aceitação: os pedidos não chegam a ser aceites a montante ou falham antes de avançar.
• Degradação dos estados finais: aumenta a proporção de mensagens pendentes, não entregues, desconhecidas ou bloqueadas, de acordo com a taxonomia disponível.
• Degradação de latência: os estados finais continuam a chegar, mas mais tarde para uma coorte específica.
• Degradação de observabilidade: o envio pode continuar, mas os callbacks ou a ingestão de eventos estão atrasados, incompletos ou com falhas.

Definir o serviço e os seus limites de evidência

Antes de ativar um incidente, defina o que cada estado representa na sua integração. Muitas plataformas distinguem entre estados de fila, envio, aceitação pela operadora a montante, entrega reportada e falha. Os nomes podem variar, mas o runbook deve documentar o significado concreto de cada um para cada fornecedor ou interface.

A aceitação a montante é uma evidência útil de progresso, não uma prova absoluta de receção no terminal. Da mesma forma, um estado reportado como entregue depende da informação recebida através da cadeia de mensagens. A receção real no dispositivo nem sempre pode ser demonstrada de forma independente pela telemetria do fornecedor.

Também é necessário separar o estado da mensagem da saúde do canal de observabilidade. Se o endpoint de callback falhar, as mensagens podem continuar a ter estado na plataforma de origem, mesmo que o seu sistema não tenha recebido o evento.

• Resultado imediato do envio: resposta HTTP ou PDU SMPP, identificador atribuído e erro, se existir.
• Estado assíncrono: transição posterior recebida através de callback, stream de eventos ou consulta do recurso da mensagem.
• Entrega reportada: confirmação disponível através da operadora ou do canal correspondente.
• Receção no terminal: nível de certeza limitado pelas evidências que o ecossistema de entrega consegue reportar.
• Observabilidade: disponibilidade, atraso e completude de callbacks, consultas e processos internos de ingestão.

Os sinais mínimos de deteção

A deteção deve combinar sinais de volume, estado, tempo e conectividade. Uma única métrica é normalmente ambígua: uma redução de entregues pode indicar um problema real, mas também um aumento temporário de mensagens ainda pendentes ou uma falha na receção de eventos.

Meça taxas por estado em coortes comparáveis e separe os estados finais dos não finais. Um aumento de pendentes exige observar a sua evolução e antiguidade antes de o classificar como falha. Estabeleça janelas temporais coerentes com as suas expectativas operacionais e com a possibilidade de receber eventos tardios.

Quanto à latência, registe as marcas temporais de aceitação, transição e chegada dos eventos. Analise percentis além das médias: uma média estável pode ocultar uma fila significativa numa parte do tráfego.

• Volume aceite, com falha e pendente por intervalo.
• Proporção de estados finais por coorte, separada de mensagens ainda não finalizadas.
• Latência entre aceitação e estado final, observada por percentis.
• Erros HTTP, códigos de erro do fornecedor, erros SMPP e taxas de reconexão.
• Tempo de resposta e sucesso das verificações de ligação SMPP através de enquire_link e enquire_link_resp.
• Disponibilidade do endpoint de callback, códigos de resposta, tentativas e atraso de ingestão.
• Profundidade, antiguidade e ritmo de escoamento das filas próprias.

Segmentar antes de diagnosticar

Não diagnostique uma coorte mista como se fosse uma rota homogénea. Segmente antes de atribuir causa ou impacto. O mesmo sintoma pode estar limitado a um país, uma rede móvel, um remetente, um tipo de tráfego, uma codificação, mensagens multipartes ou uma janela temporal específica.

Conserve os atributos disponíveis na sua telemetria e utilize sempre a mesma definição de coorte durante o incidente. Se alterar a segmentação entre atualizações, registe a alteração e evite comparar percentagens calculadas sobre populações diferentes.

A codificação e o número de partes merecem atenção específica. Os alfabetos de dados, incluindo UCS2, e as mensagens divididas em várias partes podem não ser comparáveis a mensagens de uma só parte com o alfabeto predefinido.

• Destino: país, rede móvel quando disponível e prefixo ou agrupamento definido internamente.
• Origem: remetente, tipo de identificador e configuração aplicável.
• Tráfego: OTP, transacional, alertas ou outros grupos operacionais legítimos.
• Conteúdo técnico: codificação, número de partes e modelo ou versão de conteúdo quando registados.
• Rota ou fornecedor: apenas quando esse atributo estiver disponível e for fiável na sua própria telemetria.
• Tempo: início observado, intervalo afetado e comparação com uma janela de referência equivalente.

Classificação inicial do incidente

A classificação inicial não deve afirmar uma causa raiz. Deve orientar a triagem, a mitigação e a escalação. Utilize categorias que possam ser revistas à medida que chegam eventos tardios ou evidências adicionais.

Uma verificação SMPP bem-sucedida com enquire_link confirma a saúde básica da ligação de protocolo quando a resposta correlacionada é recebida com sucesso. Não confirma que as mensagens estejam a chegar aos terminais. Por isso, a conectividade e a entrega devem ser mantidas como dimensões separadas no registo do incidente.

• Conectividade da interface: erros de sessão, timeouts, falhas de autenticação, reconexões ou ausência de resposta de ligação.
• Falha antes do envio: pedidos rejeitados ou mensagens que não avançam a partir do sistema emissor.
• Aceitação sem estado final: mensagens aceites que acumulam antiguidade sem confirmação posterior.
• Não entrega final: aumento de estados de não entrega, expiração, destinatário inacessível ou outros códigos reportados.
• Bloqueio ou filtragem reportados: estados ou códigos associados a spam, bloqueio pela operadora ou política, quando o canal os expuser.
• Falha de callback ou observabilidade: o estado pode existir na origem, mas não chega ou chega tarde ao seu sistema.
• Anomalia de medição: alterações de instrumentação, duplicados, perda de eventos ou segmentação incorreta.

Triagem passo a passo nos primeiros minutos

O primeiro objetivo é preservar a capacidade de investigação. Antes de alterar rotas, limites ou configurações, capture uma imagem das métricas e uma amostra de mensagens representativa. Em seguida, confirme se o problema está na emissão, na aceitação, na entrega reportada ou na observabilidade.

Trabalhe do geral para o específico. Verifique primeiro se existe um problema de plataforma ou conectividade partilhado; depois delimite por coorte. Evite declarar que uma rede móvel ou um fornecedor é a causa sem uma comparação controlada e dados correlacionáveis.

• 1. Abrir o registo com a hora de deteção, quem detetou, o sintoma, os serviços envolvidos e o impacto ainda desconhecido.
• 2. Capturar taxas por estado, distribuição de antiguidade dos pendentes, percentis de latência, erros de interface, saúde de callbacks e profundidade de filas.
• 3. Verificar a conectividade HTTP ou SMPP. Em SMPP, confirmar a correlação correta entre enquire_link e enquire_link_resp.
• 4. Comparar o intervalo afetado com uma janela de referência equivalente e segmentar por destino, remetente, tráfego, codificação, partes e rota disponível.
• 5. Rever uma amostra de identificadores de mensagens com as suas respostas iniciais, estados originais, erros e marcas temporais.
• 6. Consultar o estado na plataforma de origem quando os callbacks estiverem ausentes ou forem suspeitos.
• 7. Classificar provisoriamente, atribuir um responsável técnico e decidir se é adequada uma mitigação limitada.
• 8. Registar cada alteração, o respetivo momento, a coorte à qual se aplica e o resultado observado.

Mensagens de teste: úteis, mas não conclusivas

As mensagens de teste servem para verificar hipóteses concretas, não para demonstrar por si só o estado de toda uma rota. Um único dispositivo pode ter condições particulares: cobertura, disponibilidade temporária, configuração, armazenamento ou comportamento próprio do terminal.

Utilize destinos autorizados e números corretamente normalizados, geralmente de acordo com o plano internacional E.164 quando aplicável. Mantenha o teste mínimo, rastreável e equivalente à coorte que pretende observar: mesmo destino ou grupo de destinos, remetente, classe de tráfego permitida, codificação e estrutura da mensagem.

Não utilize testes para contornar filtros, controlos antiabuso, consentimento ou requisitos locais. Se um sinal apontar para bloqueio ou filtragem, a resposta correta é rever a conformidade, a configuração e as evidências disponíveis, e não alterar o conteúdo para tentar contornar os controlos.

• Defina a hipótese antes de enviar o teste.
• Utilize números de teste autorizados e evite incluir dados sensíveis.
• Registe identificador, origem, destino, hora, codificação, número de partes, resultado inicial e estados posteriores.
• Compare várias amostras homogéneas quando o volume e os controlos operacionais o permitirem.
• Confronte o resultado com a telemetria agregada; não extrapole a partir de um único terminal.
• Se o problema parecer limitado a poucos dispositivos, exclua causas próprias desses dispositivos antes de o atribuir à rota.

Mitigação controlada e proteção do tráfego crítico

A mitigação deve reduzir o risco enquanto mantém a rastreabilidade. Não aplique alterações globais com base num sinal limitado a uma coorte. Priorize medidas reversíveis, limitadas no tempo e documentadas.

Quando houver congestionamento, aumento de filas ou erros de capacidade, o controlo de ritmo, a priorização e as pausas seletivas podem proteger o tráfego mais crítico. Em cenários OTP ou transacionais, separe as filas por prioridade se a sua arquitetura o permitir e aplique os limites definidos pelas suas integrações e acordos.

As rotas alternativas só devem ser utilizadas quando estiverem autorizadas, configuradas e forem adequadas ao destino e à classe de tráfego. Uma alternativa não deve ser usada para evitar controlos de remetente, consentimento, conteúdo ou regulamentação local.

• Priorizar o tráfego OTP e transacional crítico em relação ao tráfego menos urgente, de acordo com as suas regras internas.
• Aplicar limites de ritmo ou pausas controladas à coorte afetada caso existam sinais de saturação ou falhas persistentes.
• Ajustar a gestão de filas e monitorizar a antiguidade das mensagens para evitar que percam utilidade operacional.
• Aplicar rotas alternativas previamente autorizadas apenas às coortes permitidas e registar a alteração.
• Não repetir indiscriminadamente mensagens já aceites: isso pode aumentar duplicados, carga e complexidade de reconciliação.
• Não tratar um bloqueio ou filtragem reportados como um problema de capacidade que possa ser resolvido aumentando o volume.