Exportador do Microsoft OpenTelemetry para o Azure Monitor

O exportador do Azure Monitor permite exportar dados utilizando o SDK do OpenTelemetry e enviar dados de telemetria para o Azure Monitor para aplicativos escritos em Python.

Código-fonte | Pacote (PyPi) | Documentação | de referência da APIDocumentação do produto | Amostras | Changelog

Introdução

Instalar o pacote

Instale o exportador do Microsoft OpenTelemetry para o Azure Monitor com pip:

pip install azure-monitor-opentelemetry-exporter --pre

Pré-requisitos

Para usar esse pacote, você deve ter:

• Assinatura do Azure – Criar uma conta gratuita
• Azure Monitor – Como usar o Application Insights
• SDK do OpenTelemetry – SDK do OpenTelemetry para Python
• Python 3.7 ou posterior – Instalar o Python

Instancie o cliente

A interação com o exportador do Azure Monitor começa com uma instância da AzureMonitorTraceExporter classe para rastreamento distribuído, AzureMonitorLogExporter para registro em log e AzureMonitorMetricExporter para métricas. Você precisará de um connection_string para instanciar o objeto. Encontre os exemplos vinculados abaixo para demonstração sobre como construir o exportador usando um cadeia de conexão.

Registro em log (experimental)

OBSERVAÇÃO: o sinal de registro em log para o AzureMonitorLogExporter está atualmente em um estado EXPERIMENTAL. Possíveis alterações interruptivas podem ocorrer no futuro.

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter
exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

Métricas

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

Rastreamento

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

Você também pode instanciar o exportador diretamente por meio do construtor. Nesse caso, o cadeia de conexão será populado automaticamente da APPLICATIONINSIGHTS_CONNECTION_STRING variável de ambiente.

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter
exporter = AzureMonitorLogExporter()

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter()

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter()

Principais conceitos

Alguns dos principais conceitos para o exportador do Azure Monitor incluem:

• OpenTelemetry: OpenTelemetry é um conjunto de bibliotecas usadas para coletar e exportar dados de telemetria (métricas, logs e rastreamentos) para análise para entender o desempenho e o comportamento do software.

• Instrumentação: a capacidade de chamar a API OpenTelemetry diretamente por qualquer aplicativo é facilitada pela instrumentação. Uma biblioteca que habilita a observabilidade do OpenTelemetry para outra biblioteca é chamada de biblioteca de instrumentação.

• Log: log refere-se à captura de log, exceção e eventos.

• LogRecord: representa um registro de log emitido de uma biblioteca de log com suporte.

• Agente: converte um LogRecord em um legível LogDatae será enviado por push por meio do SDK a ser exportado.

• Provedor de Agente: fornece um Logger para a biblioteca de instrumentação fornecida.

• LogRecordProcessor: interface para conectar a ação de emissão de registro de log.

• LoggingHandler: uma classe de manipulador que grava registros de registro em log no formato OpenTelemetry da biblioteca padrão do Python logging .

• AzureMonitorLogExporter: essa é a classe inicializada para enviar telemetria relacionada ao registro em log para o Azure Monitor.

• Métrica: Metric refere-se ao registro de medidas brutas com agregação predefinida e conjuntos de atributos por um período no tempo.

• Medida: representa um ponto de dados registrado em um ponto no tempo.

• Instrumento: instrumentos são usados para relatar Measurements.

• Medidor: o Meter é responsável por criar Instruments.

• Provedor de Medidor: fornece um Meter para a biblioteca de instrumentação fornecida.

• Leitor de Métrica: um objeto de implementação do SDK que fornece os aspectos configuráveis comuns do SDK de Métricas do OpenTelemetry, como coleção, liberação e desligamento.

• AzureMonitorMetricExporter: essa é a classe inicializada para enviar telemetria relacionada à métrica para o Azure Monitor.

• Rastreamento: o rastreamento refere-se ao rastreamento distribuído. Um rastreamento distribuído é um conjunto de eventos, disparados como resultado de uma única operação lógica, consolidado em vários componentes de um aplicativo. Em particular, um Rastreamento pode ser considerado como um DAG (grafo acíclico direcionado) de intervalos, em que as bordas entre intervalos são definidas como relação pai/filho.

• Span: representa uma única operação em um Trace. Pode ser aninhado para formar uma árvore de rastreamento. Cada rastreamento contém um intervalo raiz, que normalmente descreve toda a operação e, opcionalmente, um minério a mais sub-intervalos para suas sub-operações.

• Tracer: responsável pela criação Spande s.

• Provedor de rastreamento: fornece um Tracer para uso pela biblioteca de instrumentação fornecida.

• Processador de span: um processador de span permite ganchos para invocações de método inicial e final do Span SDK. Siga o link para obter mais informações.

• AzureMonitorTraceExporter: essa é a classe inicializada para enviar telemetria relacionada ao rastreamento para o Azure Monitor.

• Amostragem: a amostragem é um mecanismo para controlar o ruído e a sobrecarga introduzidos pelo OpenTelemetry, reduzindo o número de amostras de rastreamentos coletados e enviados para o back-end.

• ApplicationInsightsSampler: amostragem específica do Application Insights usada para amostragem consistente em SDKs do Application Insights e SDKs baseados em OpenTelemetry enviando dados para o Application Insights. Este sampler DEVE ser usado sempre que AzureMonitorTraceExporter for usado.

Para obter mais informações sobre esses recursos, consulte O que é o Azure Monitor?.

Configuração

Todas as opções de configuração podem ser passadas por meio dos construtores de exportadores por meio kwargsde . Veja abaixo uma lista de opções configuráveis.

• connection_string: o cadeia de conexão usado para o recurso do Application Insights.
• disable_offline_storage: valor booliano para determinar se deseja desabilitar o armazenamento de registros de telemetria com falha para repetição. Assume o padrão de False.
• storage_directory: diretório de armazenamento no qual armazenar arquivos de repetição. Assume o padrão de <tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.
• credential: credencial de token, como ManagedIdentityCredential ou ClientSecretCredential, usada para autenticação do AAD (Azure Active Directory). Assume o valor padrão de Nenhum. Consulte exemplos para obter exemplos.

Exemplos

Registro em log (experimental)

OBSERVAÇÃO: o sinal de registro em log para o AzureMonitorLogExporter está atualmente em um estado EXPERIMENTAL. Possíveis alterações interruptivas podem ocorrer no futuro.

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns, incluindo:

• Exportando um registro de log
• Exportando registro de log correlacionado
• Exportando o registro de log com propriedades personalizadas
• Exportando um registro de log de exceções

Examine o SDK de Log do OpenTelemetry para saber como usar componentes do OpenTelemetry para coletar logs.

Exportar log de Olá, Mundo

"""
An example to show an application using Opentelemetry logging sdk. Logging calls to the standard Python
logging library are tracked and telemetry is exported to application insights with the AzureMonitorLogExporter.
"""
import os
import logging

from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
    set_logger_provider,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
handler = LoggingHandler()

# Attach LoggingHandler to root logger
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.NOTSET)

logger = logging.getLogger(__name__)

logger.warning("Hello World!")

# Telemetry records are flushed automatically upon application exit
# If you would like to flush records manually yourself, you can call force_flush()
logger_provider.force_flush()

Exportar log correlacionado

"""
An example showing how to include context correlation information in logging telemetry.
"""
import os
import logging

from opentelemetry import trace
from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
    set_logger_provider,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.trace import TracerProvider

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
handler = LoggingHandler()

# Attach LoggingHandler to root logger
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.NOTSET)

logger = logging.getLogger(__name__)

logger.info("INFO: Outside of span")
with tracer.start_as_current_span("foo"):
    logger.warning("WARNING: Inside of span")
logger.error("ERROR: After span")

Exportar log de propriedades personalizadas

"""
An example showing how to add custom properties to logging telemetry.
"""
import os
import logging

from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
    set_logger_provider,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
handler = LoggingHandler()

# Attach LoggingHandler to root logger
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.NOTSET)

logger = logging.getLogger(__name__)

# Custom properties
logger.debug("DEBUG: Debug with properties", extra={"debug": "true"})

Exportar log de exceções

"""
An example showing how to export exception telemetry using the AzureMonitorLogExporter.
"""
import os
import logging

from opentelemetry._logs import (
    get_logger_provider,
    set_logger_provider,
)
from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

set_logger_provider(LoggerProvider())
exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
get_logger_provider().add_log_record_processor(BatchLogRecordProcessor(exporter))

# Attach LoggingHandler to namespaced logger
handler = LoggingHandler()
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.NOTSET)

# The following code will generate two pieces of exception telemetry
# that are identical in nature
try:
    val = 1 / 0
    print(val)
except ZeroDivisionError:
    logger.exception("Error: Division by zero")

try:
    val = 1 / 0
    print(val)
except ZeroDivisionError:
    logger.error("Error: Division by zero", stack_info=True, exc_info=True)

Métricas

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns, incluindo:

• Usando diferentes instrumentos de métrica
• Personalizando métricas geradas com exibições
• Instrumentos de gravação com atributos

Examine o SDK de Métricas do OpenTelemetry para saber como usar componentes do OpenTelemetry para coletar métricas.

Uso do instrumento de métrica

"""
An example to show an application using all instruments in the OpenTelemetry SDK. Metrics created
and recorded using the sdk are tracked and telemetry is exported to application insights with the
AzureMonitorMetricsExporter.
"""
import os
from typing import Iterable

from opentelemetry import metrics
from opentelemetry.metrics import CallbackOptions, Observation
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

# Create a namespaced meter
meter = metrics.get_meter_provider().get_meter("sample")

# Callback functions for observable instruments
def observable_counter_func(options: CallbackOptions) -> Iterable[Observation]:
    yield Observation(1, {})


def observable_up_down_counter_func(
    options: CallbackOptions,
) -> Iterable[Observation]:
    yield Observation(-10, {})


def observable_gauge_func(options: CallbackOptions) -> Iterable[Observation]:
    yield Observation(9, {})

# Counter
counter = meter.create_counter("counter")
counter.add(1)

# Async Counter
observable_counter = meter.create_observable_counter(
    "observable_counter", [observable_counter_func]
)

# UpDownCounter
up_down_counter = meter.create_up_down_counter("up_down_counter")
up_down_counter.add(1)
up_down_counter.add(-5)

# Async UpDownCounter
observable_up_down_counter = meter.create_observable_up_down_counter(
    "observable_up_down_counter", [observable_up_down_counter_func]
)

# Histogram
histogram = meter.create_histogram("histogram")
histogram.record(99.9)

# Async Gauge
gauge = meter.create_observable_gauge("gauge", [observable_gauge_func])

# Upon application exit, one last collection is made and telemetry records are
# flushed automatically. # If you would like to flush records manually yourself,
# you can call force_flush()
meter_provider.force_flush()

Exibições personalizadas de métrica

"""
This example shows how to customize the metrics that are output by the SDK using Views. Metrics created
and recorded using the sdk are tracked and telemetry is exported to application insights with the
AzureMonitorMetricsExporter.
"""
import os

