Configurar o Azure Monitor para seu aplicativo Python

O Azure Monitor dá suporte ao rastreamento distribuído, coleta de métricas e registro em log de aplicativos Python.

A solução suportada pela Microsoft para rastrear e exportar dados para seus aplicativos Python é por meio do SDK do OpenCensus Python por meio dos exportadores do Azure Monitor.

A Microsoft não recomenda o uso de outros SDKs de telemetria para Python como uma solução de telemetria porque eles não são suportados.

O OpenCensus está convergindo para o OpenTelemetry. Continuamos a recomendar o OpenCensus enquanto o OpenTelemetry amadurece gradualmente.

Pré-requisitos

Precisa de uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Apresentando o OpenCensus Python SDK

OpenCensus é um conjunto de bibliotecas de código aberto para permitir a coleta de rastreamento distribuído, métricas e telemetria de registro. Usando os exportadores do Azure Monitor, você pode enviar essa telemetria coletada para o Application Insights. Este artigo orienta você pelo processo de configuração dos exportadores do OpenCensus e do Azure Monitor para Python para enviar seus dados de monitoramento para o Azure Monitor.

Instrumento com OpenCensus Python SDK com exportadores do Azure Monitor

Instale os exportadores do OpenCensus Azure Monitor:

python -m pip install opencensus-ext-azure

O SDK usa três exportadores do Azure Monitor para enviar diferentes tipos de telemetria para o Azure Monitor. Eles são trace, metrics, e logs. Para obter mais informações sobre esses tipos de telemetria, consulte a Visão geral da plataforma de dados. Use as instruções a seguir para enviar esses tipos de telemetria através dos três exportadores.

Mapeamentos de tipo de telemetria

O OpenCensus mapeia os seguintes exportadores para os tipos de telemetria que você vê no Azure Monitor.

Registos

1. Primeiro, vamos gerar alguns dados de log locais.

   
   import logging
   
   logger = logging.getLogger(__name__)
   
   def main():
       """Generate random log data."""
       for num in range(5):
           logger.warning(f"Log Entry - {num}")
   
   if __name__ == "__main__":
       main()
   

2. Uma entrada de log é emitida para cada número no intervalo.

   Log Entry - 0
   Log Entry - 1
   Log Entry - 2
   Log Entry - 3
   Log Entry - 4
   

3. Queremos ver esses dados de log no Azure Monitor. Você pode especificá-lo em uma variável de ambiente, APPLICATIONINSIGHTS_CONNECTION_STRING. Você também pode passar o connection_string diretamente para o AzureLogHandler, mas as cadeias de conexão não devem ser adicionadas ao controle de versão.

   APPLICATIONINSIGHTS_CONNECTION_STRING=<appinsights-connection-string>
   

   Recomendamos usar a cadeia de conexão para instanciar os exportadores usados para enviar telemetria para o Application Insights. Modifique seu código da etapa anterior com base no seguinte exemplo de código:

   import logging
   from opencensus.ext.azure.log_exporter import AzureLogHandler
   
   logger = logging.getLogger(__name__)
   logger.addHandler(AzureLogHandler())
   
   # Alternatively manually pass in the connection_string
   # logger.addHandler(AzureLogHandler(connection_string=<appinsights-connection-string>))
   
   """Generate random log data."""
   for num in range(5):
       logger.warning(f"Log Entry - {num}")
   

4. O exportador envia dados de log para o Azure Monitor. Pode encontrar os dados em traces.

   Neste contexto, traces não é o mesmo que tracing. Aqui, traces refere-se ao tipo de telemetria que você vê no Azure Monitor quando utiliza AzureLogHandlero . Mas tracing refere-se a um conceito no OpenCensus e se relaciona com o rastreamento distribuído.

   Nota

   O registrador raiz é configurado com o nível de warning. Isso significa que todos os logs enviados com menos gravidade são ignorados e, por sua vez, não serão enviados para o Azure Monitor. Para obter mais informações, consulte Documentação de registro.

5. Você também pode adicionar propriedades personalizadas às suas mensagens de log no argumento de extra palavra-chave usando o custom_dimensions campo. Essas propriedades aparecem como pares chave-valor no customDimensions Azure Monitor.

   Nota

   Para que esse recurso funcione, você precisa passar um dicionário para o custom_dimensions campo. Se você passar argumentos de qualquer outro tipo, o registrador os ignorará.

   import logging
   
   from opencensus.ext.azure.log_exporter import AzureLogHandler
   
   logger = logging.getLogger(__name__)
   logger.addHandler(AzureLogHandler())
   # Alternatively manually pass in the connection_string
   # logger.addHandler(AzureLogHandler(connection_string=<appinsights-connection-string>))
   
   properties = {'custom_dimensions': {'key_1': 'value_1', 'key_2': 'value_2'}}
   
   # Use properties in logging statements
   logger.warning('action', extra=properties)
   

Configurar o registro em log para aplicativos Django

Você pode configurar o registro em log explicitamente no código do seu aplicativo, como o anterior para seus aplicativos Django, ou pode especificá-lo na configuração de log do Django. Esse código pode entrar em qualquer arquivo que você usar para a configuração de configurações do site Django, normalmente settings.py.

Para obter informações sobre como definir as configurações do Django, consulte Configurações do Django. Para obter mais informações sobre como configurar o registro em log, consulte Django logging.

LOGGING = {
    "handlers": {
        "azure": {
            "level": "DEBUG",
            "class": "opencensus.ext.azure.log_exporter.AzureLogHandler",
            "connection_string": "<appinsights-connection-string>",
        },
        "console": {
            "level": "DEBUG",
            "class": "logging.StreamHandler",
            "stream": sys.stdout,
        },
      },
    "loggers": {
        "logger_name": {"handlers": ["azure", "console"]},
    },
}

Certifique-se de usar o registrador com o mesmo nome especificado em sua configuração.

# views.py

import logging
from django.shortcuts import request

logger = logging.getLogger("logger_name")
logger.warning("this will be tracked")

Enviar exceções

O OpenCensus Python não rastreia e envia exception telemetria automaticamente. Ele é enviado usando AzureLogHandler exceções através da biblioteca de log do Python. Você pode adicionar propriedades personalizadas como faz com o registro em log normal.

import logging

from opencensus.ext.azure.log_exporter import AzureLogHandler

logger = logging.getLogger(__name__)
logger.addHandler(AzureLogHandler())
# Alternatively, manually pass in the connection_string
# logger.addHandler(AzureLogHandler(connection_string=<appinsights-connection-string>))

properties = {'custom_dimensions': {'key_1': 'value_1', 'key_2': 'value_2'}}

# Use properties in exception logs
try:
    result = 1 / 0  # generate a ZeroDivisionError
except Exception:
    logger.exception('Captured an exception.', extra=properties)

Como você deve registrar exceções explicitamente, cabe a você como registrar exceções não tratadas. O OpenCensus não coloca restrições sobre como fazer esse registro, mas você deve registrar explicitamente a telemetria de exceção.

Enviar eventos

Você pode enviar customEvent telemetria exatamente da mesma maneira que envia trace telemetria, exceto usando AzureEventHandler .

import logging
from opencensus.ext.azure.log_exporter import AzureEventHandler

logger = logging.getLogger(__name__)
logger.addHandler(AzureEventHandler())
# Alternatively manually pass in the connection_string
# logger.addHandler(AzureEventHandler(connection_string=<appinsights-connection-string>))

logger.setLevel(logging.INFO)
logger.info('Hello, World!')

Amostragem

Para obter informações sobre amostragem no OpenCensus, consulte Amostragem no OpenCensus.

Correlação de registos

Para obter informações sobre como enriquecer seus logs com dados de contexto de rastreamento, consulte OpenCensus Python logs integration.

Modificar telemetria

Para obter informações sobre como modificar a telemetria controlada antes de ser enviada para o Azure Monitor, consulte Processadores de telemetria OpenCensus Python.

Métricas

OpenCensus.stats dá suporte a quatro métodos de agregação, mas fornece suporte parcial para o Azure Monitor:

• Contagem: A contagem do número de pontos de medição. O valor é cumulativo, só pode aumentar e redefine para 0 na reinicialização.
• Soma: Soma dos pontos de medição. O valor é cumulativo, só pode aumentar e redefine para 0 na reinicialização.
• LastValue: Mantém o último valor registado e deixa cair tudo o resto.
• Distribuição: o exportador do Azure não suporta a distribuição de histograma dos pontos de medição.

Exemplo de agregação de contagem

1. Primeiro, vamos gerar alguns dados de métricas locais. Criamos uma métrica para acompanhar o número de vezes que o usuário seleciona a tecla Enter .

   
   from datetime import datetime
   from opencensus.stats import aggregation as aggregation_module
   from opencensus.stats import measure as measure_module
   from opencensus.stats import stats as stats_module
   from opencensus.stats import view as view_module
   from opencensus.tags import tag_map as tag_map_module
   
   stats = stats_module.stats
   view_manager = stats.view_manager
   stats_recorder = stats.stats_recorder
   
   prompt_measure = measure_module.MeasureInt("prompts",
                                              "number of prompts",
                                              "prompts")
   prompt_view = view_module.View("prompt view",
                                  "number of prompts",
                                  [],
                                  prompt_measure,
                                  aggregation_module.CountAggregation())
   view_manager.register_view(prompt_view)
   mmap = stats_recorder.new_measurement_map()
   tmap = tag_map_module.TagMap()
   
   def main():
       for _ in range(4):
           mmap.measure_int_put(prompt_measure, 1)
           mmap.record(tmap)
           metrics = list(mmap.measure_to_view_map.get_metrics(datetime.utcnow()))
           print(metrics[0].time_series[0].points[0])
   
   if __name__ == "__main__":
       main()
   

2. As métricas são criadas para acompanhar muitas vezes. A cada entrada, o valor é incrementado e as informações métricas aparecem no console. As informações incluem o valor atual e o carimbo de data/hora atual quando a métrica foi atualizada.

   Point(value=ValueLong(5), timestamp=2019-10-09 20:58:04.930426)
   Point(value=ValueLong(6), timestamp=2019-10-09 20:58:05.170167)
   Point(value=ValueLong(7), timestamp=2019-10-09 20:58:05.438614)
   Point(value=ValueLong(7), timestamp=2019-10-09 20:58:05.834216)
   

3. A inserção de valores é útil para fins de demonstração, mas queremos emitir os dados métricos para o Azure Monitor. Passe sua cadeia de conexão diretamente para o exportador. Ou você pode especificá-lo em uma variável de ambiente, APPLICATIONINSIGHTS_CONNECTION_STRING. Recomendamos usar a cadeia de conexão para instanciar os exportadores usados para enviar telemetria para o Application Insights. Modifique seu código da etapa anterior com base no seguinte exemplo de código:

   from datetime import datetime
   from opencensus.ext.azure import metrics_exporter
   from opencensus.stats import aggregation as aggregation_module
   from opencensus.stats import measure as measure_module
   from opencensus.stats import stats as stats_module
   from opencensus.stats import view as view_module
   from opencensus.tags import tag_map as tag_map_module
   
   stats = stats_module.stats
   view_manager = stats.view_manager
   stats_recorder = stats.stats_recorder
   
   prompt_measure = measure_module.MeasureInt("prompts",
                                              "number of prompts",
                                              "prompts")
   prompt_view = view_module.View("prompt view",
                                  "number of prompts",
                                  [],
                                  prompt_measure,
                                  aggregation_module.CountAggregation())
   view_manager.register_view(prompt_view)
   mmap = stats_recorder.new_measurement_map()
   tmap = tag_map_module.TagMap()
   
   exporter = metrics_exporter.new_metrics_exporter()
   # Alternatively manually pass in the connection_string
   # exporter = metrics_exporter.new_metrics_exporter(connection_string='<appinsights-connection-string>')
   
   view_manager.register_exporter(exporter)
   
   def main():
       for _ in range(10):
           input("Press enter.")
           mmap.measure_int_put(prompt_measure, 1)
           mmap.record(tmap)
           metrics = list(mmap.measure_to_view_map.get_metrics(datetime.utcnow()))
           print(metrics[0].time_series[0].points[0])
   
   if __name__ == "__main__":
       main()
   

4. O exportador envia dados de métrica para o Azure Monitor em um intervalo fixo. Você deve definir esse valor como 60 segundos, pois o back-end do Application Insights pressupõe a agregação de pontos de métricas em um intervalo de tempo de 60 segundos. Estamos rastreando uma única métrica, portanto, esses dados métricos, com qualquer valor e carimbo de data/hora que contenham, são enviados a cada intervalo. Os dados são cumulativos, só podem aumentar e são redefinidos para 0 na reinicialização.

   Você pode encontrar os dados em customMetrics, mas as customMetrics propriedades valueCount, valueSum, valueMin, valueMax, e valueStdDev não são usadas efetivamente.

Definir dimensões personalizadas em métricas

O OpenCensus Python SDK permite que você adicione dimensões personalizadas à sua telemetria de métricas usando tags, que são como um dicionário de pares chave-valor.

1. Insira as tags que você deseja usar no mapa de tags. O mapa de tags funciona como uma espécie de "pool" de todas as tags disponíveis que você pode usar.

   ...
   tmap = tag_map_module.TagMap()
   tmap.insert("url", "http://example.com")
   ...
   

2. Para um View, especifique as tags que você deseja usar ao gravar métricas com essa exibição por meio da chave de tag.

   ...
   prompt_view = view_module.View("prompt view",
                               "number of prompts",
                               ["url"], # <-- A sequence of tag keys used to specify which tag key/value to use from the tag map
                               prompt_measure,
                               aggregation_module.CountAggregation())
   ...
   

3. Certifique-se de usar o mapa de tags quando estiver gravando no mapa de medição. As chaves de View tag especificadas no devem ser encontradas no mapa de tags usado para gravar.

   ...
   mmap = stats_recorder.new_measurement_map()
   mmap.measure_int_put(prompt_measure, 1)
   mmap.record(tmap) # <-- pass the tag map in here
   ...
   

4. customMetrics Na tabela, todos os registros métricos emitidos usando prompt_view têm dimensões personalizadas{"url":"http://example.com"}.

5. Para produzir tags com valores diferentes usando as mesmas chaves, crie novos mapas de tags para elas.

   ...
   tmap = tag_map_module.TagMap()
   tmap2 = tag_map_module.TagMap()
   tmap.insert("url", "http://example.com")
   tmap2.insert("url", "https://www.wikipedia.org/wiki/")
   ...
   

Contadores de desempenho

Por padrão, o exportador de métricas envia um conjunto de contadores de desempenho para o Azure Monitor. Você pode desabilitar esse recurso definindo o sinalizador enable_standard_metrics como False no construtor do exportador de métricas.

...
exporter = metrics_exporter.new_metrics_exporter(
  enable_standard_metrics=False,
  )
...

Os seguintes contadores de desempenho são enviados no momento:

• Memória disponível (bytes)
• Tempo do processador da CPU (percentagem)
• Taxa de solicitação recebida (por segundo)
• Tempo médio de execução da solicitação de entrada (milissegundos)
• Uso da CPU do processo (porcentagem)
• Processar bytes privados (bytes)

Você deve ser capaz de ver essas métricas em performanceCounters. Para obter mais informações, consulte Contadores de desempenho.

Modificar telemetria

Para obter informações sobre como modificar a telemetria controlada antes de ser enviada para o Azure Monitor, consulte Processadores de telemetria OpenCensus Python.

Rastreio

1. Primeiro, vamos gerar alguns dados de rastreamento localmente. Em Python IDLE, ou seu editor de escolha, digite o seguinte código:

   from opencensus.trace.samplers import ProbabilitySampler
   from opencensus.trace.tracer import Tracer
   
   tracer = Tracer(sampler=ProbabilitySampler(1.0))
   
   def main():
       with tracer.span(name="test") as span:
           for value in range(5):
               print(value)
   
   
   if __name__ == "__main__":
       main()
   

2. Com cada entrada, o valor é impresso no shell. O módulo OpenCensus Python gera uma parte correspondente do SpanData. O projeto OpenCensus define um traço como uma árvore de vãos.

   0
   [SpanData(name='test', context=SpanContext(trace_id=8aa41bc469f1a705aed1bdb20c342603, span_id=None, trace_options=TraceOptions(enabled=True), tracestate=None), span_id='15ac5123ac1f6847', parent_span_id=None, attributes=BoundedDict({}, maxlen=32), start_time='2019-06-27T18:21:22.805429Z', end_time='2019-06-27T18:21:44.933405Z', child_span_count=0, stack_trace=None, annotations=BoundedList([], maxlen=32), message_events=BoundedList([], maxlen=128), links=BoundedList([], maxlen=32), status=None, same_process_as_parent_span=None, span_kind=0)]
   1
   [SpanData(name='test', context=SpanContext(trace_id=8aa41bc469f1a705aed1bdb20c342603, span_id=None, trace_options=TraceOptions(enabled=True), tracestate=None), span_id='2e512f846ba342de', parent_span_id=None, attributes=BoundedDict({}, maxlen=32), start_time='2019-06-27T18:21:44.933405Z', end_time='2019-06-27T18:21:46.156787Z', child_span_count=0, stack_trace=None, annotations=BoundedList([], maxlen=32), message_events=BoundedList([], maxlen=128), links=BoundedList([], maxlen=32), status=None, same_process_as_parent_span=None, span_kind=0)]
   2
   [SpanData(name='test', context=SpanContext(trace_id=8aa41bc469f1a705aed1bdb20c342603, span_id=None, trace_options=TraceOptions(enabled=True), tracestate=None), span_id='f3f9f9ee6db4740a', parent_span_id=None, attributes=BoundedDict({}, maxlen=32), start_time='2019-06-27T18:21:46.157732Z', end_time='2019-06-27T18:21:47.269583Z', child_span_count=0, stack_trace=None, annotations=BoundedList([], maxlen=32), message_events=BoundedList([], maxlen=128), links=BoundedList([], maxlen=32), status=None, same_process_as_parent_span=None, span_kind=0)]
   

3. Exibir a saída é útil para fins de demonstração, mas queremos emitir SpanData para o Azure Monitor. Passe sua cadeia de conexão diretamente para o exportador. Ou você pode especificá-lo em uma variável de ambiente, APPLICATIONINSIGHTS_CONNECTION_STRING. Recomendamos usar a cadeia de conexão para instanciar os exportadores usados para enviar telemetria para o Application Insights. Modifique seu código da etapa anterior com base no seguinte exemplo de código:

   from opencensus.ext.azure.trace_exporter import AzureExporter
   from opencensus.trace.samplers import ProbabilitySampler
   from opencensus.trace.tracer import Tracer
   
   tracer = Tracer(
       exporter=AzureExporter(),
       sampler=ProbabilitySampler(1.0),
   )
   # Alternatively manually pass in the connection_string
   # exporter = AzureExporter(
   #   connection_string='<appinsights-connection-string>',
   #   ...
   # )
   
   def main():
       with tracer.span(name="test") as span:
           for value in range(5):
               print(value)
   
   if __name__ == "__main__":
       main()
   

4. Agora, quando você executa o script Python, apenas o valor está sendo impresso no shell. O criado SpanData é enviado para o Azure Monitor. Você pode encontrar os dados de span emitidos em dependencies.

   Para obter mais informações sobre solicitações de saída, consulte Dependências do OpenCensus Python. Para obter mais informações sobre solicitações de entrada, consulte Solicitações Python do OpenCensus.

Amostragem

Para obter informações sobre amostragem no OpenCensus, consulte Amostragem no OpenCensus.

Correlação de vestígios

Para obter mais informações sobre a correlação de telemetria em seus dados de rastreamento, consulte Correlação de telemetria OpenCensus Python.

Modificar telemetria

Para obter mais informações sobre como modificar a telemetria controlada antes de ser enviada para o Azure Monitor, consulte Processadores de telemetria OpenCensus Python.

Configurar exportadores do Azure Monitor

Conforme mostrado, há três exportadores diferentes do Azure Monitor que oferecem suporte ao OpenCensus. Cada um envia diferentes tipos de telemetria para o Azure Monitor. Para ver que tipos de telemetria cada exportador envia, consulte a tabela a seguir.

Cada exportador aceita os mesmos argumentos para configuração, passados pelos construtores. Você pode ver informações sobre cada um aqui:

Integração com o Azure Functions

Para capturar telemetria personalizada em ambientes do Azure Functions, use a extensão OpenCensus Python Azure Functions. Para obter mais informações, consulte o Guia do desenvolvedor Python do Azure Functions.

Autenticação (pré-visualização)

Cada um dos exportadores do Azure Monitor dá suporte à configuração de envio seguro de cargas úteis de telemetria por meio da autenticação OAuth com o Azure Ative Directory. Para obter mais informações, consulte a documentação de autenticação.

Ver os seus dados com consultas

Você pode exibir os dados de telemetria que foram enviados do seu aplicativo por meio da guia Logs (Analytics ).

Na lista em Ativo:

• Para telemetria enviada com o exportador de rastreamento do Azure Monitor, as solicitações de entrada aparecem em requests. As solicitações de saída ou em processo aparecem em dependencies.
• Para telemetria enviada com o exportador de métricas do Azure Monitor, as métricas enviadas aparecem em customMetrics.
• Para telemetria enviada com o exportador de logs do Azure Monitor, os logs aparecem em traces. As exceções aparecem em exceptions.

Para obter mais informações sobre como usar consultas e logs, consulte Logs no Azure Monitor.

Configurar e habilitar a autenticação baseada em ID do Microsoft Entra

Crie as credenciais apropriadas e passe-as para o construtor do exportador do Azure Monitor. Verifique se a cadeia de conexão está configurada com a chave de instrumentação e o ponto de extremidade de ingestão do recurso.

Os OpenCensus exportadores do Azure Monitor dão suporte a esses tipos de autenticação. Recomendamos o uso de identidades gerenciadas em ambientes de produção.

Identidade gerida atribuída pelo sistema

from azure.identity import ManagedIdentityCredential

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

credential = ManagedIdentityCredential()
tracer = Tracer(
    exporter=AzureExporter(credential=credential, connection_string="InstrumentationKey=<your-instrumentation-key>;IngestionEndpoint=<your-ingestion-endpoint>"),
    sampler=ProbabilitySampler(1.0)
)
...

Identidade gerida atribuída pelo utilizador

from azure.identity import ManagedIdentityCredential

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

credential = ManagedIdentityCredential(client_id="<client-id>")
tracer = Tracer(
    exporter=AzureExporter(credential=credential, connection_string="InstrumentationKey=<your-instrumentation-key>;IngestionEndpoint=<your-ingestion-endpoint>"),
    sampler=ProbabilitySampler(1.0)
)
...

Saiba mais sobre o OpenCensus for Python

• OpenCensus Python no GitHub
• Personalização
• Exportadores do Azure Monitor no GitHub
• Integrações OpenCensus
• Aplicativos de exemplo do Azure Monitor

Resolução de Problemas

Testar a conectividade entre o host do aplicativo e o serviço de ingestão

SDKs e agentes do Application Insights enviam telemetria para serem ingeridos como chamadas REST para nossos pontos de extremidade de ingestão. Você pode testar a conectividade do seu servidor Web ou máquina host de aplicativo para os pontos de extremidade do serviço de ingestão usando clientes REST brutos do PowerShell ou comandos curl. Consulte Solucionar problemas de telemetria de aplicativo ausente no Azure Monitor Application Insights.

Release Notes (Notas de Lançamento)

Para obter as notas de versão mais recentes, consulte Python Azure Monitor Exporter

Nossas atualizações de serviço também resumem as principais melhorias do Application Insights.

Próximos passos

• Para habilitar experiências de uso, habilite o monitoramento de usuários da Web ou do navegador
• Rastreie as solicitações recebidas.
• Rastreie solicitações de saída.
• Consulte o mapa de candidaturas.
• Saiba como fazer o monitoramento de desempenho de ponta a ponta.

Alertas

• Visão geral da disponibilidade: crie testes para garantir que seu site esteja visível na Web.
• Diagnóstico inteligente: Estes testes são executados automaticamente, pelo que não precisa de fazer nada para os configurar. Estes indicam se a aplicação tem uma taxa de pedidos com falha fora do normal.
• Alertas métricos: defina alertas para avisá-lo se uma métrica ultrapassar um limite. Pode defini-los em métricas personalizadas que introduz no código da sua aplicação.