Exportador do Microsoft OpenTelemetry para o Azure Monitor

O exportador do Azure Monitor permite-lhe exportar dados que utilizam o SDK OpenTelemetry e enviar dados telemétricos para o Azure Monitor para aplicações escritas em Python.

Código fonte | Pacote (PyPi) | Documentação | de referência da APIDocumentação do | produtoExemplos | Caixa de alterações

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 utilizar este pacote, tem de ter:

• Subscrição do Azure – Criar uma conta gratuita
• Azure Monitor – Como utilizar o Application Insights
• SDK OpenTelemetry – SDK OpenTelemetry para Python
• Python 3.7 ou posterior – Instalar o Python

Instanciar o cliente

A interação com o exportador do Azure Monitor começa com uma instância da classe para rastreio AzureMonitorTraceExporter distribuído, AzureMonitorLogExporter para registo e AzureMonitorMetricExporter para métricas. Precisará de uma connection_string para instanciar o objeto. Veja os exemplos associados abaixo para demonstração sobre como construir o exportador com um cadeia de ligação.

Registo (experimental)

NOTA: o sinal de registo do AzureMonitorLogExporter está atualmente num estado EXPERIMENTAL. Poderão ocorrer possíveis alterações interruptivas 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"]
)

Rastreio

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

Também pode instanciar o exportador diretamente através do construtor. Neste caso, o cadeia de ligação será preenchido automaticamente a APPLICATIONINSIGHTS_CONNECTION_STRING partir da 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()

Conceitos-chave

Alguns dos principais conceitos do exportador do Azure Monitor incluem:

• OpenTelemetry: o OpenTelemetry é um conjunto de bibliotecas utilizadas para recolher e exportar dados telemétricos (métricas, registos e rastreios) para análise para compreender o desempenho e o comportamento do software.

• Instrumentação: a capacidade de chamar a API OpenTelemetry diretamente por qualquer aplicação é facilitada pela instrumentação. Uma biblioteca que permite a observabilidade openTelemetry para outra biblioteca é denominada Biblioteca de Instrumentação.

• Registo: o registo refere-se à captura de registos, exceções e eventos.

• LogRecord: representa um registo emitido a partir de uma biblioteca de registos suportada.

• Logger: converte um LogRecord num legível LogDatae será emitido através do SDK para ser exportado.

• Fornecedor de Logger: fornece uma Logger para a biblioteca de instrumentação especificada.

• LogRecordProcessor: interface para ligar a ação de emissão de registos.

• LoggingHandler: uma classe de processador que escreve registos no formato OpenTelemetry a partir da biblioteca Python logging padrão.

• AzureMonitorLogExporter: esta é a classe que é inicializada para enviar telemetria relacionada com o registo para o Azure Monitor.

• Métrica: Metric refere-se ao registo de medições não processadas com agregação predefinida e conjuntos de atributos para um período de tempo.

• Medição: representa um ponto de dados registado num ponto anterior no tempo.

• Instrumento: os instrumentos são utilizados para comunicar Measurements.

• Medidor: o Meter é responsável pela criação de Instruments.

• Fornecedor de Medidores: fornece uma Meter para a biblioteca de instrumentação especificada.

• Leitor de Métricas: um objeto de implementação do SDK que fornece os aspetos configuráveis comuns do SDK de Métricas openTelemetry, como a recolha, a descarga e o encerramento.

• AzureMonitorMetricExporter: esta é a classe que é inicializada para enviar telemetria relacionada com métricas para o Azure Monitor.

• Rastreio: o rastreio refere-se ao rastreio distribuído. Um rastreio distribuído é um conjunto de eventos, acionado como resultado de uma única operação lógica, consolidada em vários componentes de uma aplicação. Em particular, um Rastreio pode ser considerado como um grafo acíclico dirigido (DAG) de Spans, onde as arestas entre Spans são definidas como uma relação principal/subordinada.

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

• Tracer: responsável pela criação de Spans.

• Fornecedor de Rastreio: fornece uma Tracer para utilização pela biblioteca de instrumentação especificada.

