Migração do SDK do OpenCensus Python e do exportador do OpenCensus Python do Azure Monitor para a distribuição OpenTelemetry Python do Azure Monitor

  • Artigo

Observação

O SDK do Python do OpenCensus foi preterido, mas a Microsoft dá suporte a ele até a desativação em 30 de setembro de 2024. Agora, recomendamos a oferta do Python baseada no OpenTelemetry e fornecemos diretrizes de migração.

Siga estas etapas para migrar aplicativos Python para a distribuição OpenTelemetryApplication InsightsAzure Monitor.

Aviso

Etapa 1: desinstalar as bibliotecas do OpenCensus

Desinstale todas as bibliotecas relacionadas ao OpenCensus, incluindo todos os pacotes Pypi que começam com opencensus-*.

pip freeze | grep opencensus | xargs pip uninstall -y

Etapa 2: remover o OpenCensus do seu código

Remova todas as instâncias do SDK do OpenCensus e do exportador do OpenCensus do Azure Monitor do seu código.

Verifique as instruções de importação que começam com opencensus para encontrar todas as integrações, exportadores e instâncias de API/SDK do OpenCensus que devem ser removidas.

A seguir, exemplos de instruções de importação que devem ser removidas.

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.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

from opencensus.ext.azure.log_exporter import AzureLogHandler

Etapa 3: familiarizar-se com as APIs/SDKs do OpenTelemetry Python

A documentação a seguir fornece o conhecimento dos pré-requisitos de APIs/SDKs do OpenTelemetry Python.

Observação

O OpenTelemetry Python e o OpenCensus Python têm diferentes superfícies de API, recursos de coleta automática e instruções de integração.

Etapa 4: configurar a distribuição OpenTelemetry do Azure Monitor

Siga a página de introdução para integrar a distribuição OpenTelemetry do Azure Monitor.

Alterações e limitações

As seguintes alterações e limitações podem ser encontradas ao migrar do OpenCensus para o OpenTelemetry.

Suporte ao Python < 3.7

As soluções de monitoramento baseadas em Python do OpenTelemetry suportam apenas o Python 3.7 e superior, excluindo as versões anteriormente suportadas do Python 2.7, 3.4, 3.5 e 3.6 do OpenCensus. Sugerimos a atualização para os usuários que usam as versões mais antigas do Python, pois, no momento da redação deste documento, essas versões já haviam chegado ao fim da vida útil. Os usuários inflexíveis quanto à não atualização ainda podem utilizar as soluções do OpenTelemetry, mas podem encontrar um comportamento inesperado ou de interrupção que não é suportado. De qualquer forma, a última versão suportada do opencensus-ext-azure sempre existe e ainda funciona com essas versões, mas não estão sendo feitos novos lançamentos para esse projeto.

Configurações

O OpenCensus Python forneceu algumas opções de configuração relacionadas à coleta e exportação de telemetria. Você pode obter as mesmas configurações e muito mais usando as APIs e o SDK do OpenTelemetry Python. A distribuição do Python do OpenTelemetry do Azure Monitor é mais uma loja única para as necessidades de monitoramento mais comuns dos seus aplicativos Python. Como a distribuição encapsula as APIs/SDk do OpenTelemetry, algumas configurações para os casos de uso mais incomuns podem não ser suportadas atualmente pela distribuição. Em vez disso, você pode optar por integrar o exportador do OpenTelemetry do monitor do Azure, que, com as APIs/SDKs do OpenTelemetry, deve ser capaz de atender às suas necessidades de monitoramento. Algumas dessas configurações incluem:

  • Propagadores Personalizados
  • Exemplos Personalizados
  • Adição de processadores extras de span/logs/leitores de métricas

Coesão com o Azure Functions

Para fornecer recursos de rastreamento distribuído para aplicativos Python que chamam outros aplicativos Python em uma função do Azure, o pacote opencensus-extension-azure-functions foi fornecido para permitir um gráfico distribuído conectado.

