Panoramica di v1.metrics

Questo documento descrive come i dati delle metriche inviati al tuo Google Cloud progetto utilizzando l'API Telemetry (OTLP) vengono mappati alle strutture di Cloud Monitoring. Questa API implementa il protocollo OpenTelemetry Line. Puoi inviare dati a questa API quando instrumenti le tue applicazioni con un esportatore otlphttp e un agente di raccolta OpenTelemetry o quando utilizzi gli SDK OpenTelemetry.

OpenTelemetry è un progetto open source supportato da Google Cloudcon ingegneri Google Cloud assegnati per garantire il supporto per l'importazione e la visualizzazione della telemetria.

Best practice

Quando instrumenti le tue applicazioni per inviare dati di traccia al tuo progettoGoogle Cloud , ti consigliamo di utilizzare un esportatore che scriva dati in formato OTLP in un agente di raccolta, che poi invia i dati di traccia all'API Telemetry. Nell'agente di raccolta, specifica solo l'URL di base:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry rileva il tipo di dati e aggiunge automaticamente /v1/traces, /v1/metrics o /v1/logs, a seconda dei casi. Per saperne di più, consulta Richiesta OTLP/HTTP.

Per esempi di esportazione di dati di traccia o metriche nell'API Telemetry, consulta i seguenti documenti:

• Panoramica degli esempi di strumentazione basata su collector.
• Panoramica dell'importazione delle metriche OTLP.

Quando non puoi utilizzare un agente di raccolta, puoi utilizzare una libreria OpenTelemetry che contiene un esportatore OTLP in-process per inviare la telemetria all'API Telemetry. Per scoprire come esportare direttamente i dati di traccia, consulta Esportatore Cloud Trace all'endpoint OTLP.

Autenticazione

Devi configurare gli esportatori con le credenziali necessarie per inviare i dati al tuo progetto Google Cloud . Ad esempio, quando utilizzi i raccoglitori, in genere utilizzi anche l'estensione googleclientauth per l'autenticazione con le credenziali Google.

Per un esempio di autenticazione quando utilizzi l'esportazione diretta dei dati di traccia, consulta Configura l'autenticazione. Questo esempio mostra come configurare l'esportatore con le tue Google Cloud credenziali predefinite dell'applicazione (ADC) e aggiungere una libreria di autenticazione Google specifica per la lingua alla tua applicazione.

Metriche OTLP in Cloud Monitoring

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Quando le metriche vengono importate in Cloud Monitoring utilizzando un OpenTelemetry Collector e l'esportatore otlphttp o inviate direttamente utilizzando un SDK OpenTelemetry, le metriche OTLP vengono mappate alle strutture delle metriche di Cloud Monitoring. Questa sezione descrive quanto segue:

• La mappatura tra le risorse OTLP e le risorse monitorate di Cloud Monitoring.
• La mappatura tra le metriche OTLP e le metriche di Cloud Monitoring.

Mappatura delle risorse monitorate

Tutti i punti delle metriche vengono scritti così come sono per Google Cloud Managed Service per Prometheus, utilizzando il mapping di Prometheus.

Mappatura di Prometheus

Le metriche Prometheus richiedono l'utilizzo del tipo di risorsa monitorata prometheus_target.

Le seguenti etichette del tipo di risorsa prometheus_target vengono utilizzate per schematizzare e archiviare in modo efficiente i dati in Monarch. Più specifichi i valori di questi attributi, migliori saranno la queryabilità e la scalabilità.

Ti consigliamo vivamente di essere il più esplicito possibile quando imposti i valori per queste etichette, anche se abbiamo implementato una logica di fallback da utilizzare in assenza di valori espliciti.

La tabella seguente mostra le origini dei valori per le etichette, in ordine di priorità:

Etichetta prometheus-target	Valore utilizzato (in ordine di priorità)
location (obbligatorio)	Attributo location Attributo cloud.availability_zone Attributo cloud.region Rifiuta il punto se vuoto
cluster	Attributo cluster Attributo k8s.cluster.name __gce__, se l'attributo cloud.platform è gcp_compute_engine __run__, se l'attributo cloud.platform è gcp_cloud_run Stringa vuota
namespace	Attributo namespace Attributo k8s.namespace.name Attributo service.namespace Stringa vuota
job	Attributo job "service.namespace" + "/" + attributo service.namespace Attributo service.name Attributo service.name, se non unknown_service:foo Attributo faas.name Attributo k8s.deployment.name Attributo k8s.statefulset.name Attributo k8s.job.name Attributo k8s.cronjob.name Attributo service.name, se unknown_service:foo Stringa vuota
instance (obbligatorio)	Attributo instance Attributo service.instance.id Attributo faas.instance Attributo k8s.pod.name:k8s.container.name Attributo k8s.pod.name, se non è presente alcun nome del container Attributo host.id Rifiuta il punto se vuoto

Mappatura delle metriche

Le metriche vengono convertite nel formato di serie temporali di Prometheus. I nomi delle metriche devono avere un dominio o il dominio prometheus.googleapis.com. Dopo la conversione, il nome della metrica includerà il prefisso prometheus.googleapis.com e un suffisso aggiuntivo, in base al tipo di punto OTLP. La metrica di Cloud Monitoring risultante ha la seguente struttura:

prometheus.googleapis.com/{metric_name}/{suffix}

Inoltre, per ogni risorsa OpenTelemetry univoca, la conversione aggiunge una metrica target_info che contiene tutti gli attributi della risorsa, tranne service.name, service.instance.id e service.namespace.

Tutte le metriche OTLP INT64 vengono convertite nel DOUBLE tipo di valore in Cloud Monitoring, anche se l'agente di raccolta specifica il tipo di valore come INT64. Questa modifica viene apportata perché una volta che una serie temporale si trova in Monarch, non puoi modificare il tipo di valore. La conseguenza più comune del supporto dei valori INT64 è che si verificano conflitti che possono essere risolti solo eliminando una metrica.

Nota: prevediamo che si verifichino possibili conflitti tra i tipi di valori, in particolare se in precedenza hai inviato metriche INT64 target_info. Se si verificano collisioni, la soluzione migliore a lungo termine è eliminare il descrittore della metrica per le metriche INT64 target_info. Per eliminare questo descrittore dall'ambito della metrica, utilizza questo script Golang.

Mapping delle metriche Prometheus

I tipi di metrica sono mappati come segue:

• Il tipo di metrica OTLP Gauge corrisponde al tipo di metrica Gauge di Cloud Monitoring.
• OTLP Sum esegue il mapping come segue:
  • A indicatore di Cloud Monitoring quando is_monotonic è impostato su false.
  • A Cloud Monitoring cumulativo quando aggregation_temporality è impostato su AGGREGATION_TEMPORALITY_CUMULATIVE.
  • A Cloud Monitoring delta quando aggregation_temporality è impostato su AGGREGATION_TEMPORALITY_DELTA.
• L'istogramma OTLP viene mappato alla distribuzione di Cloud Monitoring con un tipo di metrica cumulativa o delta, a seconda del valore di aggregation_temporality.
• Le metriche di riepilogo OTLP vengono espanse in serie temporali individuali per ogni componente: count, sum e ogni quantile.
  • I nomi delle metriche di conteggio e somma hanno come suffisso _count o _sum rispettivamente e sono scritti come metriche cumulative di Cloud Monitoring di tipo DOUBLE.
  • Ogni quantile diventa una propria serie temporale di tipo indicatore DOUBLE, con un'etichetta quantile.

La seguente tabella riassume il mapping delle metriche:

Tipo di punto OTLP	Monitoraggio tipo di metrica	Monitoraggio tipo di valore	Suffisso	Note
GAUGE	GAUGE	DOUBLE	/gauge
GAUGE (metric.metadata["prometheus.type"]="unknown")	GAUGE	DOUBLE	/unknown	I valori sconosciuti di Prometheus vengono suddivisi in un contatore e un indicatore da OpenTelemetry Collector.
SUM (monotonic, CUMULATIVE)	CUMULATIVO	DOUBLE	/counter
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVO	DOUBLE	/unknown:counter	I valori sconosciuti di Prometheus vengono suddivisi in un contatore e un indicatore da OpenTelemetry Collector.
SUM (monotonic, DELTA)	DELTA	DOUBLE	/delta
SUM (non-monotonic, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SUM (non-monotonic, DELTA)	Non supportato			UpDownCounter con temporalità delta non sono supportati.
ISTOGRAMMA (CUMULATIVO)	CUMULATIVO	DISTRIBUZIONE con bucket espliciti	/histogram
ISTOGRAMMA ESPONENZIALE (CUMULATIVO)	CUMULATIVO	DISTRIBUTION con bucket esponenziali	/histogram
ISTOGRAMMA (DELTA)	DELTA	DISTRIBUZIONE con bucket espliciti	/histogram:delta
ISTOGRAMMA ESPONENZIALE (DELTA)	DELTA	DISTRIBUTION con bucket esponenziali	/histogram:delta
SUMMARY (sum, count, quantile)	CUMULATIVO CUMULATIVO INDICATORE	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	I punti dati di riepilogo vengono scritti come più serie temporali, una per conteggio, somma e ogni quantile calcolato. Vengono generate anche le metriche quantile con un'etichetta quantile.

Differenze tra l'esportatore googlemanagedprometheus e l'API Telemetry

L'API Telemetry (telemetry.googleapis.com) gestisce le metriche in modo diverso dall'esportatore googlemanagedprometheus:

• L'API Telemetry consente l'utilizzo dei caratteri punto (.) e barra (/) nei nomi delle metriche. L'esportatore googlemanagedprometheus converte tutte le istanze di questi caratteri nel carattere di sottolineatura (_). Ad esempio, una metrica OTLP denominata prometheus.googleapis.com/foo.bar/gauge viene esportata letteralmente dall'esportatore OTLP, ma viene esportata come prometheus.googleapis.com/foo_bar/gauge dall'esportatore googlemanagedprometheus.

  Quando le metriche vengono importate, Cloud Monitoring crea descrittori di metriche in base ai nomi. La differenza nel modo in cui i caratteri punto (.) e barra (/) vengono gestiti dai percorsi di importazione fa sì che i descrittori delle metriche risultanti differiscano tra le metriche importate utilizzando l'esportatore googlemanagedprometheus e quelle importate utilizzando l'esportatore otlphttp. Se utilizzi entrambi i percorsi di importazione, avrai due set di metriche. Per ottenere risultati completi durante l'esecuzione di query, devi unire manualmente i risultati delle versioni Prometheus e OTLP delle metriche.

• L'API Telemetry non aggiunge un'unità a un nome di metrica quando è presente un'unità e non aggiunge un suffisso _total ai contatori. Pertanto, una metrica esportata come prometheus.googleapis.com/foo/counter quando si utilizza l'API Telemetry viene esportata come prometheus.googleapis.com/foo_seconds_total/counter dall'esportatore googlemanagedprometheus. Questa differenza vale anche per i suffissi _total e _ratio.

• L'API sintetizza il valore sum_of_squared_deviation per i valori di distribuzione derivati dagli istogrammi esponenziali. L'esportatore googlemanagedprometheus non imposta questo campo per gli istogrammi esponenziali.

• L'API converte tutti i valori interi dei punti in valori doppi per le metriche Prometheus.

• L'API non imposta le etichette scope_version o scope_name se queste hanno valori vuoti.

Cloud Monitoring e localizzazione dei dati

Per informazioni su come vengono archiviati i dati delle metriche, consulta Regionalità dei dati per Cloud Monitoring.

Dove visualizzare i dati importati

I dati delle metriche inseriti tramite l'API Telemetry possono essere visualizzati utilizzando la pagina Esplora metriche. Per informazioni sulla visualizzazione e la rappresentazione grafica dei dati delle metriche, consulta Crea grafici con Esplora metriche.