Panoramica di v1.metrics

Questo documento descrive come i dati delle metriche inviati a your Google Cloud project utilizzando l'API Telemetry (OTLP) vengono mappati alle strutture di Cloud Monitoring. Questa API implementa il protocollo OpenTelemetry OTLP. Puoi inviare dati a questa API quando strumenti 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 Google Cloudcon Google Cloud ingegneri che garantiscono il supporto per l'importazione e la visualizzazione della telemetria.

Best practice

Quando strumenti le applicazioni per inviare dati di traccia al tuo Google Cloud progetto, ti consigliamo di utilizzare un esportatore che scriva i dati in formato OTLP in un agente di raccolta, che poi invia i dati di traccia all'API Telemetry. Nel raccoglitore, 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 basati su raccoglitore.
• Panoramica dell'importazione di 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 a your Google Cloud project. 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 Configurare l'autenticazione. Questo esempio illustra 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 agente di raccolta OpenTelemetry 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:

• Il mapping tra le risorse OTLP e le risorse monitorate di Cloud Monitoring.
• Il mapping tra le metriche OTLP e le metriche di Cloud Monitoring.

Mapping 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.

Mapping di Prometheus

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

Le seguenti etichette sul tipo di risorsa prometheus_target vengono utilizzate per schematizzare e archiviare in modo efficiente i dati in Monarch. Più precisamente specifichi i valori per questi attributi, migliore sarà la query 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" + "/" + service.namespace attributo 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 il nome del container Attributo host.id Rifiuta il punto se è vuoto

Mapping delle metriche

Le metriche vengono convertite nel formato di serie temporali di Prometheus. I nomi delle metriche non 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 target_info metrica che contiene tutti gli attributi delle risorse, ad eccezione di service.name, service.instance.id, e service.namespace.

Tutte le metriche OTLP INT64 vengono convertite nel tipo di valore DOUBLE 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 modificarne il tipo di valore. La conseguenza più comune del supporto dei valori INT64 è che si verificano collisioni che possono essere risolte solo eliminando una metrica.

Nota: prevediamo che possano verificarsi collisioni di 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 target_info INT64. Per eliminare questo descrittore dall'ambito delle metriche, utilizza questo script Golang.

Mapping delle metriche di Prometheus

I tipi di metriche vengono mappati come segue:

• Il tipo di metrica OTLP Gauge viene mappato al tipo di metrica Gauge di Cloud Monitoring.
• Il tipo di metrica OTLP Sum viene mappato come segue:
  • Al tipo di metrica Gauge di Cloud Monitoring gauge quando is_monotonic è impostato su false.
  • Al tipo di metrica Cumulative di Cloud Monitoring quando aggregation_temporality è impostato su AGGREGATION_TEMPORALITY_CUMULATIVE.
  • Al tipo di metrica Delta di Cloud Monitoring delta quando aggregation_temporality è impostato su AGGREGATION_TEMPORALITY_DELTA.
• Il tipo di metrica OTLP Histogram viene mappato al tipo di metrica Distribution di Cloud Monitoring distribution con un tipo di metrica Cumulative o Delta, a seconda del valore di aggregation_temporality.
• Le metriche OTLP Summary vengono espanse in serie temporali individuali per ogni componente: count, sum e ogni quantile.
  • I nomi delle metriche di conteggio e somma hanno rispettivamente i suffissi _count o _sum e vengono scritti come metriche cumulative di Cloud Monitoring di tipo DOUBLE.
  • Ogni quantile diventa una serie temporale di tipo Gauge di tipo DOUBLE, con un'etichetta quantile.

La tabella seguente riassume il mapping delle metriche:

Tipo di punto OTLP point kind	Tipo di metrica di Monitoring	Tipo di valore di Monitoring	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 tipo di metrica Gauge dal raccoglitore OpenTelemetry.
SUM (monotono, CUMULATIVE)	CUMULATIVE	DOUBLE	/counter
SUM (monotono, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	CUMULATIVE	DOUBLE	/unknown:counter	I valori sconosciuti di Prometheus vengono suddivisi in un contatore e un tipo di metrica Gauge dal raccoglitore OpenTelemetry.
SUM (monotono, DELTA)	DELTA	DOUBLE	/delta
SUM (non monotono, CUMULATIVE)	GAUGE	DOUBLE	/gauge
SUM (non monotono, DELTA)	Non supportato			I contatori UpDownCounters con temporalità delta non sono supportati.
HISTOGRAM (CUMULATIVE)	CUMULATIVE	DISTRIBUTION con bucket espliciti	/histogram
EXPONENTIAL HISTOGRAM (CUMULATIVE)	CUMULATIVE	DISTRIBUTION con bucket esponenziali	/histogram
HISTOGRAM (DELTA)	DELTA	DISTRIBUTION con bucket espliciti	/histogram:delta
EXPONENTIAL HISTOGRAM (DELTA)	DELTA	DISTRIBUTION con bucket esponenziali	/histogram:delta
SUMMARY (sum, count, quantile)	CUMULATIVE CUMULATIVE GAUGE	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	I punti dati di riepilogo vengono scritti come più serie temporali, una per il conteggio, la somma e ogni quantile calcolato. Le metriche quantile vengono anche generate 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'googlemanagedprometheus esportatore:

• L'API Telemetry consente l'utilizzo dei caratteri punto (.) e barra (/) ne i nomi delle metriche. L'esportatore googlemanagedprometheus converte tutte le istanze di questi caratteri nel carattere trattino basso (_). 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 significa che i descrittori di metriche risultanti differiscono 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 si applica anche ai suffissi _total e _ratio.

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

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

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

Cloud Monitoring e residenza dei dati

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

Dove visualizzare i dati importati

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