Partilhar via

Biblioteca de cliente opentelemetry 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 monitorização do Azure Monitor opentelemetry. Permite-lhe instrumentar as suas aplicações Python para capturar e comunicar telemetria ao Azure Monitor através dos exportadores do Azure Monitor.

Esta distribuição instala automaticamente as seguintes bibliotecas:

Instrumentações oficialmente suportadas

As instrumentações OpenTelemetry permitem a recolha automática de pedidos enviados a partir de bibliotecas instrumentadas subjacentes. Segue-se uma lista de instrumentações OpenTelemetry incluídas com a distribuição do Azure Monitor. Estas instrumentações estão ativadas por predefinição. Veja a secção Utilização abaixo para saber como optar ativamente por não participar nestas instrumentações.

Instrumentação Nome da biblioteca suportada Versões suportadas
Azure Core Tracing OpenTelemetry azure_sdk
OpenTelemetry Django Instrumentation django ligação
OpenTelemetry FastApi Instrumentation fastapi ligação
OpenTelemetry Flask Instrumentation flask ligação
OpenTelemetry Psycopg2 Instrumentation psycopg2 ligação
OpenTelemetry Requests Instrumentation pedidos ligação
OpenTelemetry UrlLib Instrumentation urllib Todos
OpenTelemetry UrlLib3 Instrumentation urllib3 ligação

Se quiser adicionar suporte para outra instrumentação openTelemetry, submeta um pedido de funcionalidade. Entretanto, pode utilizar a instrumentação OpenTelemetry manualmente através das suas próprias APIs (ou seja, instrument()) no seu código. Veja isto para obter um exemplo.

Conceitos-chave

Este pacote agrupe uma série de componentes do OpenTelemetry e do Azure Monitor para permitir a recolha e o envio de telemetria para o Azure Monitor. Para instrumentação MANUAL, utilize a configure_azure_monitor função . A instrumentação automática ainda não é suportada.

Os exportadores do OpenTelemetry do Azure Monitor são os principais componentes para tal. Poderá utilizar os exportadores e as respetivas APIs diretamente através deste pacote. Aceda à documentação do exportador para compreender como os componentes do OpenTelemetry e do Azure Monitor funcionam na ativação da recolha e exportação de telemetria.

Atualmente, todas as instrumentações disponíveis no OpenTelemetry estão num estado beta, o que significa que não são estáveis e podem sofrer alterações interruptivas no futuro. Estão a ser feitos esforços para os empurrar para um estado mais estável.

Introdução

Pré-requisitos

Para utilizar este pacote, tem de ter:

Instalar o pacote

Instale a Distribuição opentelemetry do Azure Monitor com pip:

pip install azure-monitor-opentelemetry

Utilização

Pode utilizar configure_azure_monitor para configurar a instrumentação da sua aplicação para o Azure Monitor. configure_azure_monitor suporta os seguintes argumentos opcionais. Todos os parâmetros de pass-in têm prioridade sobre quaisquer variáveis de ambiente relacionadas.

Parâmetro Description Variável de Ambiente
connection_string O cadeia de ligação para o recurso do Application Insights. O cadeia de ligação será preenchido automaticamente a APPLICATIONINSIGHTS_CONNECTION_STRING partir da variável de ambiente, se não for explicitamente transmitido. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name O nome do logger python no qual a telemetria é recolhida. N/A
instrumentation_options Um dicionário aninhado que determina que instrumentações ativar ou desativar. As instrumentações são referidas pelos respetivos Nomes de Biblioteca. Por exemplo, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} desativará o Rastreio do Núcleo do Azure e a instrumentação do Flask, mas deixará o Django e as outras instrumentações predefinidas ativadas. A OTEL_PYTHON_DISABLED_INSTRUMENTATIONS variável de ambiente explicada abaixo também pode ser utilizada para desativar instrumentações. N/A

Pode configurar ainda mais com variáveis de ambiente OpenTelemetry , tais como: | Variável de Ambiente | Descrição | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Especifica o recurso OpenTelemetry associado à sua aplicação. | | OTEL_LOGS_EXPORTER | Se estiver definido como None, desativa a recolha e exportação da telemetria de registo. | | OTEL_METRICS_EXPORTER | Se estiver definido como None, desativa a recolha e exportação de telemetria de métricas. | | OTEL_TRACES_EXPORTER | Se estiver definido como None, desativa a recolha e exportação da telemetria de rastreio distribuído. | | OTEL_BLRP_SCHEDULE_DELAY | Especifica o intervalo de exportação do registo em milissegundos. A predefinição é 5000. | | OTEL_BSP_SCHEDULE_DELAY | Especifica o intervalo de exportação de rastreio distribuído em milissegundos. A predefinição é 5000. | | OTEL_TRACES_SAMPLER_ARG | Especifica a proporção de telemetria de rastreio distribuído a ser amostrada. Os valores aceites estão no intervalo [0,1]. A predefinição é 1.0, o que significa que não foi amostrada qualquer telemetria. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Especifica qual das instrumentações suportadas a desativar. As instrumentações desativadas não serão instrumentadas como parte do configure_azure_monitor. No entanto, ainda podem ser instrumentados instrument() manualmente com diretamente. Aceita uma lista separada por vírgulas de Nomes de Bibliotecas em minúsculas. Por exemplo, defina como "psycopg2,fastapi" para desativar as instrumentações Psycopg2 e FastAPI. A predefinição é uma lista vazia, ativando todas as instrumentações suportadas. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Uma variável experimental de ambiente OpenTelemetry utilizada para especificar Detetores de Recursos a serem utilizados para gerar Atributos de Recursos. Esta é uma funcionalidade experimental e o nome desta variável e o respetivo comportamento podem mudar de uma forma não retrocompatível. A predefinição é "azure_app_service,azure_vm" para ativar os Detetores de Recursos do Azure para Serviço de Aplicações do Azure e VM do Azure. Para adicionar ou remover detetores de recursos específicos, defina a variável de ambiente em conformidade. Veja a Documentação do Detetor de Recursos do Python do OpenTelemetry para obter mais informações. |

Configurações do Exportador de OpenTelemetry do Azure Monitor

Pode transmitir os parâmetros de configuração do exportador openTelemetry do Azure Monitor diretamente para configure_azure_monitor. Veja a configuração adicional relacionada com a exportação aqui.

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

Exemplos

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

Monitorização no Funções do Azure

Correlação de rastreio

Os pedidos recebidos controlados que entram na sua aplicação Python alojada no Funções do Azure não serão automaticamente correlacionados com o controlo da telemetria na mesma. Pode obter manualmente a correlação de rastreio ao extrair diretamente, TraceContext 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 registo

A própria função de trabalho de Funções do Azure envia a telemetria de registo sem a utilização do sdk do azure monitor (a chamada para configure_azure_monitor()). Isto fará com que se depare com entradas de telemetria duplicadas ao enviar telemetria de registo. A nossa recomendação para os clientes é utilizar apenas o SDK, uma vez que permitirá muito mais telemetria e funcionalidades avançadas do que utilizar a incorporada fornecida pela função de trabalho Funções do Azure. Pode desativar o Funções do Azure logger de telemetria ao limpar a lista de processadores do seu logger.

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

Certifique-se de que chama o acima ANTES de quaisquer loggers ou a chamada para configure_azure_monitor() está configurada.

Também pode desativar o registo através Funções do Azure configuração.

v2.x+

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

v1.x

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

Resolução de problemas

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

Passos seguintes

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

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Documentação adicional