Panoramica dell'API Telemetry (OTLP)

Questo documento descrive l'API Telemetry (OTLP), che implementa il protocollo OpenTelemetry OTLP. Questa API è progettata per l'utilizzo con applicazioni instrumentate utilizzando uno degli SDK OpenTelemetry o che utilizzano qualsiasi OpenTelemetry Collector.

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.

Dati di Trace e API Telemetry

Questa sezione fornisce informazioni sull'API Telemetry e sulle tracce.

Perché dovresti utilizzare l'API Telemetry

Quando utilizzi l'API Telemetry, i tuoi dati vengono archiviati in un formato generalmente coerente con i file proto definiti dal protocollo OpenTelemetry OTLP. Tuttavia, i campi potrebbero essere convertiti da un tipo di dati specifico di OpenTelemetry a un tipo di dati JSON prima dell'archiviazione. Inoltre, si applicano i limiti per l'API Telemetry. Questi limiti sono spesso più generosi di quelli dell'Cloud Trace API. Infine, la strumentazione non si basa su un esportatore specifico per Google Cloud.

Per saperne di più sul formato di archiviazione, consulta Schema per i dati di traccia.

Quando utilizzare l'API Telemetry

Ti consigliamo di inviare i dati di traccia al tuo progetto Google Cloud utilizzando l'API Telemetry. Questa API offre la compatibilità con l'ecosistema OpenTelemetry open source e i suoi limiti sono spesso più generosi di quelli dell'Cloud Trace API, che è un'APIGoogle Cloud proprietaria. Alcune funzionalità, come il monitoraggio delle applicazioni, si basano su informazioni disponibili solo quando i dati di traccia vengono inviati all'API Telemetry.

Quando instrumenti le tue applicazioni per inviare dati di traccia al tuo progettoGoogle Cloud , ti consigliamo di procedere in uno dei seguenti modi:

Utilizza un esportatore che scrive OTLP in un raccoglitore, che poi invia i dati di traccia all'API Telemetry.
Utilizza un esportatore OTLP in-process supportato da una libreria OpenTelemetry che invia dati di telemetria all'API Telemetry. Non esiste un raccoglitore con questa configurazione.

Per informazioni su come utilizzare l'API Telemetry, consulta Eseguire la migrazione dall'esportatore Cloud Trace all'endpoint OTLP.

Autenticazione

Gli esportatori devono essere autorizzati a inviare dati al tuo progetto Google Cloud . Ad esempio, puoi configurare l'esportatore con le tue Google Cloud credenziali predefinite dell'applicazione (ADC) aggiungendo una libreria di autenticazione Google specifica per la lingua alla tua applicazione. Per ulteriori informazioni e codice campione, vedi Configurare l'autenticazione.

Cloud Trace e localizzazione dei dati

Se utilizzi Assured Workloads perché hai requisiti di residenza dei dati o Impact Level 4 (IL4), non utilizzare l'API Telemetry per inviare gli intervalli di traccia.

Dati delle metriche e API Telemetry

Questa sezione descrive come Cloud Monitoring gestisce le metriche inserite utilizzando l'esportatore otlphttp e un collettore OpenTelemetry o da applicazioni strumentate utilizzando uno degli SDK OpenTelemetry.

Metriche OTLP in Cloud Monitoring

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ù precisi sono i valori specificati per 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`
`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` Rifiuta il punto se vuoto	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`

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 il raccoglitore 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.

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 dal collettore OpenTelemetry.
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 dal collettore OpenTelemetry.
SUM (monotono, DELTA)	DELTA	DOUBLE	/delta
SUM (non-monotonic, CUMULATIVE)	GAUGE	DOUBLE	/gauge
ISTOGRAMMA (CUMULATIVO)	CUMULATIVO	DISTRIBUZIONE con bucket espliciti	/histogram
ISTOGRAMMA ESPONENZIALE (CUMULATIVO)	CUMULATIVO	DISTRIBUZIONE con bucket esponenziali	/histogram
ISTOGRAMMA (DELTA)	DELTA	DISTRIBUZIONE con bucket espliciti	/histogram:delta
ISTOGRAMMA ESPONENZIALE (DELTA)	DELTA	DISTRIBUZIONE con bucket esponenziali	/histogram:delta
RIEPILOGO (somma, conteggio, 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 dei punti interi in valori doppi per le metriche Prometheus.
L'API non imposta le etichette scope_version o scope_name se queste hanno valori vuoti.

Dove visualizzare i dati importati

I dati di Trace importati tramite l'API Telemetry possono essere visualizzati utilizzando la pagina Esplora tracce. Per informazioni su come visualizzare i dati di traccia, consulta le seguenti risorse:

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.

Supporto dei Controlli di servizio VPC

Il servizio API Telemetry, il cui nome servizio è telemetry.googleapis.com, è un servizio supportato dai Controlli di servizio VPC. Eventuali limitazioni dei Controlli di servizio VPC che crei per il servizio API Telemetry si applicano solo a quel servizio. Queste limitazioni non si applicano ad altri servizi, inclusi quelli come il servizio cloudtrace.googleapis.com, che possono anche importare dati di tracciamento.

Per ulteriori informazioni, consulta le seguenti risorse: