Questa pagina è stata tradotta dall'API Cloud Translation.

Genera tracce e metriche con Python

Questo documento descrive come modificare un'app Python per raccogliere dati su tracce e metriche utilizzando il framework open source OpenTelemetry e come scrivere log JSON strutturati in output standard. Il presente documento fornisce inoltre su un'app Python di esempio che puoi installare ed eseguire. L'app utilizza il framework web Flask ed è configurato per generare metriche, per le tracce e i log.

Per scoprire di più sulla misurazione, consulta i seguenti documenti:

Informazioni sulla strumentazione manuale e automatica

Per questo linguaggio, OpenTelemetry definisce la strumentazione automatica come la pratica di raccogliere la telemetria da librerie e framework senza apportare modifiche al codice. Tuttavia, puoi installare i moduli e impostare le variabili di ambiente.

Questo documento non descrive la misurazione automatica. Per informazioni su questo argomento, consulta Strumentazione automatica per Python.

Per informazioni generali, vedi OpenTelemetry Instrumentation per Python.

Prima di iniziare

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Instrumenta l'app per raccogliere tracce, metriche e log

Per eseguire l'instrumentazione dell'app in modo da raccogliere dati sulle metriche e sulle tracce e scrivere JSON strutturato nello standard out, svolgi i seguenti passaggi come descritto nelle sezioni successive di questo documento:

Configurare OpenTelemetry
Configurare il logging strutturato

Configurare OpenTelemetry

Questa app di esempio è configurata per utilizzare l'SDK Python OpenTelemetry per esportare tracce e metriche utilizzando il protocollo OTLP. Per impostazione predefinita, l'SDK Python di OpenTelemetry utilizza il formato W3C Trace Context per propagare il contesto traccia, il che garantisce che gli span abbiano la relazione padre-figlio corretta all'interno di una traccia.

Il seguente esempio di codice illustra un modulo Python per configurare OpenTelemetry. Per visualizzare l'anteprima completa, fai clic su Altro, quindi seleziona Visualizza su GitHub.

resource = Resource.create(attributes={
    # Use the PID as the service.instance.id to avoid duplicate timeseries
    # from different Gunicorn worker processes.
    SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
})

traceProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter())
traceProvider.add_span_processor(processor)
trace.set_tracer_provider(traceProvider)

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter()
)
meterProvider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(meterProvider)

L'app Flask si basa su Gunicorn per gestire le richieste HTTP seguendo i consigli della guida Eseguire il deployment in produzione di Flask. Gunicorn avvia più copie dell'app in processi di lavoro indipendenti per aumentare il throughput. garantire che le metriche dei processi worker non siano in conflitto consigliamo che ogni processo worker imposti un valore unico per Attributo risorsa service.instance.id. Un modo per farlo è includere ID di processo in service.instance.id. Per ulteriori informazioni, consulta Collisioni delle serie temporali.

Per ulteriori informazioni e opzioni di configurazione, consulta la strumentazione di OpenTelemetry per Python.

Configura il logging strutturato

Per scrivere log strutturati collegati alle tracce, configura l'app in output di log in formato JSON in output standard con chiavi contenenti traccia informazioni. Il seguente esempio di codice illustra come configurare la raccolta standard logging per generare log strutturati JSON utilizzando la raccolta python-json-logger e come utilizzare il pacchetto opentelemetry-instrumentation-logging per includere informazioni sulla traccia.

LoggingInstrumentor().instrument()

logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
    rename_fields={
        "levelname": "severity",
        "asctime": "timestamp",
        "otelTraceID": "logging.googleapis.com/trace",
        "otelSpanID": "logging.googleapis.com/spanId",
        "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)
logHandler.setFormatter(formatter)
logging.basicConfig(
    level=logging.INFO,
    handlers=[logHandler],
)

La configurazione precedente estrae le informazioni sull'intervallo attivo dal messaggio di log, quindi aggiunge queste informazioni come attributi al file JSON strutturato log. Questi attributi possono essere utilizzati per correlare un log con una traccia:

logging.googleapis.com/trace: nome risorsa della traccia associata a la voce di log.
logging.googleapis.com/spanId: l'ID intervallo con la traccia che è associati alla voce di log.
logging.googleapis.com/trace_sampled: il valore di questo campo deve essere true o false.

Per saperne di più su questi campi, consulta la LogEntry alla struttura del centro di costo.

Esegui un'app di esempio configurata per raccogliere dati di telemetria

L'app di esempio utilizza formati indipendenti dal fornitore, tra cui JSON per i log e OTLP per ottenere metriche e tracce. La telemetria dell'app viene inoltrata a Google Cloud utilizzando Collector OpenTelemetry configurato con gli esportatori Google. Utilizza Flask per gestire le richieste HTTP e la libreria requests per effettuare richieste HTTP. a generare metriche e tracce per il client HTTP server, l'app di esempio installa opentelemetry-instrumentation-flask e opentelemetry-instrumentation-requests librerie di strumentazione:

logger = logging.getLogger(__name__)

app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()

L'app ha due endpoint:

L'endpoint /multi è gestito dalla funzione multi. Il carico nell'app invia richieste all'endpoint /multi. Quando questo endpoint riceve una richiesta, invia da tre a sette richieste all'endpoint /single sul server locale.

@app.route('/multi')
def multi():
    """Handle an http request by making 3-7 http requests to the /single endpoint."""
    subRequests = randint(3, 7)
    logger.info("handle /multi request", extra={'subRequests': subRequests})
    for _ in range(subRequests):
        requests.get(url_for('single', _external=True))
    return 'ok'

L'endpoint /single è gestito dalla funzione single. Quando questo endpoint riceve una richiesta, entra in modalità di sospensione per un breve periodo di tempo e poi risponde con una stringa.

@app.route('/single')
def single():
    """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
    duration = uniform(0.1, 0.2)
    time.sleep(duration)
    return f'slept {duration} seconds'

Scarica ed esegui il deployment dell'app

Per eseguire l'esempio, segui questi passaggi:

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Clona il repository:

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python

Vai alla directory di esempio:

cd opentelemetry-operations-python/samples/instrumentation-quickstart

Crea ed esegui il sample:

docker compose up --abort-on-container-exit

Se non esegui l'applicazione su Cloud Shell, eseguila con la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS che rimanda a un file delle credenziali. App predefinita Credenziali fornisce un file di credenziali all'indirizzo $HOME/.config/gcloud/application_default_credentials.json.

# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Visualizzare le metriche

La misurazione OpenTelemetry nell'app di esempio genera metriche Prometheus che puoi visualizzare utilizzando Metrics Explorer:

Prometheus/http_server_duration_milliseconds/histogram registra la durata delle richieste al server e memorizza i risultati in un istogramma.
Prometheus/http_client_duration_milliseconds/histogram registra la durata delle richieste del client e memorizza i risultati in un istogramma.

Per visualizzare le metriche generate dall'app di esempio, procedi nel seguente modo:

Nella console Google Cloud, vai alla pagina Esplora metriche:
Vai a Esplora metriche

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
Nell'elemento Metrica, espandi il menu Seleziona una metrica, inserisci http_server nella barra dei filtri, poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
1. Nel menu Risorse attive, seleziona Target Prometheus.
2. Nel menu Categorie di metriche attive, seleziona Http.
3. Seleziona una metrica nel menu Metriche attive.
4. Fai clic su Applica.
Configura la visualizzazione dei dati.
Quando le misurazioni di una metrica sono cumulativo, Metrics Explorer normalizza automaticamente i dati misurati il periodo di allineamento, che determina la visualizzazione di un tasso nel grafico. Per maggiori informazioni, consulta Tipi, conversioni e tipi.

Quando vengono misurati valori interi o doppi, ad esempio con i due valori counter, Metrics Explorer somma automaticamente tutte le serie temporali. Per visualizzare i dati relativi alle route HTTP /multi e /single, imposta il primo menu della voce Aggregation su None.

Per ulteriori informazioni sulla configurazione di un grafico, consulta Seleziona le metriche quando utilizzi Esplora metriche.

Visualizzare le tracce

Per visualizzare i dati di traccia, segui questi passaggi:

Nella console Google Cloud, vai alla pagina Esplora tracce.
Vai a Trace Explorer

Puoi trovare questa pagina anche utilizzando la barra di ricerca.
Nel grafico a dispersione, seleziona una traccia con URI /multi.
Nel grafico di Gantt, all'interno del riquadro Dettagli traccia, seleziona l'intervallo con l'etichetta /multi.

Viene visualizzato un riquadro che mostra le informazioni sulla richiesta HTTP. Questi dettagli includono il metodo, il codice di stato, il numero di byte e l'agente utente del chiamante.
Per visualizzare i log associati a questa traccia, seleziona la scheda Log ed eventi.

La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandere la voce di log. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.

Per ulteriori informazioni sull'utilizzo di Explorer di Cloud Trace, consulta Trovare ed esplorare le tracce.

Visualizza i log

Da Esplora log, puoi ispezionare i log e anche visualizzare le tracce associate, se esistono.

Nella console Google Cloud, vai alla pagina Esplora log:
Vai a Esplora log

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.
Individua un log con la descrizione handle /multi request.

Per visualizzare i dettagli del log, espandi la voce del log.
Fai clic su Tracce in una voce di log con "handle /multi-richiesta" quindi seleziona Visualizza dettagli traccia.

Si apre un riquadro Dettagli traccia che mostra la traccia selezionata.

Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Visualizza i log utilizzando Esplora log.