from opentelemetry import metrics
from opentelemetry.sdk.metrics import Counter, MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.metrics.view import View

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter.from_connection_string(
    os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
# Create a view matching the counter instrument `my.counter`
# and configure the new name `my.counter.total` for the result metrics stream
change_metric_name_view = View(
    instrument_type=Counter,
    instrument_name="my.counter",
    name="my.counter.total",
)

reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
provider = MeterProvider(
    metric_readers=[
        reader,
    ],
    views=[
        change_metric_name_view,
    ],
)
metrics.set_meter_provider(provider)

meter = metrics.get_meter_provider().get_meter("view-name-change")
my_counter = meter.create_counter("my.counter")
my_counter.add(100)

Mais exemplos com o SDK de métricas Views podem ser encontrados aqui.

Atributos de registro de métrica

"""
An example to show an application using different attributes with instruments in the OpenTelemetry SDK.
Metrics created and recorded using the sdk are tracked and telemetry is exported to application insights
with the AzureMonitorMetricsExporter.
"""
import os

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter.from_connection_string(
    os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

attribute_set1 = {
    "key1": "val1"
}
attribute_set2 = {
    "key2": "val2"
}
large_attribute_set = {}
for i in range(20):
    key = "key{}".format(i)
    val = "val{}".format(i)
    large_attribute_set[key] = val

meter = metrics.get_meter_provider().get_meter("sample")

# Counter
counter = meter.create_counter("attr1_counter")
counter.add(1, attribute_set1)

# Counter2
counter2 = meter.create_counter("attr2_counter")
counter2.add(10, attribute_set1)
counter2.add(30, attribute_set2)

# Counter3
counter3 = meter.create_counter("large_attr_counter")
counter3.add(100, attribute_set1)
counter3.add(200, large_attribute_set)

Rastreamento

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns, incluindo:

• Exportando um intervalo personalizado
• Usando uma instrumentação para acompanhar uma biblioteca
• Habilitar a amostragem para limitar a quantidade de telemetria enviada

Examine o SDK de Rastreamento do OpenTelemetry para saber como usar componentes do OpenTelemetry para coletar logs.

Exportar rastreamento de Olá, Mundo

"""
An example to show an application using Opentelemetry tracing api and sdk. Custom dependencies are
tracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter.
"""
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

tracer_provider = TracerProvider()
trace.set_tracer_provider(tracer_provider)
tracer = trace.get_tracer(__name__)
# This is the exporter that sends data to Application Insights
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

with tracer.start_as_current_span("hello"):
    print("Hello, World!")

# Telemetry records are flushed automatically upon application exit
# If you would like to flush records manually yourself, you can call force_flush()
tracer_provider.force_flush()

Instrumentação com biblioteca de solicitações

O OpenTelemetry também dá suporte a várias instrumentações que permitem instrumentar com bibliotecas de terceiros.

Para obter uma lista de instrumentações disponíveis no OpenTelemetry, visite a documentação contrib.

Este exemplo mostra como instrumentar com a biblioteca de solicitações .

• Instale o pacote de instrumentação de solicitações usando pip install opentelemetry-instrumentation-requests.

"""
An example to show an application instrumented with the OpenTelemetry requests instrumentation.
Calls made with the requests library will be automatically tracked and telemetry is exported to 
application insights with the AzureMonitorTraceExporter.
See more info on the requests instrumentation here:
https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests
"""
import os
import requests
from opentelemetry import trace
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

# This line causes your calls made with the requests library to be tracked.
RequestsInstrumentor().instrument()

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

# This request will be traced
response = requests.get(url="https://azure.microsoft.com/")

Habilitando a amostragem

Você pode habilitar a amostragem para limitar a quantidade de registros de telemetria recebidos. Para habilitar a amostragem correta no Application Insights, use o ApplicationInsightsSampler conforme mostrado abaixo.

"""
An example to show an application using the ApplicationInsightsSampler to enable sampling for your telemetry.
Specify a sampling rate for the sampler to limit the amount of telemetry records you receive. Custom dependencies
 are tracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter.
"""
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import (
    ApplicationInsightsSampler,
    AzureMonitorTraceExporter,
)

# Sampler expects a sample rate of between 0 and 1 inclusive
# A rate of 0.75 means approximately 75% of your telemetry will be sent
sampler = ApplicationInsightsSampler(0.75)
trace.set_tracer_provider(TracerProvider(sampler=sampler))
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

for i in range(100):
    # Approximately 25% of these spans should be sampled out
    with tracer.start_as_current_span("hello"):
        print("Hello, World!")

Comportamento de liberação/desligamento

Para todos os aplicativos configurados com o SDK do OpenTelemetry e exportadores do Azure Monitor, a telemetria é liberada automaticamente após a saída do aplicativo. Observe que isso não inclui quando o aplicativo termina abruptamente ou falha devido a uma exceção não capturada.

Solução de problemas

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

Próximas etapas

Mais códigos de exemplo

Encontre mais exemplos no diretório de exemplos que demonstram cenários comuns.

Documentação adicional

Para obter uma documentação mais abrangente sobre o serviço do Azure Monitor, consulte a documentação do Azure Monitor sobre docs.microsoft.com.

Para obter uma visão geral detalhada do OpenTelemetry, visite a página de visão geral .

Para obter a documentação oficial do OpenTelemetry Python e como habilitar outros cenários de telemetria, visite o site oficial do OpenTelemetry.

Para obter mais informações sobre a Distribuição opentelemetry do Azure Monitor, que é um pacote de componentes úteis e pré-montados (um deles sendo esse pacote atual) que habilita cenários de telemetria com o Azure Monitor, visite o LEIAME.

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.