• Processador Span: um processador span permite hooks para invocações do método de início e de fim do Span SDK. Siga a ligação para obter mais informações.

• AzureMonitorTraceExporter: esta é a classe que é inicializada para enviar telemetria relacionada com o rastreio para o Azure Monitor.

• Amostragem: a amostragem é um mecanismo para controlar o ruído e a sobrecarga introduzidos pela OpenTelemetry ao reduzir o número de amostras de rastreios recolhidos e enviados para o back-end.

• ApplicationInsightsSampler: exemplo específico do Application Insights utilizado para amostragem consistente em SDKs do Application Insights e SDKs baseados em OpenTelemetry a enviar dados para o Application Insights. Este sampler tem de ser utilizado sempre que AzureMonitorTraceExporter for utilizado.

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

Configuração

Todas as opções de configuração podem ser transmitidas através dos construtores dos exportadores através do kwargs. Segue-se uma lista de opções configuráveis.

• connection_string: a cadeia de ligação utilizada para o recurso do Application Insights.
• disable_offline_storage: valor booleano para determinar se pretende desativar o armazenamento de registos de telemetria falhados para repetição. A predefinição é False.
• storage_directory: diretório de armazenamento no qual armazenar ficheiros de repetição. A predefinição é <tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.
• credential: credencial de token, como ManagedIdentityCredential ou ClientSecretCredential, utilizada para autenticação do Azure Active Directory (AAD). A predefinição é Nenhuma. Veja exemplos para obter exemplos.

Exemplos

Registo (experimental)

NOTA: o sinal de registo do AzureMonitorLogExporter está atualmente num estado EXPERIMENTAL. Poderão ocorrer possíveis alterações interruptivas no futuro.

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns, incluindo:

• Exportar um registo
• Exportar registo correlacionado
• Exportar o registo com propriedades personalizadas
• Exportar um registo de exceções

Reveja o SDK de Registo openTelemetry para saber como utilizar componentes openTelemetry para recolher registos.

Exportar registo de Hello World

"""
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 Registo 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 Registo 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"})

Registo de Exceções de Exportação

"""
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 secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns, incluindo:

• Utilizar diferentes instrumentos métricos
• Personalizar métricas saídas com vistas
• Instrumentos de gravação com atributos

Reveja o SDK de Métricas openTelemetry para saber como utilizar componentes openTelemetry para recolher métricas.

Utilização 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()

Vistas personalizadas de métricas

"""
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)

Pode encontrar mais exemplos com o SDK de métricas Viewsaqui.

Atributos de registo de métricas

"""
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)

Rastreio

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns, incluindo:

• Exportar um intervalo personalizado
• Utilizar uma instrumentação para controlar uma biblioteca
• Permitir a amostragem para limitar a quantidade de telemetria enviada

Reveja o SDK de Rastreio openTelemetry para saber como utilizar componentes openTelemetry para recolher registos.

Exportar rastreio de Hello World

"""
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 pedidos

O OpenTelemetry também suporta 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 pedidos .

• Instale o pacote de instrumentação de pedidos com o 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/")

Ativar a amostragem

Pode ativar a amostragem para limitar a quantidade de registos de telemetria que recebe. Para ativar a amostragem correta no Application Insights, utilize 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 da descarga/encerramento

Para todas as aplicações configuradas com o SDK OpenTelemetry e os exportadores do Azure Monitor, a telemetria é removida automaticamente após a saída da aplicação. Tenha em atenção que isto não inclui quando a aplicação termina abruptamente ou falha devido a uma exceção não identificada.

Resolução de problemas

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

Passos seguintes

Mais código de exemplo

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

Documentação adicional

Para obter documentação mais extensa sobre o serviço Azure Monitor, veja a documentação do Azure Monitor sobre docs.microsoft.com.

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

Para obter a documentação oficial do OpenTelemetry Python e como ativar 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 conjunto de componentes pré-montados úteis (um deles é este pacote atual) que permite cenários de telemetria com o Azure Monitor, visite o README.

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.