Atualmente, as soluções do OpenTelemetry do Azure Monitor não suportam esse cenário. Como solução alternativa, você pode propagar manualmente o contexto de rastreamento no seu aplicativo Azure Functions, conforme mostrado no exemplo a seguir.

from opentelemetry.context import attach, detach
from opentelemetry.trace.propagation.tracecontext import \
  TraceContextTextMapPropagator

# Context parameter is provided for the body of the function
def main(req, context):
  functions_current_context = {
    "traceparent": context.trace_context.Traceparent,
    "tracestate": context.trace_context.Tracestate
  }
  parent_context = TraceContextTextMapPropagator().extract(
      carrier=functions_current_context
  )
  token = attach(parent_context)

  ...
  # Function logic
  ...
  detach(token)

Extensões e exportadores

O SDK do OpenCensus ofereceu maneiras de coletar e exportar a telemetria por meio de integrações e exportadores do OpenCensus, respectivamente. No OpenTelemetry, as integrações agora são chamadas de instrumentações, enquanto os exportadores permaneceram com a mesma terminologia. As instrumentações e os exportadores OpenTelemetry Python são um superconjunto do que foi fornecido no OpenCensus, portanto, em termos de cobertura e funcionalidade da biblioteca, as bibliotecas do OpenTelemetry são uma atualização direta. Quanto à distribuição do OpenTelemetry do Azure Monitor, ela vem com algumas das populares instrumentações do OpenTelemetry Python prontas para uso, de modo que nenhum código extra é necessário. A Microsoft suporta totalmente essas instrumentações.

Quanto às outras instrumentações do OpenTelemetry Python que não estão incluídas nessa lista, os usuários ainda podem instrumentá-las manualmente. Entretanto, é importante observar que a estabilidade e o comportamento não são garantidos nem suportados nesses casos. Portanto, use-os de acordo com seus próprios critérios.

Se você quiser sugerir uma biblioteca de instrumentação comunitária para incluirmos na nossa distribuição, publique ou vote positivamente na nossa comunidade de comentários. Para exportadores, a distribuição OpenTelemetry do Azure Monitor vem com o exportador do OpenTelemetry do Azure Monitor. Se quiser usar outros exportadores também, você pode usá-los com a distribuição, como neste exemplo.

TelemetryProcessors

Os processadores de telemetria do OpenCensus Python são um mecanismo poderoso que permite aos usuários modificar suas telemetrias antes de serem enviadas ao exportador. Não existe o conceito de TelemetryProcessors no mundo do OpenTelemetry, mas existem APIs e classes que você pode usar para replicar o mesmo comportamento.

Definição do nome da função na nuvem e da instância da função na nuvem

Siga as instruções aqui para saber como definir o nome da função na nuvem e a instância da função na nuvem para sua telemetria. A distribuição OpenTelemetry do Azure Monitor obtém automaticamente os valores das variáveis de ambiente e preenche os respectivos campos.

Modificação de spans com SpanProcessors

em breve.

Modificação das métricas com Exibições

em breve.

Contadores de desempenho

O exportador OpenCensus Python do Azure Monitor coletou automaticamente as métricas relacionadas ao sistema e ao desempenho chamadas de contadores de desempenho. Essas métricas aparecem em performanceCounters na sua instância do Application Insights. No OpenTelemetry, não enviamos mais essas métricas explicitamente para performanceCounters. As métricas relacionadas às solicitações de entrada/saída podem ser encontradas nas métricas padrão. Se quiser que o OpenTelemetry colete automaticamente métricas relacionadas ao sistema, você pode usar as métricas experimentais do sistema de instrumentação, contribuídas pela comunidade do OpenTelemetry Python. Esse pacote é experimental e não é suportado oficialmente pela Microsoft.

Solução de problemas

Não está funcionando? Confira a página de solução de problemas do ASP.NET Core.

Suporte

Selecione uma guia para o idioma de sua escolha para descobrir as opções de suporte.

Comentários sobre o OpenTelemetry

Para fornecer comentários: