Condividi tramite

Libreria client di distribuzione Opentelemetry di Monitoraggio di Azure per Python - versione 1.1.1

  • Articolo

La distribuzione di Monitoraggio di Azure di Opentelemetry Python offre più componenti installabili disponibili per una soluzione di monitoraggio di Monitoraggio di Azure Opentelemetry. Consente di instrumentare le applicazioni Python per acquisire e segnalare i dati di telemetria a Monitoraggio di Azure tramite gli strumenti di esportazione di Monitoraggio di Azure.

Questa distribuzione installa automaticamente le librerie seguenti:

Strumentazioni ufficialmente supportate

Le strumentazioni OpenTelemetry consentono la raccolta automatica di richieste inviate dalle librerie instrumentate sottostanti. Di seguito è riportato un elenco di strumentazioni OpenTelemetry incluse nella distribuzione di Monitoraggio di Azure. Queste strumentazioni sono abilitate per impostazione predefinita. Per informazioni su come rifiutare esplicitamente queste strumentazioni, vedere la sezione Utilizzo di seguito.

Strumentazione Nome della libreria supportato Versioni supportate
Azure Core Tracing OpenTelemetry azure_sdk
Strumentazione Django OpenTelemetry Django Link
Strumentazione FastApi OpenTelemetry fastapi Link
Strumentazione Flask OpenTelemetry Flask Link
Strumentazione Psycopg2 OpenTelemetry psycopg2 Link
Strumentazione richieste OpenTelemetry requests Link
Strumentazione URLLib di OpenTelemetry urllib Tutti
Strumentazione di OpenTelemetry UrlLib3 urllib3 Link

Se si vuole aggiungere il supporto per un'altra strumentazione OpenTelemetry, inviare una richiesta di funzionalità. Nel frattempo, è possibile usare manualmente la strumentazione OpenTelemetry tramite LE API (ad esempio instrument()) nel codice. Per un esempio, vedere questo esempio.

Concetti chiave

Questo pacchetto aggrega una serie di componenti OpenTelemetry e Monitoraggio di Azure per abilitare la raccolta e l'invio di dati di telemetria a Monitoraggio di Azure. Per la strumentazione MANUAL, usare la configure_azure_monitor funzione . La strumentazione AUTOMATICA non è ancora supportata.

Gli strumenti di esportazione OpenTelemetry di Monitoraggio di Azure sono i componenti principali per eseguire questa operazione. Sarà possibile usare gli strumenti di esportazione e le relative API direttamente tramite questo pacchetto. Per informazioni sul funzionamento dei componenti openTelemetry e Monitoraggio di Azure per abilitare la raccolta e l'esportazione dei dati di telemetria, vedere la documentazione dell'utilità di esportazione.

Attualmente, tutte le strumentazioni disponibili in OpenTelemetry si trovano in uno stato beta, ovvero non sono stabili e potrebbero avere modifiche di rilievo in futuro. Si stanno facendo sforzi per spingere questi verso uno stato più stabile.

Introduzione

Prerequisiti

Per usare questo pacchetto, è necessario disporre di:

Installare il pacchetto

Installare la distribuzione Opentelemetry di Monitoraggio di Azure con pip:

pip install azure-monitor-opentelemetry

Utilizzo

È possibile usare configure_azure_monitor per configurare la strumentazione per l'app in Monitoraggio di Azure. configure_azure_monitor supporta gli argomenti facoltativi seguenti. Tutti i parametri pass-in hanno la priorità su tutte le variabili di ambiente correlate.

Parametro Descrizione Variabile di ambiente
connection_string Il stringa di connessione per la risorsa di Application Insights. Il stringa di connessione verrà popolato automaticamente dalla APPLICATIONINSIGHTS_CONNECTION_STRING variabile di ambiente se non viene passato in modo esplicito. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name Nome del logger Python in cui vengono raccolti i dati di telemetria. N/A
instrumentation_options Dizionario annidato che determina quali strumentazioni abilitare o disabilitare. Le strumentazioni vengono definite dai relativi nomi di libreria. Ad esempio, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} disabiliterà La traccia di Base di Azure e la strumentazione Flask, ma lasceranno Django e le altre strumentazioni predefinite abilitate. La OTEL_PYTHON_DISABLED_INSTRUMENTATIONS variabile di ambiente illustrata di seguito può essere usata anche per disabilitare le strumentazioni. N/A

È possibile configurare ulteriormente con le variabili di ambiente OpenTelemetry , ad esempio: | Variabile di ambiente | Descrizione | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Specifica la risorsa OpenTelemetry associata all'applicazione. | | OTEL_LOGS_EXPORTER | Se impostato su None, disabilita la raccolta e l'esportazione dei dati di telemetria di registrazione. | | OTEL_METRICS_EXPORTER | Se impostato su None, disabilita la raccolta e l'esportazione dei dati di telemetria delle metriche. | | OTEL_TRACES_EXPORTER | Se impostato su None, disabilita la raccolta e l'esportazione dei dati di telemetria di traccia distribuiti. | | OTEL_BLRP_SCHEDULE_DELAY | Specifica l'intervallo di esportazione della registrazione in millisecondi. Il valore predefinito è 5000. | | OTEL_BSP_SCHEDULE_DELAY | Specifica l'intervallo di esportazione della traccia distribuita in millisecondi. Il valore predefinito è 5000. | | OTEL_TRACES_SAMPLER_ARG | Specifica il rapporto tra i dati di telemetria di traccia distribuita da campionare. I valori accettati sono compresi nell'intervallo [0,1]. Il valore predefinito è 1.0, ovvero non viene campionata alcuna telemetria. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Specifica quale delle strumentazioni supportate da disabilitare. Le strumentazioni disabilitate non verranno instrumentate come parte di configure_azure_monitor. Tuttavia, possono comunque essere instrumentati manualmente con instrument() direttamente. Accetta un elenco delimitato da virgole di nomi di librerie minuscole. Ad esempio, impostare su "psycopg2,fastapi" per disabilitare le strumentazioni Psycopg2 e FastAPI. L'impostazione predefinita è un elenco vuoto, abilitando tutte le strumentazioni supportate. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Variabile di ambiente OpenTelemetry sperimentale usata per specificare i rilevatori di risorse da usare per generare attributi di risorsa. Si tratta di una funzionalità sperimentale e il nome di questa variabile e il relativo comportamento possono cambiare in modo non compatibile con le versioni precedenti. L'impostazione predefinita è "azure_app_service,azure_vm" per abilitare i rilevatori di risorse di Azure per Servizio app di Azure e macchina virtuale di Azure. Per aggiungere o rimuovere rilevatori di risorse specifici, impostare di conseguenza la variabile di ambiente. Per altre informazioni, vedere la documentazione di Rilevamento risorse Python openTelemetry . |

Configurazioni di OpenTelemetry Exporter di Monitoraggio di Azure

È possibile passare i parametri di configurazione dell'utilità di esportazione OpenTelemetry di Monitoraggio di Azure direttamente in configure_azure_monitor. Vedere altre configurazioni correlate all'esportazione qui.

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

Esempio

Gli esempi sono disponibili qui per illustrare come usare le opzioni di configurazione precedenti.

Monitoraggio in Funzioni di Azure

Correlazione delle tracce

Le richieste in ingresso rilevate provenienti dall'applicazione Python ospitata in Funzioni di Azure non verranno correlate automaticamente con i dati di telemetria rilevati al suo interno. È possibile ottenere manualmente la correlazione di traccia estraendolo TraceContext direttamente, come illustrato di seguito:


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),
   ):
      ...

Problemi di registrazione

Il ruolo di lavoro Funzioni di Azure invia i dati di telemetria di registrazione senza l'uso dell'SDK di Monitoraggio di Azure (la chiamata a configure_azure_monitor()). In questo modo è possibile che si verifichino voci di telemetria duplicate durante l'invio dei dati di telemetria di registrazione. Si consiglia ai clienti di usare esclusivamente l'SDK perché consentirà dati di telemetria e funzionalità molto più avanzati rispetto all'uso di quello integrato fornito dal ruolo di lavoro Funzioni di Azure. È possibile disattivare il logger di telemetria Funzioni di Azure cancellando l'elenco dei gestori del logger.

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

Assicurarsi di chiamare i logger precedenti o la chiamata a configure_azure_monitor() è configurata.

È anche possibile disabilitare la registrazione tramite Funzioni di Azure configurazione.

v2.x+

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

v1.x

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

Risoluzione dei problemi

L'utilità di esportazione genera eccezioni definite in Azure Core.

Passaggi successivi

Per altre informazioni, vedere la documentazione .

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Documentazione aggiuntiva