Como configurar o monitoramento do Azure Functions

O Azure Functions integra-se ao Application Insights para permitir que você monitore melhor os seus aplicativos de funções. O Application Insights, um recurso do Azure Monitor, é um serviço de APM (Gerenciamento de Desempenho de Aplicativos) extensível que coleta dados gerados pelo seu aplicativo de funções, incluindo informações que o seu aplicativo grava nos logs. A integração do Application Insights é normalmente habilitada quando o seu aplicativo de funções é criado. Se o seu aplicativo não tiver o conjunto de chaves de instrumentação, você precisará primeiro habilitar a integração do Application Insights.

Você pode usar Application Insights sem nenhuma configuração personalizada. No entanto, a configuração padrão pode resultar em grandes volumes de dados. Se você estiver usando uma assinatura do Azure do Visual Studio, poderá ter atingido o limite de dados para o Application Insights. Para obter informações sobre os custos do Application Insights, consulte Cobrança do Application Insights. Para saber mais, confira Soluções com alto volume de telemetria.

Neste artigo, você aprende como configurar e personalizar os dados que suas funções enviam ao Application Insights. Você pode definir configurações comuns de log no arquivo host.json. Por padrão, essas configurações também regem os logs personalizados emitidos pelo código. No entanto, em alguns casos, esse comportamento pode ser desabilitado em favor de opções que oferecem mais controle sobre o registro em log. Para obter mais informações, consulte Logs de aplicativos personalizados.

Logs do aplicativo personalizados

Por padrão, os logs personalizados que você grava são enviados para o host do Functions, que os envia para o Application Insights na categoria Trabalho. Algumas pilhas de linguagem de programação permitem, em vez disso, enviar os logs diretamente para o Application Insights, o que dá a você controle total sobre como os logs gravados são emitidos. Nesse caso, o pipeline de registro em log muda de worker -> Functions host -> Application Insights para worker -> Application Insights.

A seguinte tabela resume as opções de configuração disponíveis para cada pilha:

Quando você configura os logs personalizados para serem enviados diretamente, o host não os emite mais e host.json não controla mais o comportamento deles. Da mesma forma, as opções expostas por cada pilha se aplicam apenas a logs personalizados e não alteram o comportamento dos outros logs de runtime descritos neste artigo. Nesse caso, para controlar o comportamento de todos os logs, talvez seja necessário fazer alterações em ambas as configurações.

Configurar categorias

O agente do Azure Functions inclui uma categoria para cada log. A categoria indica qual parte do código de runtime ou do seu código de função gravou o log. As categorias diferenciam a versão 1.x das versões posteriores.

Os nomes de categoria são atribuídos de forma diferente no Functions em comparação com outras estruturas do .NET. Por exemplo, ao usar ILogger<T> no ASP.NET, a categoria é o nome do tipo genérico. As funções C# também usam ILogger<T>, mas em vez de definir o nome de tipo genérico como uma categoria, o runtime atribui categorias com base na origem. Por exemplo:

• As entradas relacionadas à execução de uma função são atribuídas a uma categoria de Function.<FUNCTION_NAME>.
• As entradas criadas pelo código do usuário dentro da função, como ao chamar logger.LogInformation(), recebem uma categoria de Function.<FUNCTION_NAME>.User.

A seguinte tabela descreve as principais categorias de logs que o runtime cria:

A coluna Tabela indica em qual tabela no Application Insights o log é gravado.

Configurar os níveis de log

Um nível de log é atribuído a cada log. O valor é um inteiro que indica a importância relativa:

A configuração doarquivohost.jsondetermina quanto registro em log um aplicativo de funções envia ao Application Insights.

Para cada categoria, você deve indicar o nível de log mínimo para enviar. As configurações de host.json variam dependendo da versão do runtime do Functions.

Os seguintes exemplos definem o registro em log com base nas seguintes regras:

• O nível de registros em log padrão é definido como Warning para evitar o registro em log excessivo para categorias inesperadas.
• Host.Aggregator e Host.Results são definidos como níveis mais baixos. Definir níveis de log com um valor muito alto (especialmente maior que Information) pode resultar em perda de métricas e dados de desempenho.
• O registro em log para execuções de função é definido como Information. Se necessário, você pode substituir essa configuração no desenvolvimento local para Debug ou Trace.

{
  "logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "default": "Warning",
      "Host.Aggregator": "Trace",
      "Host.Results": "Information",
      "Function": "Information"
    }
  }
}

{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "Warning",
      "categoryLevels": {
        "Host.Results": "Information",
        "Host.Aggregator": "Trace",
        "Function": "Information"
      }
    }
  }
}

Se o host.json incluir vários logs que começam com a mesma cadeia de caracteres, será feito primeiro a correspondência com os mais definidos. Considere o seguinte exemplo que registra tudo no runtime, exceto o Host.Aggregator no nível Error:

{
  "logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "default": "Information",
      "Host": "Error",
      "Function": "Error",
      "Host.Aggregator": "Information"
    }
  }
}

{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "Information",
      "categoryLevels": {
        "Host": "Error",
        "Function": "Error",
        "Host.Aggregator": "Information"
      }
    }
  }
}

Você pode usar uma configuração de nível de log de None para impedir que os logs sejam gravados em uma categoria.

Configurar o agregador

Conforme observado na seção anterior, o runtime agrega dados sobre as execuções de função em um período. O período padrão é de 30 segundos ou 1.000 execuções, o que ocorrer primeiro. Você pode definir essa configuração no arquivo host.json. Por exemplo:

{
    "aggregator": {
      "batchSize": 1000,
      "flushTimeout": "00:00:30"
    }
}

Configurar a amostragem

O Application Insights tem um recurso de amostragem que pode protegê-lo contra a produção de excesso de dados de telemetria em execuções concluídas em horários de pico de carregamento. Quando a taxa de execuções de entrada excede um limite especificado, o Application Insights começa a ignorar aleatoriamente algumas das execuções de entrada. A configuração padrão para o número máximo de execuções por segundo é 20 (cinco na versão 1.x). Você pode configurar a amostragem em host.json. Aqui está um exemplo:

{
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond" : 20,
        "excludedTypes": "Request;Exception"
      }
    }
  }
}

{
  "applicationInsights": {
    "sampling": {
      "isEnabled": true,
      "maxTelemetryItemsPerSecond" : 5
    }
  }
}

Se o projeto usar uma dependência do SDK do Application Insights para fazer o acompanhamento de telemetria manual, você poderá se deparar com um comportamento estranho se a configuração de amostragem for diferente da configuração de amostragem do aplicativo de funções. Nesses casos, use a mesma configuração de amostragem que o aplicativo de funções. Para obter mais informações, consulte Amostragem no Application Insights.

Habilitar a coleta de consulta SQL

O Application Insights coleta automaticamente dados sobre dependências para solicitações HTTP, chamadas de banco de dados e para várias associações. Para saber mais, confira Dependências. Para chamadas SQL, o nome do servidor e do banco de dados é sempre coletado e armazenado, mas o texto da consulta SQL não é coletado por padrão. Você pode usar dependencyTrackingOptions.enableSqlCommandTextInstrumentation para habilitar o log de texto da consulta SQL usando (no mínimo) as seguintes configurações no arquivo host.json:

"logging": {
    "applicationInsights": {
        "enableDependencyTracking": true,    
        "dependencyTrackingOptions": {
            "enableSqlCommandTextInstrumentation": true
        }
    }
}

Para obter mais informações, confira Acompanhamento avançado de SQL para obter uma consulta SQL completa.

Configurar logs do controlador de escala

Este recurso está em versão prévia.

Você pode fazer com que o controlador de escala do Azure Functions emita logs para o Application Insights ou para o Armazenamento de blobs a fim de entender melhor as decisões que o controlador de escala está tomando para o seu aplicativo de funções.

Para habilitar esse recurso, adicione uma configuração de aplicativo chamada SCALE_CONTROLLER_LOGGING_ENABLED às suas configurações do aplicativo de funções. O valor da configuração a seguir precisa estar no formato <DESTINATION>:<VERBOSITY>. Para obter mais informações, confira a tabela a seguir:

Por exemplo, o seguinte comando da CLI do Azure ativa o registro em log detalhado do controlador de escala para o Application Insights:

az functionapp config appsettings set --name <FUNCTION_APP_NAME> \
--resource-group <RESOURCE_GROUP_NAME> \
--settings SCALE_CONTROLLER_LOGGING_ENABLED=AppInsights:Verbose

Neste exemplo, substitua <FUNCTION_APP_NAME> e <RESOURCE_GROUP_NAME> pelo nome do seu aplicativo de funções e pelo nome do grupo de recursos, respectivamente.

O seguinte comando da CLI do Azure desabilita o registro em log configurando o detalhamento como None:

az functionapp config appsettings set --name <FUNCTION_APP_NAME> \
--resource-group <RESOURCE_GROUP_NAME> \
--settings SCALE_CONTROLLER_LOGGING_ENABLED=AppInsights:None

Você também pode desabilitar o registro em log removendo a configuração SCALE_CONTROLLER_LOGGING_ENABLED com o seguinte comando da CLI do Azure:

az functionapp config appsettings delete --name <FUNCTION_APP_NAME> \
--resource-group <RESOURCE_GROUP_NAME> \
--setting-names SCALE_CONTROLLER_LOGGING_ENABLED

Com o registro em log do controlador de escala habilitado, agora você pode consultar os logs do controlador de escala.

Habilitar a integração do Application Insights

Para que um aplicativo de funções envie dados para o Application Insights, ele precisa se conectar ao recurso do Application Insights usando apenas uma destas configurações de aplicativo:

Ao criar seu aplicativo de funções no portal do Azure, com a linha de comando usando o Azure Functions Core Tools ou o Visual Studio Code, a integração do Application Insights é habilitada por padrão. O recurso do Application Insights tem o mesmo nome do seu aplicativo de funções e é criado na mesma região ou na região mais próxima.

Exigir autenticação do Microsoft Entra

Você pode usar a configuração APPLICATIONINSIGHTS_AUTHENTICATION_STRING para habilitar conexões com o Application Insights usando a autenticação do Microsoft Entra. Isso cria uma experiência de autenticação consistente em todos os pipelines do Application Insights, incluindo o Criador de Perfil e o Depurador de Instantâneos, bem como no host do Functions e em agentes específicos a um idioma.

O valor contém Authorization=AAD para uma identidade gerenciada atribuída pelo sistema ou ClientId=<YOUR_CLIENT_ID>;Authorization=AAD para uma identidade gerenciada atribuída pelo usuário. A identidade gerenciada já deve estar disponível para o aplicativo de funções com uma função atribuída equivalente ao Editor de Métricas de Monitoramento. Para obter mais informações, consulte Autenticação do Microsoft Entra para Application Insights.

A configuração APPLICATIONINSIGHTS_CONNECTION_STRING ainda é necessária.

Novo aplicativo de funções no portal

Para examinar o recurso do Application Insights que está sendo criado, selecione-o para expandir a janela do Application Insights. Você pode alterar o Novo nome do recurso ou selecionar um Local diferente em uma geografia do Azure onde deseja armazenar seus dados.

Quando você seleciona Criar, um recurso de Application Insights é criado com seu aplicativo de funções, que tem APPLICATIONINSIGHTS_CONNECTION_STRING definido nas configurações do aplicativo. Tudo está pronto para começar.

Adicionar a um aplicativo de funções existente

Se um recurso do Application Insights não foi criado com o seu aplicativo de funções, use as etapas a seguir para criar o recurso. Em seguida, você pode adicionar a cadeia de conexão desse recurso como uma configuração de aplicativo em seu aplicativo de funções.

1. No portal do Azure, pesquise aplicativo de funções e selecione-o. Depois selecione o seu aplicativo de funções.

2. Selecione a faixa O Application Insights não está configurado na parte superior da janela. Caso não veja essa faixa, pode ser que o Application Insights já esteja habilitado no aplicativo.

   

3. Expanda a opção Alterar seu recurso e crie um recurso do Application Insights usando as configurações especificadas na tabela a seguir:

   Configuração	Valor sugerido	Descrição
   Nome de recurso novo	Nome de aplicativo exclusivo	É mais fácil usar o mesmo nome que seu aplicativo de funções, que deve ser exclusivo em sua assinatura.
   Localidade	Europa Ocidental	Se possível, use a mesma região que seu aplicativo de funções ou uma região próxima dela.

   

4. Escolha Aplicar.

   O recurso do Application Insights é criado no mesmo grupo de recursos e assinatura que seu aplicativo de funções. Depois que o recurso for criado, feche a janela do Application Insights.

5. Em seu aplicativo de funções, expanda Configurações e selecione Variáveis de ambiente. Na guia Configurações de aplicativo, se você vir uma configuração chamada APPLICATIONINSIGHTS_CONNECTION_STRING, isso significa que a integração do Application Insights está habilitada para seu aplicativo de funções em execução no Azure. Se essa configuração não existir, adicione-a usando sua cadeia de conexão do Application Insights como o valor.

Desabilitar o registro em log interno

As primeiras versões de Functions usavam o monitoramento interno, o que não é mais recomendado. Ao ativar o Application Insights, desative o registro interno que usa o Armazenamento do Microsoft Azure. O registro em log interno é útil para testes com cargas de trabalho leves, mas não se destina ao uso em produção com carga alta. Para monitoramento de produção, o Application Insights é recomendado. Se você usar o registro em log interno na produção, o registro de logs poderá estar incompleto devido à limitação da largura de banda de rede no Armazenamento do Microsoft Azure.

Para desabilitar o registro em log interno, exclua a configuração de aplicativo AzureWebJobsDashboard. Para obter mais informações sobre como excluir configurações do aplicativo no portal do Azure, consulte a seção Configurações do aplicativo em Como gerenciar um aplicativo de funções. Antes de excluir a configuração do aplicativo, verifique se não existe nenhuma função no mesmo aplicativo de funções que use essa configuração para associações ou gatilhos do Armazenamento do Microsoft Azure.

Soluções com alto volume de telemetria

Os aplicativos de funções são uma parte essencial das soluções que podem causar grandes volumes de telemetria, como soluções de IoT, soluções rápidas orientadas a eventos, sistemas financeiros de alta carga e sistemas de integração. Nesse caso, você deve considerar a configuração extra para reduzir os custos, mantendo a observabilidade.

A telemetria gerada pode ser consumida dos painéis em tempo real, dos alertas, do diagnóstico detalhado e assim por diante. Dependendo de como a telemetria gerada será consumida, será necessário definir uma estratégia para reduzir o volume de dados gerados. Essa estratégia permite que você monitore, opere e diagnostique corretamente seus aplicativos de funções na produção. Considere as seguintes opções:

• Usar amostragem: conforme mencionado anteriormente, a amostragem ajudará a reduzir drasticamente o volume de eventos de telemetria ingeridos enquanto mantém uma análise estatisticamente correta. Pode acontecer que até mesmo com o uso da amostragem você obtenha um alto volume de telemetria. Inspecione as opções que a amostragem adaptável fornece a você. Por exemplo, defina maxTelemetryItemsPerSecond como um valor que equilibre o volume gerado com suas necessidades de monitoramento. Tenha em mente que a amostragem de telemetria é aplicada a cada host que executa seu aplicativo de funções.

• Nível de log padrão: use Warning ou Error como o valor padrão em todas as categorias de telemetria. Depois, você pode decidir quais categorias deseja definir no nível Information para poder monitorar e diagnosticar suas funções corretamente.

• Ajustar a telemetria de funções: com o nível de log padrão definido como Error ou Warning, nenhuma informação detalhada de cada função é coletada (dependências, métricas personalizadas, eventos personalizados e rastreamentos). No caso de funções que sejam fundamentais para o monitoramento da produção, defina uma entrada explícita para a categoria Function.<YOUR_FUNCTION_NAME> e defina-a como Information para poder coletar informações detalhadas. Para evitar a coleta de logs gerados pelo usuário no nível Information, defina a categoria Function.<YOUR_FUNCTION_NAME>.User como Error ou com nível de log Warning.

• Categoria Host.Aggregator: conforme descrito em configurar categorias, é uma categoria que fornece informações agregadas de invocações de função. As informações dessa categoria são coletadas na tabela customMetrics do Application Insights e mostradas na guia de Visão geral da função na portal do Azure. Dependendo de como você configura o agregador, considere que poderá haver um atraso, determinado pela configuração flushTimeout, na telemetria coletada. Se você definir essa categoria com um valor diferente de Information, deixará de coletar os dados na tabela customMetrics e não exibirá as métricas na guia Visão geral da função.

  A captura de tela a seguir mostra os dados de telemetria Host.Aggregator exibidos na guia Visão geral da função:

  

  A captura de tela a seguir mostra os dados de telemetria de Host.Aggregator na tabela customMetrics do Application Insights:

  

• Categoria Host.Results: conforme descrito em configurar categorias, é a categoria que fornece os logs gerados pelo tempo de execução para indicar o êxito ou a falha de uma invocação de função. As informações dessa categoria são coletadas na tabela requests do Application Insights e mostradas na guia Monitor da função e em diferentes painéis do Application Insights (Desempenho, Falhas, entre outros). Se você definir essa categoria com um valor diferente de Information, coletará apenas a telemetria gerada no nível de log definido (ou superior). Por exemplo, a definição como error resulta no rastreamento de dados de solicitações somente de execuções com falha.

  A captura de tela a seguir mostra os dados de telemetria Host.Results exibidos na guia Monitor da função:

  

  A captura de tela a seguir mostra os dados de telemetria de Host.Results exibidos no painel Desempenho do Application Insights:

  

• Host.Aggregator vs. Host.Results: ambas as categorias fornecem bons insights sobre execuções de função. Se necessário,é possível remover as informações detalhadas de uma dessas categorias e usar a outra para monitoramento e alertas. Veja um exemplo:

{
  "version": "2.0",  
  "logging": {
    "logLevel": {
      "default": "Warning",
      "Function": "Error",
      "Host.Aggregator": "Error",
      "Host.Results": "Information", 
      "Function.Function1": "Information",
      "Function.Function1.User": "Error"
    },
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond": 1,
        "excludedTypes": "Exception"
      }
    }
  }
} 

{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "Warning",
      "categoryLevels": {
        "Function": "Error",
        "Host.Aggregator": "Error",
        "Host.Results": "Information",
        "Host.Executor": "Warning"
      }
    }
  },
  "applicationInsights": {
    "sampling": {
      "isEnabled": true,
      "maxTelemetryItemsPerSecond" : 5
    }
  }
}

Com esta configuração:

• O valor padrão de todas as categorias de funções e telemetria é definido como Warning (incluindo as categorias Microsoft e Trabalho). Ou seja, por padrão, todos os erros e avisos gerados pelo runtime e o registro em log personalizado são coletados.

• O nível de log de categoria Function é definido como Error, portanto, para todas as funções, por padrão, somente exceções e logs de erro são coletados. Dependências, métricas geradas pelo usuário e eventos gerados pelo usuário são ignorados.

