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. 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 saber mais sobre os custos do Application Insights, confira Gerenciar o uso e os custos do Application Insights. Para saber mais, confira Soluções com alto volume de telemetria.

Este artigo mostra como configurar e personalizar os dados que suas funções enviam ao Application Insights. Para um aplicativo de funções, o registro em log é configurado no arquivo host. JSON.

Observação

Você pode usar as configurações de aplicativo especialmente configuradas para representar as configurações específicas em um arquivo host.json para um ambiente específico. Isso permite que você altere efetivamente as configurações do host.json sem precisar publicar novamente o arquivo host.json no seu projeto. Para saber mais, confira Substituir os valores do host.json.

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. O gráfico a seguir descreve as principais categorias de logs que o runtime cria.

Categoria Tabela Descrição
Function.<YOUR_FUNCTION_NAME> dependencies Os dados de dependência são coletados automaticamente em alguns serviços. Em execuções bem-sucedidas, esses logs estão no nível Information. Para saber mais, confira Dependências. As exceções são registradas no nível Error. O runtime também cria os logs de nível Warning, por exemplo, quando mensagens de fila são enviadas para a fila de mensagens suspeitas.
Function.<YOUR_FUNCTION_NAME> customMetrics
customEvents
Os SDKs do C# e do JavaScript permitem que você colete métricas personalizadas e registre eventos personalizados. Para saber mais, confira Dados de telemetria personalizados.
Function.<YOUR_FUNCTION_NAME> traces Inclui logs de função iniciada e concluída para execuções de função específicas. Em execuções bem-sucedidas, esses logs estão no nível Information. As exceções são registradas no nível Error. O runtime também cria os logs de nível Warning, por exemplo, quando mensagens de fila são enviadas para a fila de mensagens suspeitas.
Function.<YOUR_FUNCTION_NAME>.User traces Logs gerados pelo usuário, que podem ser de qualquer nível de log. Para saber mais sobre como gravar em logs nas suas funções, confira Como gravar em logs.
Host.Aggregator customMetrics Esses logs gerados por runtime fornecem contagens e médias de invocações de função referentes a um período configurável. O período padrão é de 30 segundos ou 1.000 resultados, o que ocorrer primeiro. Exemplos são número de execuções, taxa de sucesso e duração. Todos esses logs são gravados no nível de Information. Se você filtrar Warning ou acima, não verá nenhum desses dados.
Host.Results requests Esses logs gerados por runtime indicam êxito ou falha de uma função. Todos esses logs são gravados no nível de Information. Se você filtrar Warning ou acima, não verá nenhum desses dados.
Microsoft traces Categoria de log totalmente qualificada que reflete um componente de runtime .NET invocado pelo host.
Worker traces Logs gerados pelo processo de trabalho de linguagem para linguagens não .NET. Os logs de trabalho de linguagem também podem ser registrados em uma categoria da Microsoft.*, como Microsoft.Azure.WebJobs.Script.Workers.Rpc.RpcFunctionInvocationDispatcher. Esses logs são gravados no nível Information.

Observação

Para funções de biblioteca de classes do .NET, essas categorias pressupõem que você esteja usando o ILogger e não o ILogger<T>. Para saber mais, confira a Documentação do ILogger do Functions.

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:

LogLevel Código Descrição
Trace 0 Logs que contêm as mensagens mais detalhadas. Essas mensagens podem conter dados confidenciais do aplicativo. Essas mensagens são desabilitadas por padrão e nunca devem ser habilitadas em um ambiente de produção.
Depurar 1 Logs que são usados para investigação interativa durante o desenvolvimento. Esses logs devem conter principalmente informações úteis para depuração e não têm valor de longo prazo.
Informações 2 Logs que rastreiam o fluxo geral do aplicativo. Esses logs devem ter valor de longo prazo.
Aviso 3 Logs que realçam um evento anormal ou inesperado no fluxo do aplicativo, mas não fazem com que a execução do aplicativo pare.
Erro 4 Logs que realçam quando o fluxo de execução atual é interrompido por causa de a uma falha. Eles erros devem indicar uma falha na atividade atual, não uma falha em todo o aplicativo.
Crítico 5 Logs que descrevem uma falha irrecuperável do aplicativo ou do sistema ou uma falha catastrófica que exige atenção imediata.
Nenhum 6 Desabilita o registro em log para a categoria especificada.

A configuração do arquivo host.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.

O seguinte exemplo define o registro em log com base nas seguintes regras:

  • Para logs do Host.Results ou do Function, somente eventos de log no nível Error ou superior.
  • Para logs do Host.Aggregator, registre todas as métricas geradas (Trace).
  • Para todos os outros logs, incluindo logs de usuário, registre apenas eventos com o nível Information ou superior.
{
  "logging": {
    "fileLoggingMode": "always",
    "logLevel": {
      "default": "Information",
      "Host.Results": "Error",
      "Function": "Error",
      "Host.Aggregator": "Trace"
    }
  }
}

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": "always",
    "logLevel": {
      "default": "Information",
      "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.

Cuidado

O Azure Functions integra-se ao Application Insights com o armazenamento de eventos de telemetria em tabelas do Application Insights. A definição de um nível de log de categoria como um valor diferente de Information fará com que a telemetria flua para essas tabelas e, como resultado, você não poderá ver os dados relacionados na guia Application Insights ou Monitor da função.

Dos exemplos acima:

  • Se a categoria Host.Results estiver definida com o nível de log Error, ela só coletará eventos de telemetria de execução de host na tabela requests para execuções de função com falha, o que impedirá a exibição de detalhes de execução de host das execuções com êxito nas guias Application Insights e Monitor da função.
  • Se a categoria Function estiver definida com o nível de log Error, ela interromperá a coleta de dados de telemetria de função relacionados a dependencies, customMetrics e customEvents para todas as funções, o que impedirá que esses dados sejam exibidos no Application Insights. Ele só coletará traces registrados em log com o nível Error.

Em ambos os casos, você continuará a coletar dados de erros e exceções no Application Insights e na guia Monitor da função. Para saber mais, confira Soluções com alto volume de telemetria.

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. Aqui está um 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"
      }
    }
  }
}

Você pode excluir determinados tipos de telemetria da amostragem. Neste exemplo, os dados do tipo Request e Exception são excluídos da amostragem. Isso garante que todas as execuções de função (solicitações) e exceções sejam registradas enquanto outros tipos de telemetria permanecem sujeitos à amostragem.

Para saber mais, confira Amostragem no Application Insights.

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 configurações do aplicativo de funções. O valor dessa configuração precisa estar no formato <DESTINATION>:<VERBOSITY>, com base no seguinte:

Propriedade Descrição
<DESTINATION> O destino para o qual os logs são enviados. Os valores válidos são AppInsights e Blob.
Ao usar o AppInsights, verifique se Application Insights está habilitado no aplicativo de funções.
Quando você define o destino como Blob, os logs são criados em um contêiner de blob nomeado azure-functions-scale-controller na conta de armazenamento padrão definida na configuração do aplicativo AzureWebJobsStorage.
<VERBOSITY> Especifique o nível de registro em log. Os valores com suporte são None, Warning e Verbose.
Quando definido como Verbose, o controlador de escala registra um motivo para cada alteração na contagem de trabalhadores, bem como informações sobre os gatilhos que resultam nessas decisões. Os logs detalhados incluem avisos de gatilho e os hashes usados pelos gatilhos antes e depois que o controlador de escala é executado.

Dica

Lembre-se de que, enquanto você deixa o registro em log do controlador de escala habilitado, ele afeta os custos potenciais de monitoramento do seu aplicativo de funções. Considere habilitar o registro em log até que você tenha coletado dados suficientes para entender como o controlador de escala está se comportando, depois desabilite-o.

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 um aplicativo de funções enviar dados ao Application Insights, ele precisa saber a chave de instrumentação de um recurso do Application Insights. A chave deve estar em uma configuração de aplicativo chamada APPINSIGHTS_INSTRUMENTATIONKEY.

Ao criar seu aplicativo de funções no portal do Azure, com a linha de comando usando o Azure Functions Core Tools, ou usando 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.

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 escolher um Local diferente em uma geografia do Azure onde deseja armazenar seus dados.

Habilitar o Application Insights ao criar um aplicativo de funções

Quando você escolhe Criar, um recurso de Application Insights é criado com seu aplicativo de funções, que tem APPINSIGHTS_INSTRUMENTATIONKEY 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 chave de instrumentação a partir desse recurso como uma configuração de aplicativo no seu aplicativo de funções.

  1. No portal do Azure, pesquise aplicativo de funções e selecione-o. Depois escolha 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.

    Habilitar o Application Insights no portal

  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.

    Criar um recurso do Application Insights

  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, clique em Configuração na opção Configurações e selecione Configurações do aplicativo. Se você vir uma configuração chamada APPINSIGHTS_INSTRUMENTATIONKEY, isso significa que a integração do Application Insights está habilitada para seu aplicativo de funções em execução no Azure. Se, por algum motivo, essa configuração não existir, adicione-a usando a sua chave de instrumentação do Application Insights como o valor.

