Azure API Management Monitoramento e Debug

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Community Hub.

"Se você não pode medir, não pode gerenciar" (Peter Drucker)

 

O APIM (Azure API Management) captura uma série de informações sobre requisições HTTP e HTTPS, transferência de dados, tempo de resposta, cache e muito mais. Todas essas informações podem ser visualizadas na própria instância do APIM através do menu Analytics no grupo Monitoring, também conhecido como Built-in Analytics. Esses logs são retidos de acordo com o tempo de vida da instância e possuem nível de detalhamento reduzido, o que pode dificultar análises mais profundas.

Uma boa opção é integrar o APIM com o Application Insights e o Log Analytics, aumentando a capacidade de retenção e das análises. Saiba mais

A ideia é mostrar como as ferramentas de monitoramento do Azure podem ajudar em processos de análise complexos, demonstrando como combinar recursos do APIM, Application Insights e Log Analytics para monitorar a aplicação abaixo.

 

Arquitetura

 

Arquitetura

Aqui temos um Navegador acessando o App Gateway, que repassa a requisição para o APIM. Por sua vez, o APIM acessa um backend em um App Service, que consome dados do Azure SQL Server. Esses recursos são monitorados por dois Application Insights e utilizam a mesma workspace do Log Analytics.

 

Configurar APIM com Application Insights

 

Primeiro precisamos entrar no menu Application Insights no grupo Monitoring, então associamos o APIM com uma instancia do Application Insights .Depois vá ate o menu APIS clique em uma API e acesse a aba Settings.

Nessa aba podemos especificar detalhes de como vai ser essa integração, podemos especificar características como Sampling,Verbosity, payload além de adicionar Headers que devem ser capturados.

Tela do APIM

 

Para saber mais sobre essas configurações clique aqui, depois disso podemos acessar o Application Insights e usar diversas ferramentas para analisar as requisições feitas no APIM e nos backends. saiba mais

Vamos por exemplo configurar o APIM para capturar dois Headers que podem nos ajudar em processos de troubleshooting, vamos capturar:

  1. X-Forwarded-For (Aqui temos o id do cliente que chamou o APIM, esse valor é perdido quando temos um balanceador na frente do APIM)
  2. Ocp-Apim-Trace-Location (Esse Header contem uma URL de Trace Response com dados detalhados da requisição passando pelas etapas do pipeline do apim)

Tela do APIM capturar headers customizados Aba Settings do APIM no menu API, clicando em uma API em especifica

 

Configurar APIM com Log analytics

 

Também é possível, mandar os dados para uma Workspace do Log Analytics utilizando todo o potencial do Azure Monitor e podendo cruzar tabelas de diferentes componentes da sua infraestrutura, a configuração segue a mesma lógica do Application Insights mas para integrar como a Workspace precisamos configurar a ferramenta de Diagnostic settings

Diagnostic settings do APIM

Diagnostic settings do APIM

Se você selecionar um espaço de trabalho do Log Analytics, poderá optar por armazenar os dados na tabela ApiManagementGatewayLogs específica do recurso ou armazenar na tabela AzureDiagnostics geral. Recomendamos usar a tabela específica do recurso para destinos de log que a suportam. Saber mais

Nesse caso a aba Settings das Apis não precisa apontar para a Workspace do Analytics basta a configuração do Diagnostic settings é já podemos começar a fazer consultas na Workspace especificada, por exemplo temos uma consulta das requests feitas no APIM

Tabela de Request

Quando usar ferramentas de monitoramento, como o Application Insights e o Log Analytics?

 

As ferramentas de insights sempre apresentam os dados de forma prática, compilando informações em painéis fáceis de analisar. No entanto, elas têm suas limitações em relação aos dados disponíveis dentro de um único recurso. Por exemplo, no caso do APIM, é comum termos mais de uma instância do Application Insights, uma para cada API. Nesses casos, cada instância contém apenas os dados de uma API específica, o que dificulta a totalização das requisições, por exemplo.

Ao centralizarmos todas as informações em uma única base do Log Analytics, podemos cruzar os dados provenientes de diferentes origens (tabelas), permitindo uma análise mais abrangente e completa. Essa abordagem integrada nos possibilita visualizar dados de todas as APIs em conjunto, possibilitando uma visão global do desempenho e comportamento do APIM. Dessa forma, ganhamos insights mais profundos e valiosos para melhorar a eficiência e o desempenho das nossas APIs.

Ao integrar essas duas ferramentas, obtemos uma visão holística e unificada de todo o ecossistema de aplicativos e serviços. Podemos criar dashboards personalizados que nos permitem monitorar o desempenho e a saúde do sistema em tempo real, receber alertas automáticos sobre possíveis problemas e realizar análises detalhadas para otimizar o desempenho, a escalabilidade e a eficiência dos nossos recursos de TI.

Outra vantagem de utilizar essas ferramentas em conjunto é a possibilidade de criar relatórios personalizados para diferentes equipes e partes interessadas, cada uma com foco nas métricas e informações mais relevantes para suas atividades.

 

Vamos falar um pouco das métricas do APIM

 

As métricas podem oferecer insights valiosos sobre o desempenho, uso e comportamento das suas APIs, permitindo tomar decisões para otimizar a experiência dos usuários e maximizar a eficiência dos serviços oferecidos.

As duas principais métricas são:

  1. Capacidade (_Capacity_): ajuda a tomar decisões relacionadas ao upgrade/downgrade de seus serviços do APIM. A métrica é emitida por minuto e reflete a capacidade do gateway. A métrica varia de 0 a 100 e é calculada com base nos recursos como a utilização da CPU e a memória.
  2. Solicitações (_Requests_): ajuda você a analisar o tráfego de API que passa pelos serviços do Gerenciamento de API. A métrica é emitida por minuto e relata o número de solicitações de gateway com dimensões. Filtre solicitações por códigos de resposta, localização, nome do host e erros.

 

Use a capacidade para tomar decisões

 

A capacidade é a métrica para tomar decisões sobre dimensionar uma instância do APIM para acomodar mais carga. Seguem as considerações gerais:

  • Olhe para uma tendência de longo prazo e média.
  • Ignore picos repentinos (consulte a seção Comportamento da métrica de capacidade para obter explicação).
  • Como regra geral, atualize ou dimensione sua instância quando o valor da capacidade exceder 60% — 70% por um longo período (por exemplo, 30 minutos).
  • Se sua instância estiver configurada com apenas 1 unidade, faça upgrade ou dimensione sua instância quando o valor da capacidade exceder 40% por um longo período.

 

Criando Alertas

 

Podemos criar alertas com base nos indicadores mostrados acima. Para fazer isso, basta acessar o menu Monitoring, Alerts e clicar em ‘Create Alert Rule’. Em seguida, selecione a métrica desejada, por exemplo, ‘requests’, e defina os parâmetros, como dimensões, Lógica e Período de Tempo

métricas disponíveis

Configurar Escala

 

A instância do serviço de Gerenciamento de API do Azure pode ser dimensionada automaticamente com base em um conjunto de regras. Esse comportamento pode ser habilitado e configurado por meio do dimensionamento automático do Azure Monitor e tem suporte apenas nas camadas Standard e Premium do serviço de Gerenciamento de API do Azure.

Saiba mais aqui

Criando consultas usando KQL (Kusto Query Language)

 

Comecei usando as consultas na tabela de logs do APIM através do menu de logs dentro do Application Insights. O KQL (Kusto Query Language) é muito fácil de usar e é semelhante a linguagens SQL comuns.

Além disso, temos a ferramenta Transaction Search que é muito útil tanto para encontrar logs quanto para aprender a construir queries.

Aqui, estou visualizando os dados das requisições feitas ao APIM:

ApiManagementGatewayLogs

Podemos buscar dados da tabela de dependências onde tenhamos o texto “text/plain;charset=UTF-8” em qualquer campo dessa tabela, pegando apenas o campo Request-Content-Type

dependencies  
| where * has “text/plain;charset=UTF-8”  
| project customDimensions[“Request-Content-Type”]

Buscar dados da tabela de requests onde tenhamos o texto “Application/json; charset=utf-8” no campo customDimensions[“Response-Content-Type”] dessa tabela, pegando apenas o campo Request-Content-Type

requests  
| where customDimensions[“Response-Content-Type”] in (“application/json; charset=utf-8”)  
|project customDimensions[“Response-Content-Type”]

Buscar dados da tabela de requests onde tenhamos o texto “text/plain;charset=UTF-8” no campo customDimensions[“Request-Content-Type”] ou o texto “application/json; charset=utf-8” no campo customDimensions[“Response-Content-Type”] dessa tabela, pegando o campo Request-Content-Type, Response-Content-Type e os renomeando para Request e Response respectivamente.

requests  
| where customDimensions[“Request-Content-Type”] in (“text/plain;charset=UTF-8”) or customDimensions[“Response-Content-Type”] in (“application/json; charset=utf-8”)  
|project customDimensions[“Request-Content-Type”], customDimensions[“Response-Content-Type”]  
|project-rename Request = [‘customDimensions_Request-Content-Type’] ,Response = [‘customDimensions_Response-Content-Type’]

 

Olhando os dados todos Juntos para análises

 

Logo percebi que a instância do Application Insights que estava utilizando não continha todos os dados necessários para minha análise. Era como estar em um silo, com muitas informações, mas ainda limitado em sua abrangência. Comecei a compreender quais dados estavam disponíveis em cada tabela e percebi que, além de dominar o KQL, era necessário ter paciência para minerar os dados e fazer as correlações. saiba quais tabelas estão disponíveis em Azure Monitor table reference index by category | Microsoft Learn

//Application gateway  
AzureDiagnostics  
| where ResourceType == "APPLICATIONGATEWAYS" and OperationName == "ApplicationGatewayAccess"  
| where requestUri_s contains "device"  
| project  split(split(requestQuery_s,"&")[2],"=")[1]  
//Application Insights  
AppRequests  
| where ResultCode == 200  
| where Properties["Service Type"] has "API Management"  
| project  Properties["Request Id"]// Juntando as coisas  
union  
AzureDiagnostics,  
AppRequests  
| project   split(split(requestQuery_s,"&")[2],"=")[1], Properties["Request Id"]//APIM  
ApiManagementGatewayLogs

Na sequencia tentei correlacionar mas não encontrei nada que pudesse unir as consultas no nível da requisição

AzureDiagnostics  
| where ResourceType == "APPLICATIONGATEWAYS" and OperationName == "ApplicationGatewayAccess"  
| where requestUri_s contains "device"| where clientIP_s == "186.207.64.242"  
| where TimeGenerated  > now(-15m)AppRequests  
| where ResultCode == 200  
| where Properties["Service Type"] has "API Management"  
| where Name contains "device"  
| where TimeGenerated  > now(-15m)  
| where Properties["Request-X-Forwarded-For"] has "186.207.64.242"

e por fim depois de ver que não existem campos correlacionados fiz uma amarração pelas datas usando ordenação e uma função chamada row_number()

let appgw = AzureDiagnostics  
| where ResourceType == "APPLICATIONGATEWAYS" and OperationName == "ApplicationGatewayAccess"  
| where requestUri_s contains "device"  
| where clientIP_s == "186.207.64.242"  
| where TimeGenerated  > now(-120m)  
| order by TimeGenerated  
|extend  rowAPPGW=row_number()  
| project rowAPPGW,requestUri_s;let apim = AppRequests   
| where ResultCode == 200  
| where Properties["Service Type"] has "API Management"  
| where Name contains "device"  
| where Properties["Request-X-Forwarded-For"] has "186.207.64.242"  
| where TimeGenerated  > now(-120m)  
| order by TimeGenerated  
|extend  rowAPIM=row_number()  
| project rowAPIM,Name;appgw | join apim on $left.rowAPPGW ==  $right.rowAPIM

tela do Log Analytics tela do Log Analytics que mostra a consulta acima, além dos resultados.

 

Para mais detalhes da linguagem KQL clique aqui

OBS: Após realizar todas essas configurações, descobri que o Application Gateway (APPGW) possui um cabeçalho chamado X-ARR-LOG-ID. Com base nisso, procedi com a configuração no Azure API Management (APIM) para capturar esse cabeçalho e enviá-lo para o Application Insights.

tela do apim tela do apim onde podemos configurar a captura de Headers que serão enviados para o applications insights

 

let appgw = AzureDiagnostics  
| where ResourceType == "APPLICATIONGATEWAYS" and OperationName == "ApplicationGatewayAccess"  
| where requestUri_s contains "device"  
| where clientIP_s == "186.207.64.242"  
| where  TimeGenerated  > now(-25m)  
| order by TimeGenerated  
| extend  rowAPPGW = row_number()  
| project rowAPPGW, IdAPPGW = tostring(split(split(requestQuery_s,"&")[2],"=")[1]), requestUri_s, TimeMs = timeTaken_d;let apim = AppRequests  
| where ResultCode == 200  
| where Properties["Service Type"] has "API Management"  
| where Name contains "device"  
| where Properties["Request-X-Forwarded-For"] has "186.207.64.242"  
| where  TimeGenerated  > now(-25m)  
| order by TimeGenerated  
| extend  rowAPIM = row_number()  
| project  rowAPIM,IdAPIM = tostring(Properties["Request-X-ARR-LOG-ID"]),  Name, TimeMs=DurationMs, OperationId;appgw | join apim on $left.IdAPPGW == $right.IdAPIM

 

Trace

 

A política trace adiciona um rastreamento personalizado à saída de rastreamento de solicitação no console de teste, telemetrias do Application Insights e/ou logs de recursos

<set-variable name="response" value="@(((IResponse)context.Response).Body.As<JObject>())" />  
<trace source="gatilho_atualizacao" severity="verbose">  
    <message>@(JsonConvert.SerializeObject(context.Variables["response"]))</message>  
    <metadata name="Operation Name" value="gatilho" />  
</trace>

Precisamos habilitar o nível de severidade de coleta para verbose

tela do apim severidade dos logs

No application insights

 

Podemos usar a ferramenta de Transaction Search para localizar o Gatilho do Trace

Transaction Search Ferramenta de Transaction Search do Application Insights

 

Na workspace do Analytics

 

E no log Analytics temos essas informações na tabela de AppTrace

tabela de AppTrace Log Analytics tabela de AppTrace

 

Visualizações

 

AS ferramentas de visualização de dados da plataforma de monitoramento são bem poderosas, comecei usando os dashboards e workbooks mas logo percebi que podia integrar com Grafa e até o Power BI.

Um dos recursos que mais gosto ó de “pinar” uma consulta, um Gráfico ou uma métrica, seja customizado no KQL ou mesmo os insights built in existentes em um dashboard, workbook ou mesmo direto no Grafana caso você tenha uma workspace gerenciada.

 

menu de pinagem

Vou usar essa consulta para comparar as visualizações do workbook, Dashboard e Grafana

AppRequests  
| summarize total = count() by ResultCode,   
| render piechart

 

Vou pinar esse gráfico em um workbook

 

Os workbooks são uma poderosa ferramenta para a criação de relatórios visuais avançados. Sua interface interativa permite compartilhá-los facilmente entre equipes, com dados sempre atualizados em tempo real. Você pode aproveitar os workbooks fornecidos com os Insights, explorar a biblioteca de modelos ou criar suas próprias análises personalizadas.

ela do Log Analytics com um gráfico específico em exibição

Nesta configuração, temos a tela do Log Analytics com um gráfico específico em exibição. Ao mesmo tempo, uma aba de pinagem em um workbook está aberta, possibilitando a ação de fixar o gráfico. Essa integração entre o Log Analytics e os workbooks oferece uma forma mais eficiente de visualizar e compartilhar dados, além de permitir análises detalhadas das informações em diferentes contextos

A escolha que você fizer aqui determinará a localização do seu workbook posteriormente. Se optar pelo Azure Monitor, o workbook será salvo em ‘Azure Monitor > workbooks’. Caso escolha um Recurso Azure específico, encontrará o workbook no item de menu ‘workbook’ associado a esse recurso. Se esse tipo de recurso ainda não estiver integrado aos workbooks, você poderá encontrá-lo apenas na seção ‘Procurar Todos’ dos workbooks do Azure no Portal Azure.

 

o gráfico resultante apresentou uma aparência mais simples e diferente

Após a pinagem no workbook, o gráfico resultante apresentou uma aparência mais simples e diferente. Essa modificação pode ser resultado da adaptação do gráfico para a visualização dentro do workbook ou pode estar relacionada a alguma limitação específica na plataforma. Apesar das mudanças visuais, o gráfico fixado ainda oferece insights valiosos e é uma maneira eficaz de compartilhar e analisar os dados dentro do contexto do workbook

 

Depois em um Dashboard

 

Os Dashboards permitem combinar diferentes tipos de dados em um painel no portal do Azure. Você pode compartilhar o Dashboards com outros usuários do Azure. Você pode adicionar a saída de qualquer consulta de log ou gráfico de métricas a um painel do Azure. Por exemplo, é possível criar um painel que combine blocos que mostrem um gráfico de métricas, uma tabela de logs de atividades, um gráfico de uso do Application Insights e a saída de uma consulta de log.

aba de pinagem em um dashboard está aberta

Nesta configuração, temos a tela do Log Analytics com um gráfico específico em exibição. Além disso, uma aba de pinagem em um dashboard está aberta. Isso permite fixar o gráfico para visualização e análise posterior no dashboard. Essa integração entre o Log Analytics e o dashboard oferece uma forma mais eficiente de compartilhar insights e ter uma visão mais ampla dos dados em um único painel.

o gráfico mantém as mesmas características da renderização na tela do Log Analytics

Após a pinagem no dashboard, o gráfico mantém as mesmas características da renderização na tela do Log Analytics. Essa consistência na apresentação do gráfico permite uma transição suave entre as duas visualizações, garantindo que os insights e informações essenciais sejam preservados. A pinagem do gráfico no dashboard oferece uma forma organizada de compartilhar e monitorar dados importantes em um único local, mantendo a fidelidade da análise original realizada no Log Analytics

 

No Grafana

 

A conversão entre os gráficos do Portal Azure e os painéis do Grafana é realizada com o melhor esforço. No entanto, devido às diferenças nas capacidades das plataformas, algumas visualizações ou opções podem não ser mapeadas diretamente entre elas.

Início Rápido: criar uma instância da versão prévia do Espaço Gerenciado do Azure para Grafana usando o portal do Azure | Microsoft Learn

temos a tela do Log Analytics com um gráfico específico sendo exibido. Ao mesmo tempo, uma aba do Grafana está aberta

Nesta configuração, temos a tela do Log Analytics com um gráfico específico sendo exibido. Ao mesmo tempo, uma aba do Grafana está aberta para possibilitar a pinagem desse gráfico. Essa integração entre as duas plataformas permite visualizar e compartilhar os dados de forma mais eficiente e analisar as informações em diferentes contextos.

O Grafana é famoso pelos seus painéis ricos e detalhados, mas nesse a visualização ficou bem estranha, devido a simplicidade da query.

A tela do Grafana exibe um gráfico com características bastante distintas em relação ao gráfico presente no Analytics A tela do Grafana exibe um gráfico com características bastante distintas em relação ao gráfico presente no Analytics. Essas diferenças podem estar relacionadas à forma como os dados são processados, interpretados ou apresentados nas duas plataformas. Apesar das disparidades, ambas as visualizações podem oferecer insights úteis e complementares para análises específicas e diferentes contextos de uso

usei outra consulta

AzureMetrics  
| where Average  > 0  
| summarize   
    total=count(),  
    Minimum = min(Minimum),  
    Maximum = max(Maximum),  
    Average = avg(Average)  
    by MetricName,Resource  
| render piechart

Com essa consulta mais detalhada, o gráfico do Grafana apresentou melhorias significativas Com essa consulta mais detalhada, o gráfico do Grafana apresentou melhorias significativas, no entanto, ainda é evidente que existe uma simplificação acentuada em comparação com o Analytics. Essa discrepância pode ser devido a diferenças nas capacidades de visualização e processamento de dados entre as duas plataformas. Apesar disso, as informações obtidas do gráfico aprimorado no Grafana continuam sendo valiosas e fornecem insights relevantes para análises específicas.

O Analytics infere algumas informações que não estão presentes na consulta original, resultando em uma visualização mais detalhada e rica em dados. Isso pode ser atribuído à capacidade do Analytics de realizar análises avançadas e aplicar algoritmos para preencher lacunas nos dados, proporcionando uma visão mais abrangente das informações. Essa abordagem enriquece o resultado final, tornando-o mais informativo e útil para análises detalhadas.

O Analytics infere algumas informações que não estão presentes na consulta original, resultando em uma visualização mais detalhada e rica em dados

Gráfico original do Analytics usado para a pinagem no Grafana.

 

Conclusão

 

As ferramentas de monitoramento do Azure são fundamentais para obter insights valiosos sobre o desempenho e a saúde de suas aplicações e serviços na nuvem. A combinação de recursos do Azure API Management (APIM), Application Insights e Log Analytics pode fornecer uma visão holística e abrangente do ambiente, permitindo uma análise mais detalhada e complexa para otimizar e solucionar problemas de forma eficaz.

 

Referências

  1. Integrate Azure API Management with Azure Application Insights — Azure API Management | Microsoft Docs
  2. https://learn.microsoft.com/en-us/azure/api-management/observability
  3. Azure API Management policy reference — trace | Microsoft Learn
  4. Diagnostic logs settings reference | Microsoft Learn
  5. Capacity of an Azure API Management instance | Microsoft Docs
  6. Tutorial — Monitor published APIs in Azure API Management | Microsoft Docs
  7. Observability in Azure API Management | Microsoft Docs
  8. Tutorial — Debug APIs in Azure API Management using request tracing | Microsoft Docs
  9. Let statement — Azure Data Explorer | Microsoft Docs
  10. Azure API Management advanced policies | Microsoft Docs
  11. Configure autoscale of an Azure API Management instance | Microsoft Docs

KQL References

  1. Azure Monitor overview — Azure Monitor | Microsoft Learn
  2. Tutorial: Kusto queries | Microsoft Docs
  3. operador project-rename — Azure Data Explorer | Microsoft Docs
  4. join operator — Azure Data Explorer | Microsoft Docs
  5. Scalar Functions — Azure Data Explorer | Microsoft Docs
  6. Azure Monitor table reference index by category | Microsoft Learn
  7. Reference — Azure API Management resource log | Microsoft Learn

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.