• Para a categoria Host.Aggregator, como ela está definida com o nível de log Error, as informações agregadas das invocações de função não são coletadas na tabela customMetrics do Application Insights, e as informações sobre as contagens de execuções (total, êxitos e falhas) não são mostradas no painel de visão geral da função.

• Para a categoria Host.Results, todas as informações de execução do host são coletadas na tabela requests do Application Insights. Todos os resultados de invocações são mostrados no painel Monitor da função e nos painéis do Application Insights.

• Para a função chamada Function1, definimos o nível de log como Information. Ou seja, essa função concreta, toda a telemetria é coletada (dependência, métricas personalizadas e eventos personalizados). Para a mesma função, definimos a categoria Function1.User (rastreamentos gerados pelo usuário) é definida como Error e, portanto, somente o log de erros personalizado é coletado.

  Observação

  Não há suporte para a configuração por função na v1.x do runtime do Functions.

• A amostragem é configurada para enviar um item de telemetria por segundo por tipo, excluídas as exceções. Essa amostragem ocorre para cada host do servidor que executa nosso aplicativo de funções. Ou seja, se houver quatro instâncias, essa configuração emitirá quatro itens de telemetria por segundo por tipo e todas as exceções que possam ocorrer.

  Observação

  As contagens de métrica, como a taxa de solicitações e a taxa de exceções são ajustadas para compensar a taxa de amostragem, para que mostrem valores aproximadamente corretos no Gerenciador de Métricas.

Substituindo a configuração de monitoramento no tempo de execução

Por fim, pode haver situações em que você precise alterar rapidamente o comportamento de log de determinada categoria na produção e não queira fazer uma implantação inteira apenas para uma alteração no arquivo host.json. Em tais casos, você pode substituir os valores host.json.

Para configurar esses valores no nível das configurações do aplicativo (e evitar a reimplantação apenas em alterações de host.json), você deve substituir os valores host.json específicos pela criação de um valor equivalente como configuração de aplicativo. Quando o runtime encontra uma configuração de aplicativo no formato AzureFunctionsJobHost__path__to__setting, ele substitui a configuração host.json equivalente na configuração localizada em path.to.setting no JSON. Quando expressa como uma configuração de aplicativo, o ponto (.) usado para indicar a hierarquia JSON é substituído por um sublinhado duplo (__). Por exemplo, você pode usar as configurações de aplicativo a seguir para configurar níveis de log de funções individuais em host.json.

Você pode substituir as configurações diretamente no painel Configuração do Aplicativo de Funções do portal do Azure ou por meio de um script da CLI do Azure ou do PowerShell.

az functionapp config appsettings set --name MyFunctionApp --resource-group MyResourceGroup --settings "AzureFunctionsJobHost__logging__logLevel__Host__Aggregator=Information"

Update-AzFunctionAppSetting -Name MyAppName -ResourceGroupName MyResourceGroupName -AppSetting @{"AzureFunctionsJobHost__logging__logLevel__Host__Aggregator" = "Information"}

Monitorar aplicativos de funções usando a Verificação de Integridade

Você pode usar o recurso Verificação de Integridade para monitorar aplicativos de funções nos planos Premium (Elástico Premium) e Dedicado (Serviço de Aplicativo). A Verificação de Integridade não é uma opção para o plano de Consumo. Para saber como configurá-la, confira Monitorar instâncias do Serviço de Aplicativo usando a Verificação de Integridade. O aplicativo de funções deve ter uma função de gatilho HTTP que responda com um código de status HTTP 200 no mesmo ponto de extremidade configurado no parâmetro Path da Verificação de Integridade. Você também pode fazer com que essa função execute verificações extras para garantir que os serviços dependentes estejam acessíveis e funcionando.

Conteúdo relacionado

Para obter mais informações sobre monitoramento, consulte:

• Monitorar Azure Functions
• Analisar os dados de telemetria do Azure Functions no Application Insights
• Visão geral do Application Insights