Observação

As primeiras versões de Functions usavam o monitoramento interno, o que não é mais recomendado. Ao habilitar a integração do Application Insights para um aplicativo de funções como esse, você também deve desabilitar o registro em log interno.

Desabilitar o registro em log interno

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 o registro em log interno foi usado na produção, o registro de logs pode 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 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, veja 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

Seus aplicativos de funções podem ser parte essencial de soluções que, por natureza, geram altos volumes de telemetria (soluções de IoT, soluções baseadas em eventos, sistemas financeiros com alta carga, sistemas de integração...). Nesse caso, você deve pensar em fazer configurações adicionais para reduzir os custos, mas mantendo a observabilidade.

Dependendo de como a telemetria gerada será consumida, dos painéis em tempo real, dos alertas, do diagnóstico detalhado e assim por diante, será necessário definir uma estratégia para reduzir o volume de dados gerados. Essa estratégia permitirá 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, ela 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. Agora você pode decidir quais categorias deseja definir como 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 será 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. Aqui, 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 haverá um atraso, determinado por flushTimeout, na telemetria coletada. Se você definir essa categoria com outro valor diferente de Information, deixará de coletar os dados na tabela customMetrics e não exibirá as métricas na guia de visão geral da função.

    A captura de tela a seguir mostra os dados de telemetria de Host.Aggregator exibidos na guia de visão geral da função. Captura de tela da telemetria de Host.Aggregator exibida na guia de 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. Captura de tela da 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...). Se você definir essa categoria com valor diferente de Information, coletará apenas a telemetria gerada no nível de log definido (ou superior), ou seja, 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. Captura de tela da telemetria Host.Results 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. Captura de tela da telemetria de Host.Results 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"
      }
    }
  }
} 

Com essa configuração, você terá:

  • O valor padrão de todas as categorias de funções e telemetria definido como Warning (incluindo as categorias Microsoft e Trabalho) para que sejam coletados, por padrão, todos os erros e avisos gerados por ambos, o tempo de execução e o registro em log personalizado.

  • O nível de log de categoria Function é definido como Error, ou seja, em todas as funções, por padrão, somente logs de erros e exceções serão coletados (dependências, métricas geradas pelo usuário e eventos gerados pelo usuário serão ignorados).

  • Para a categoria Host.Aggregator, como ela está definida com o nível de log Error, nenhuma informação agregada das invocações de função será coletada na tabela customMetrics do Application Insights e nenhuma informação sobre as contagens de execuções (total, êxitos, falhas...) será mostrada 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 serã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, eventos personalizados). Para a mesma função, a categoria Function1.User (rastreamentos gerados pelo usuário) é definida como Error e, portanto, somente o log de erros personalizado será coletado. Observe que a configuração por função não é compatível com a v1.x.

  • 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. Observe que, nas métricas, as contagens do tipo taxa de solicitações e taxa de exceções são ajustadas a fim de compensar a taxa de amostragem, para que mostrem valores aproximadamente corretos no Metrics Explorer.

Dica

Experimente configurações diferentes para ter certeza de que você atendeu aos requisitos de registro em log, monitoramento e alertas. Verifique se você tem diagnósticos detalhados em caso de erros inesperados ou com problemas de funcionamento.

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 JSON de host.

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 abaixo para configurar níveis de log de funções individuais, como no host.json mostrado acima.

Caminho do host.json Configurações de aplicativo
logging.logLevel.default AzureFunctionsJobHost__logging__logLevel__default
logging.logLeve.Host.Aggregator AzureFunctionsJobHost__logging__logLevel__Host__Aggregator
logging.logLevel.Function AzureFunctionsJobHost__logging__logLevel__Function
logging.logLevel.Function.Function1 AzureFunctionsJobHost__logging__logLevel__Function1
logging.logLevel.Function.Function1.User AzureFunctionsJobHost__logging__logLevel__Function1.User

Você pode substituir as configurações diretamente na folha 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"

Observação

A substituição do host.json com a mudança das configurações do aplicativo reiniciará seu aplicativo de funções.

Próximas etapas

Para saber mais sobre o monitoramento, confira: