Compartilhar via

Biblioteca de clientes do Opentelemetry Distro do Azure Monitor para Python – versão 1.1.1

  • Artigo

A Distribuição do Azure Monitor do Opentelemetry Python fornece vários componentes instaláveis disponíveis para uma solução de monitoramento do Opentelemetry Azure Monitor. Ele permite que você instrumente seus aplicativos Python para capturar e relatar telemetria ao Azure Monitor por meio dos exportadores do Azure Monitor.

Essa distribuição instala automaticamente as seguintes bibliotecas:

Instrumentações com suporte oficial

As instrumentações OpenTelemetry permitem a coleta automática de solicitações enviadas de bibliotecas instrumentadas subjacentes. Veja a seguir uma lista de instrumentações OpenTelemetry que vêm agrupadas com a distribuição do Azure Monitor. Essas instrumentações são habilitadas por padrão. Consulte a seção Uso abaixo para saber como recusar essas instrumentações.

Instrumentação Nome da biblioteca com suporte Versões com suporte
OpenTelemetry de Rastreamento do Azure Core azure_sdk
Instrumentação OpenTelemetry Django Django link
Instrumentação FastApi do OpenTelemetry fastapi link
Instrumentação OpenTelemetry Flask flask link
Instrumentação OpenTelemetry Psycopg2 psycopg2 link
Instrumentação de Solicitações openTelemetry requests link
Instrumentação UrlLib do OpenTelemetry urllib Tudo
Instrumentação OpenTelemetry UrlLib3 urllib3 link

Se você quiser adicionar suporte para outra instrumentação OpenTelemetry, envie uma solicitação de recurso. Enquanto isso, você pode usar a instrumentação OpenTelemetry manualmente por meio de suas próprias APIs (ou seja, instrument()) em seu código. Veja isso para obter um exemplo.

Principais conceitos

Esse pacote agrupa uma série de componentes do OpenTelemetry e do Azure Monitor para habilitar a coleta e o envio de telemetria para o Azure Monitor. Para instrumentação MANUAL, use a configure_azure_monitor função . A instrumentação AUTOMÁTICA ainda não tem suporte.

Os exportadores opentelemetry do Azure Monitor são os componentes main para fazer isso. Você poderá usar os exportadores e suas APIs diretamente por meio deste pacote. Acesse a documentação do exportador para entender como os componentes do OpenTelemetry e do Azure Monitor funcionam na habilitação da coleta e exportação de telemetria.

Atualmente, todas as instrumentações disponíveis no OpenTelemetry estão em um estado beta, o que significa que elas não são estáveis e podem ter alterações interruptivas no futuro. Esforços estão sendo feitos para empurrá-los para um estado mais estável.

Introdução

Pré-requisitos

Para usar esse pacote, você deve ter:

Instalar o pacote

Instale o Azure Monitor Opentelemetry Distro com pip:

pip install azure-monitor-opentelemetry

Uso

Você pode usar configure_azure_monitor para configurar a instrumentação do aplicativo para o Azure Monitor. configure_azure_monitor dá suporte aos seguintes argumentos opcionais. Todos os parâmetros de passagem são prioritários em relação a quaisquer variáveis de ambiente relacionadas.

Parâmetro Descrição Variável de ambiente
connection_string O cadeia de conexão para o recurso do Application Insights. O cadeia de conexão será preenchido automaticamente da APPLICATIONINSIGHTS_CONNECTION_STRING variável de ambiente se não for transmitido explicitamente. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name O nome do agente do Python sob o qual a telemetria é coletada. N/A
instrumentation_options Um dicionário aninhado que determina quais instrumentações habilitar ou desabilitar. As instrumentações são referenciadas por seus Nomes de Biblioteca. Por exemplo, desabilitará o Rastreamento do Azure Core e a instrumentação do Flask, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} mas deixará o Django e as outras instrumentações padrão habilitadas. A OTEL_PYTHON_DISABLED_INSTRUMENTATIONS variável de ambiente explicada abaixo também pode ser usada para desabilitar instrumentações. N/A

Você pode configurar ainda mais com variáveis de ambiente OpenTelemetry , como: | Variável de ambiente | Descrição | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Especifica o recurso OpenTelemetry associado ao seu aplicativo. | | OTEL_LOGS_EXPORTER | Se definido como , desabilita a Nonecoleta e a exportação de telemetria de registro em log. | | OTEL_METRICS_EXPORTER | Se definido como , desabilita a Nonecoleta e a exportação de telemetria de métrica. | | OTEL_TRACES_EXPORTER | Se definido como , desabilita a Nonecoleta e a exportação da telemetria de rastreamento distribuído. | | OTEL_BLRP_SCHEDULE_DELAY | Especifica o intervalo de exportação de log em milissegundos. Usa 5.000 como padrão. | | OTEL_BSP_SCHEDULE_DELAY | Especifica o intervalo de exportação de rastreamento distribuído em milissegundos. Usa 5.000 como padrão. | | OTEL_TRACES_SAMPLER_ARG | Especifica a taxa de telemetria de rastreamento distribuído a ser amostrada. Os valores aceitos estão no intervalo [0,1]. O padrão é 1.0, o que significa que nenhuma telemetria é amostrada. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Especifica qual das instrumentações com suporte para desabilitar. Instrumentações desabilitadas não serão instrumentadas como parte do configure_azure_monitor. No entanto, eles ainda podem ser instrumentados manualmente com instrument() diretamente. Aceita uma lista separada por vírgulas de nomes de biblioteca minúsculos. Por exemplo, defina como "psycopg2,fastapi" para desabilitar as instrumentações Psycopg2 e FastAPI. O padrão é uma lista vazia, habilitando todas as instrumentações com suporte. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Uma variável de ambiente OpenTelemetry experimental usada para especificar detectores de recursos a serem usados para gerar atributos de recurso. Esse é um recurso experimental e o nome dessa variável e seu comportamento podem ser alterados de maneira não compatível com versões anteriores. O padrão é "azure_app_service,azure_vm" para habilitar os Detectores de Recursos do Azure para Serviço de Aplicativo do Azure e VM do Azure. Para adicionar ou remover detectores de recursos específicos, defina a variável de ambiente adequadamente. Consulte a Documentação do Detector de Recursos do Python OpenTelemetry para obter mais informações. |

Configurações do Exportador opentelemetry do Azure monitor

Você pode passar os parâmetros de configuração do exportador OpenTelemetry do Azure Monitor diretamente para configure_azure_monitor. Consulte configuração adicional relacionada à exportação aqui.

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

Exemplos

Os exemplos estão disponíveis aqui para demonstrar como utilizar as opções de configuração acima.

Monitoramento em Azure Functions

Correlação de rastreamento

As solicitações de entrada controladas que chegam ao aplicativo Python hospedado no Azure Functions não serão correlacionadas automaticamente com a telemetria sendo rastreada dentro dele. Você pode obter manualmente a correlação de rastreamento extraindo o TraceContext diretamente, conforme mostrado abaixo:


import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

Problemas de registro em log

O próprio trabalho do Azure Functions envia a própria telemetria de registro em log sem o uso do sdk do azure Monitor (a chamada para configure_azure_monitor()). Isso fará com que você possivelmente experimente entradas de telemetria duplicadas ao enviar telemetria de log. Nossa recomendação aos clientes é usar apenas o SDK, pois ele permitirá telemetria e recursos muito mais avançados do que usar o interno fornecido pelo Azure Functions trabalho. Você pode desativar o agente de telemetria Azure Functions limpando a lista de manipuladores do agente.

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

Certifique-se de chamar o antes de qualquer agente ou a chamada para configure_azure_monitor() é configurada.

Você também pode desabilitar o registro em log por meio Azure Functions configuração.

v2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

v1. x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

Solução de problemas

O exportador gera exceções definidas no Azure Core.

Próximas etapas

Confira a documentação para obter mais informações.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Documentação adicional