TL;DR: Agilizando diagnósticos no Azure App Service
Este artigo apresenta uma nova coleção de comandos (aliases) SSH agora disponíveis de forma nativa no Azure App Service para Linux. A ferramenta transforma diagnósticos complexos e manuais em comandos de uma única palavra. A conclusão é que, ao utilizar esses helpers, times de engenharia ganham eficiência para identificar a causa raiz de falhas (como DNS, conectividade AI ou dependências faltantes) sem a necessidade de reconstruir containers ou executar comandos sequenciais manuais e propensos a erros.
Você realizou o deploy de uma aplicação Python no App Service. O software passou no ambiente de desenvolvimento e funciona perfeitamente localmente. No entanto, em produção, o endpoint /chat retorna erros 502, enquanto /health responde positivamente, os logs não indicam nada e é impossível reproduzir o incidente na sua máquina local.
O que você realmente precisa é de um shell direto no container para investigar DNS, environment variables, pacotes instalados e o endpoint de IA que a aplicação consome. Embora o SSH já fosse uma opção no Azure, o "playbook" tradicional de abrir uma conexão e executar dezenas de comandos era um conhecimento fragmentado dentro dos times.
Recentemente, a Microsoft disponibilizou um conjunto de SSH helper aliases que transformam esse conhecimento em comandos de uma única palavra. O apphelp exibe a lista completa de aliases disponíveis. Ferramentas como appconfig, showpkgs e appcurl cobrem o lado da aplicação, enquanto comandos como ai-test, ai-diagnose, ai-dns e ai-latency facilitam a depuração em interações com Azure AI Foundry.
O setup de diagnóstico: apphelp
Após o deploy, a primeira ação dentro do container é executar o apphelp. Ele categoriza os comandos disponíveis, eliminando a necessidade de memorizar sintaxes complexas:
- App info:
showpkgs,appconfig,appenv - Logs:
applogs,deploylogs,logfiles - Reachability:
appcurl,checkport,gohome,gosrc - AI/Foundry:
ai-test,ai-dns,ai-access-check,ai-curl,ai-latency,ai-diagnose - Network tools:
install-nettools
Validando o baseline com ai-diagnose
Antes de investigar falhas, utilize o ai-diagnose. É o cheque rápido para validar se o caminho para o serviço de IA está íntegro, verificando a identidade gerenciada, resolução de DNS e latência de endpoint.
O desafio do ambiente: Sincronizando o shell com a aplicação
Um erro comum é tentar testar uma falha via SSH sem que o shell tenha acesso ao estado atual do processo da aplicação. Como o shell SSH é um processo separado, a dica de ouro é utilizar:
source /home/site/diagnostics/fault.env
Ao usar esse padrão em seu código, você garante que qualquer alteração de estado (como a injeção de uma falha de configuração) seja refletida no ambiente de depuração.
Categorização de falhas: Onde olhar?
- Erros de rede e endpoints (
ai-dns,ai-curl): Falhas que impedem a comunicação entre o App Service e o AI Foundry. - Erros que passam no
ai-test, mas falham na app: Sinaliza que a plataforma está íntegra e o problema está no código ou na configuração da aplicação (ex:AZURE_CLIENT_IDincorreto ou falta de dependências norequirements.txt).
Conclusão: Uma nova workflow de debug
O uso desses aliases altera drasticamente a agilidade da equipe de engenharia. A recomendação da Nuvem Online é que times de SRE e desenvolvedores sempre comecem a depuração pelo apphelp e ai-diagnose. Entender que um ai-test positivo é um sinal de que a plataforma está operante, permitindo o "pivô" imediato para o log da aplicação, reduz drasticamente o Mean Time To Repair (MTTR).
Perguntas Frequentes
-
O que são os novos SSH helper aliases no Azure App Service?
São uma coleção de comandos pré-configurados (como 'apphelp', 'ai-diagnose', 'ai-latency') que automatizam o acesso a logs, variáveis de ambiente e diagnósticos de conectividade de rede e serviços AI de maneira simplificada, sem exigir conhecimento tribal complexo. -
Como identificar se a origem de uma falha é a plataforma ou o código?
A recomendação é executar o 'ai-diagnose'. Se as verificações retornarem erro, o problema está na infraestrutura (DNS, Managed Identity ou conectividade). Se o diagnóstico estiver saudável, mas a aplicação continuar falhando, a causa reside tipicamente na configuração da aplicação ou no código. -
Por que o meu shell SSH apresenta um ambiente diferente da aplicação?
O shell SSH é um processo separado que herda o ambiente do container no momento da criação. Para diagnosticar a aplicação corretamente, é necessário executar 'source /home/site/diagnostics/fault.env' para carregar as variáveis de ambiente ativas que a aplicação está utilizando no runtime.
Artigo originalmente publicado em Azure Updates - Latest from Azure Charts.
