Raccogliere metriche e tracce OpenTelemetry Protocol (OTLP)

Questo documento descrive come utilizzare Ops Agent e il ricevitore OTLP (OpenTelemetry Protocol) per raccogliere tracce e metriche definite dall'utente dalle applicazioni instrumentate mediante OpenTelemetry e in esecuzione su Compute Engine.

Questo documento è organizzato nel seguente modo:

Una panoramica che descrive i casi d'uso per il ricevitore OTLP.
Prerequisiti per l'utilizzo del ricevitore OTLP.
Configurazione dell'agente per l'utilizzo del ricevitore OTLP.
Utilizzare il ricevitore per raccogliere metriche. Questa sezione descrive come eseguire query sulle metriche OpenTelemetry in Cloud Monitoring.
Utilizzo del ricevitore per raccogliere le tracce. Questa sezione descrive come autorizzare un account di servizio a scrivere dati in Cloud Trace.

Panoramica dell'utilizzo del ricevitore OTLP

Con il ricevitore OTLP di Ops Agent, puoi:

Instrumenta la tua applicazione utilizzando uno degli SDK specifici del linguaggio per OpenTelemetry. Per informazioni sulle lingue supportate, consulta OpenTelemetry Instrumentation. La combinazione degli SDK OpenTelemetry e Ops Agent ti consentono di:
- Raccogli le metriche OTLP dalla tua applicazione e inviale a Cloud Monitoring per l'analisi.
- Raccogli gli intervalli OTLP, ovvero i dati, dall'applicazione e inviali a Cloud Trace per l'analisi.
Raccogli le tracce da applicazioni di terze parti che dispongono del supporto integrato per OTLP o da plug-in con questo tipo di supporto, ad esempio applicazioni come Nginx. Il ricevitore OTLP in Ops Agent può raccogliere queste tracce. Per un esempio, consulta il modulo nginx OpenTelemetry.
Utilizza la strumentazione personalizzata di OpenTelemetry.
Utilizza la strumentazione automatica di OpenTelemetry.

Puoi utilizzare il destinatario per raccogliere metriche, tracce o entrambe. Dopo che Ops Agent ha raccolto le metriche, puoi utilizzare le funzionalità di Cloud Monitoring, tra cui grafici, dashboard e criteri di avviso, per monitorare le metriche. Se l'applicazione invia anche dati di traccia, puoi utilizzare Cloud Trace per analizzarli.

Vantaggi

Prima della disponibilità del plug-in OTLP per Ops Agent, tra i principali modi in cui le applicazioni raccogliere le metriche e le tracce definite dall'utente includevano quanto segue:

Utilizzo di librerie client che implementano l'API Monitoring o l'API Trace.
Utilizzare le librerie OpenCensus precedenti.

L'utilizzo di OpenTelemetry con il ricevitore OTLP offre diversi vantaggi rispetto a questi metodi, tra cui:

OpenTelemetry sostituisce OpenCensus. Il progetto OpenCensus è in fase di archiviazione. Per ulteriori informazioni, consulta la sezione Che cos'è OpenTelemetry?.
L'importazione è controllata a livello di agente, quindi non è necessario eseguire nuovamente il deployment delle applicazioni se la configurazione dell'agente cambia.
Nelle tue applicazioni non è necessario configurare le credenziali Google Cloud; tutta l'autorizzazione viene gestita a livello di agente.
Il codice dell'applicazione non contiene codice di monitoraggio o tracciamento specifico di Google Cloud. Non devi utilizzare direttamente l'API Monitoring o l'API Trace.
L'applicazione esegue il push dei dati a Ops Agent e, in caso di arresto anomalo dell'applicazione, i dati raccolti da Ops Agent non andranno persi.

Limitazioni

Il listener OTLP esposto dal destinatario Ops Agent supporta il trasporto gRPC. HTTP, utilizzato principalmente per i client JavaScript, non è supportato. Per ulteriori informazioni sul protocollo OpenTelemetry, consulta Dettagli del protocollo.

Il ricevitore OTLP non raccoglie log. Puoi raccogliere i log utilizzando Ops Agent e altri ricevitori e puoi includere le informazioni di log negli intervalli OTLP, ma il ricevitore OTLP non supporta la raccolta diretta dei log. Per informazioni sull'utilizzo di Ops Agent per raccogliere i log, consulta Configurazioni di Logging.

Prerequisiti

Per raccogliere metriche e tracce OTLP utilizzando il ricevitore OTLP e l'Ops Agent, devi installare Ops Agent versione 2.37.0 o successive.

Questo documento presuppone che tu abbia già un'applicazione basata su OpenTelemetry scritta utilizzando uno degli SDK OpenTelemetry. Questo documento non tratta l'uso degli SDK OpenTelemetry. Per informazioni sugli SDK e sui linguaggi supportati, consulta OpenTelemetry Instrumentation.

Configurazione dell'agente operativo

Per configurare Ops Agent per l'utilizzo del ricevitore OTLP:

Modifica il file di configurazione utente per Ops Agent in modo che includa il ricevitore OTLP.
Riavvia Ops Agent.

Nelle sezioni seguenti vengono descritti i singoli passaggi.

Modifica il file di configurazione utente di Ops Agent

Aggiungi gli elementi di configurazione per il ricevitore OTLP al file di configurazione utente per Ops Agent:

Per Linux: /etc/google-cloud-ops-agent/config.yaml
Per Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

Per informazioni generali sulla configurazione dell'agente, consulta Modello di configurazione.

Il ricevitore OTLP introduce la sezione di configurazione combined per Ops Agent. L'uso del ricevitore richiede la configurazione dei servizi per le metriche e le tracce, anche se non li usi entrambi.

Le seguenti sezioni descrivono i passaggi per la configurazione del ricevitore OTLP.

Aggiungi la sezione ricevitore `combined`

Puoi posizionare il destinatario per le metriche e le tracce OTLP nella sezione combined. Non sono ammessi responsabili o servizi nella sezione combined. Non devi configurare nessun altro ricevitore con lo stesso nome di un ricevitore nella sezione combined. L'esempio seguente utilizza otlp come nome del ricevitore.

La configurazione combined minima per OTLP è la seguente:

combined:
  receivers:
    otlp:
      type: otlp

Il destinatario otlp offre le seguenti opzioni di configurazione:

type: obbligatorio. Deve essere otlp
grpc_endpoint: facoltativo. L'endpoint gRPC su cui è in ascolto il ricevitore OTLP. Il valore predefinito è 0.0.0.0:4317.
metrics_mode: facoltativo. Il valore predefinito è googlemanagedprometheus, il che significa che il ricevitore invia le metriche OTLP come metriche formattate da Prometheus utilizzando l'API Prometheus utilizzata anche da Managed Service per Prometheus.

Per inviare le metriche come metriche personalizzate di Cloud Monitoring utilizzando invece l'API Monitoring, imposta l'opzione metrics_mode sul valore googlecloudmonitoring.

Questa scelta influisce sul modo in cui le metriche vengono importate e su come vengono misurate per la fatturazione. Per saperne di più sui formati delle metriche, consulta Formati di importazione per le metriche OTLP.

Aggiungere pipeline OTLP ai servizi

Il ricevitore OTLP può raccogliere metriche e tracce, quindi devi definire un servizio per le metriche e le tracce. Se non raccoglierai metriche o tracce, puoi creare servizi vuoti. Se hai già dei servizi con altre pipeline, puoi aggiungere loro la pipeline OTLP.

Di seguito sono mostrati i servizi metrics e traces con il ricevitore OTLP incluso nelle pipeline:

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

Se non vuoi utilizzare il servizio metrics o traces per la raccolta OTLP, lascia il ricevitore OTLP fuori dalla pipeline del servizio. Il servizio deve esistere anche se non ha pipeline. Se l'applicazione invia dati di un determinato tipo e non esiste una pipeline corrispondente che includa il ricevitore, Ops Agent elimina i dati.

Riavvia Ops Agent

Per applicare le modifiche alla configurazione, devi riavviare Ops Agent.

Linux

Per riavviare l'agente, esegui questo comando sull'istanza:
```
sudo systemctl restart google-cloud-ops-agent
```
Per confermare che l'agente è stato riavviato, esegui il comando seguente e verifica che i componenti "Metrics Agent" e "Logging Agent" siano stati avviati:
```
sudo systemctl status "google-cloud-ops-agent*"
```

Windows

Connettiti all'istanza utilizzando RDP o uno strumento simile e accedi a Windows.
Apri un terminale PowerShell con privilegi di amministratore facendo clic con il tasto destro del mouse sull'icona di PowerShell e selezionando Esegui come amministratore
Per riavviare l'agente, esegui il comando PowerShell seguente:
```
Restart-Service google-cloud-ops-agent -Force
```
Per confermare che l'agente è stato riavviato, esegui il comando seguente e verifica che i componenti "Metrics Agent" e "Logging Agent" siano stati avviati:
```
Get-Service google-cloud-ops-agent*
```

Raccogliere metriche OTLP

Quando utilizzi il ricevitore OTLP per raccogliere metriche dalle applicazioni OpenTelemetry, la configurazione principale per il ricevitore è l'API che vuoi utilizzare per importare le metriche.

Puoi scegliere questa opzione modificando l'opzione metrics_mode nella configurazione del ricevitore otlp o utilizzando il valore predefinito. La scelta influisce sulla modalità di importazione delle metriche OTLP in Cloud Monitoring e sulle modalità di misurazione dei dati ai fini della fatturazione.

La scelta di metrics_mode non influisce sulla tua capacità di creare grafici, dashboard e criteri di avviso in Monitoring.

Per informazioni sulla creazione di grafici e dashboard, consulta la pagina Panoramica di dashboard e grafici.
Per informazioni sui criteri di avviso, consulta la Panoramica degli avvisi.

Le seguenti sezioni descrivono le differenze nei formati utilizzati dalle modalità delle metriche e come eseguire query sui dati importati per utilizzarli in Monitoring.

Formati di importazione per le metriche OTLP

Il ricevitore OTLP fornisce l'opzione metrics_mode, che specifica l'API utilizzata per importare i dati delle metriche. Per impostazione predefinita, il ricevitore utilizza l'API Prometheus. Il valore predefinito per l'opzione metrics_mode è googlemanagedprometheus. Le metriche vengono importate utilizzando la stessa API utilizzata da Managed Service per Prometheus.

Puoi configurare il destinatario in modo che invii i dati delle metriche all'API Cloud Monitoring. Per inviare dati all'API Monitoring, imposta il valore dell'opzione metrics_mode su googlecloudmonitoring, come mostrato nell'esempio seguente:

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

Il formato di importazione utilizzato determina il modo in cui le metriche OTLP vengono mappate in Cloud Monitoring. Puoi creare grafici, dashboard e criteri di avviso in Monitoring per metriche di entrambi i formati, ma nelle query fai riferimento alle metriche in modo diverso.

Il formato di importazione determina anche il modello di prezzi utilizzato per l'importazione dei dati.

Le seguenti sezioni descrivono i prezzi, le differenze strutturali tra una metrica importata dall'API Prometheus e la stessa metrica importata dall'API Monitoring e come fare riferimento alle metriche nelle query.

Prezzi e quote

Il formato di importazione utilizzato determina la modalità di addebito delle metriche OTLP:

API Prometheus: quando utilizzi l'API Prometheus per importare le metriche della tua applicazione, i dati sono soggetti a prezzi basati su campioni, come se le metriche fossero state fornite utilizzando Managed Service per Prometheus.
- Per i prezzi attuali, consulta il riepilogo dei prezzi di Cloud Monitoring.
- Per saperne di più sul conteggio dei campioni e sulla stima dei costi, consulta Esempi di prezzi basati sui campioni importati.
API Monitoring: quando utilizzi l'API Monitoring per importare le metriche della tua applicazione, i dati sono soggetti a prezzi basati sul volume, come i dati di altre integrazioni con Ops Agent.
- Per i prezzi attuali, consulta il riepilogo dei prezzi di Cloud Monitoring.
- Per saperne di più sul volume di importazione e sulla stima dei costi, consulta la pagina Esempi di prezzi basati sui byte importati.

Le metriche importate utilizzando il ricevitore OTLP sono considerate tipi di metriche "personalizzate" quando vengono importate in Cloud Monitoring e sono soggette alle quote e ai limiti per le metriche personalizzate.

Struttura delle metriche

Cloud Monitoring descrive il formato dei dati delle metriche utilizzando uno schema chiamato descrittore della metrica. Il descrittore della metrica include il nome della metrica, il tipo di dati dei valori della metrica, la relazione tra ogni valore e i valori precedenti ed eventuali etichette associate ai valori. Se configuri il ricevitore OTLP per importare le metriche utilizzando l'API Prometheus, il descrittore della metrica creato sarà diverso da quello della metrica creato quando utilizzi l'API Monitoring.

API Prometheus: quando utilizzi l'API Prometheus per importare le metriche della tua applicazione, ogni metrica viene trasformata utilizzando la trasformazione OpenTelemetry-to-Prometheus standard e mappata a un tipo di risorsa monitorata di Cloud Monitoring.

La trasformazione include le seguenti modifiche:
- Il nome della metrica OTLP è preceduto dal prefisso prometheus.googleapis.com/.
- Tutti i caratteri non alfanumerici, come i punti (.), nel nome della metrica OTLP vengono sostituiti da trattini bassi (_).
- Il nome della metrica OTLP è postfissato con una stringa che indica il tipo di metrica, ad esempio /gauge o /counter.
Le seguenti etichette, compilate con i valori della risorsa OTLP, vengono aggiunte alla metrica:
- instance_name: il valore dell'attributo risorsa host.name.
- machine_type: il valore dell'attributo risorsa host.type.
La risorsa monitorata registrata con le misurazioni della metrica è di tipo prometheus_target generico. La serie temporale di Prometheus generata include le seguenti etichette della risorsa prometheus_target, completate con i valori della risorsa OTLP:
- location: il valore dell'attributo risorsa cloud.availability_zone.
- namespace: il valore dell'attributo risorsa host.id.
Il tipo di risorsa prometheus_target include anche queste etichette:
- project_id: l'identificatore del progetto Google Cloud, ad esempio my-project, in cui è in esecuzione Ops Agent.
- cluster: il valore è sempre __gce__ quando le metriche vengono raccolte da Ops Agent.

Se nei dati OTLP in entrata mancano gli attributi delle risorse utilizzati per i valori delle etichette, i valori vengono ricavati dalle informazioni sulla VM che esegue Ops Agent. Questo comportamento significa che i dati OTLP senza questi attributi delle risorse vengono visualizzati con le stesse etichette dei dati raccolti dal ricevitore Prometheus di Ops Agent.

API Monitoring: quando utilizzi l'API Monitoring per importare le metriche della tua applicazione, ogni metrica viene gestita come segue:

Il nome della metrica OTLP è preceduto dal prefisso workload.googleapis.com/, a meno che il nome della metrica OTLP non contenga già questa stringa o un altro dominio della metrica valido, come custom.googleapis.com. Ti consigliamo di utilizzare il dominio "carico di lavoro".
La risorsa monitorata registrata con le misurazioni delle metriche è il tipo di macchina virtuale di Compute Engine gce_instance.

I seguenti esempi mostrano i descrittori delle metriche per una coppia di metriche OpenTelemetry. Le metriche vengono create da un'applicazione che utilizza la libreria delle metriche Go OpenTelemetry. La scheda API Prometheus mostra il descrittore della metrica creato quando il ricevitore OTLP utilizza la modalità delle metriche Prometheus predefinita. La scheda API Monitoring mostra il descrittore della metrica creato quando il ricevitore OTLP utilizza la modalità della metrica googlecloudmonitoring.

Non cambia nulla nell'applicazione che crea la metrica; l'unica modifica è la modalità della metrica utilizzata dal ricevitore OTLP.

L'applicazione crea una metrica indicatore OTLP, otlp.test.gauge, che registra valori in virgola mobile a 64 bit. Le seguenti schede mostrano il descrittore della metrica creato da ogni API di importazione:

API Prometheus

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

API Monitoring

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

L'applicazione crea una metrica di contatore OTLP, otlp.test.cumulative, che registra l'aumento dei valori in virgola mobile a 64 bit. Le seguenti schede mostrano il descrittore della metrica creato da ogni API di importazione:

API Prometheus

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

API Monitoring

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

La seguente tabella riassume alcune delle differenze di formato imposte dalle API utilizzate per importare le metriche OTLP:

	API Prometheus	API Monitoring
Dominio metrica	`prometheus.googleapis.com`	`workload.googleapis.com`
Nome metrica OTLP	Modificato durante l'importazione	Utilizzata come fornita
Risorsa monitorata	`prometheus_target`	`gce_instance`

Query e formati di importazione

La modalità delle metriche utilizzata nel ricevitore OTLP influisce sul modo in cui esegui query sulle metriche risultanti in Cloud Monitoring quando crei grafici, dashboard e criteri di avviso.

Quando configuri un grafico, una dashboard o un criterio di avviso in Cloud Monitoring, la configurazione include una query per i dati su cui opera il grafico, la dashboard o il criterio di avviso.

Cloud Monitoring supporta i seguenti strumenti per eseguire query sui dati delle metriche:

Un'interfaccia basata sul generatore di query integrata in strumenti come Metrics Explorer, l'interfaccia dello strumento di creazione di dashboard e l'interfaccia di configurazione dei criteri di avviso.
Monitoring Query Language (MQL): un linguaggio di query basato su testo specifico di Cloud Monitoring.
Prometheus Query Language (PromQL): il linguaggio di query basato su testo utilizzato da Prometheus open source.

Per informazioni sull'esecuzione di query sulle metriche OTLP utilizzando questi strumenti, consulta quanto segue:

Esegui una query sulle metriche OTLP importate utilizzando l'API Prometheus
Esegui una query sulle metriche OTLP importate utilizzando l'API Monitoring

Esegui query sulle metriche OTLP importate utilizzando l'API Prometheus

Questa sezione illustra come eseguire query sulle metriche OTLP importate utilizzando l'API Prometheus, che è la modalità metrica predefinita per il ricevitore OTLP.

Le query si basano sulle metriche OTLP descritte in Struttura delle metriche:

otlp.test.gauge: una metrica di misurazione OTLP che registra valori in virgola mobile a 64 bit.
otlp.test.cumlative: una metrica di contatore OTLP che registra l'aumento dei valori in virgola mobile a 64 bit.

Queste metriche vengono importate in Cloud Monitoring con i seguenti tipi di metriche, che funzionano come nomi:

prometheus.googleapis.com/otlp_test_gauge/gauge
prometheus.googleapis.com/otlp_test_cumulative/counter

Le metriche importate utilizzando l'API Prometheus vengono scritte in base al tipo di risorsa monitorata prometheus_target.

Le schede mostrano l'aspetto delle query di base quando esegui query sulle metriche utilizzando la console Google Cloud. Questi esempi utilizzano Metrics Explorer, ma i principi sono gli stessi per le dashboard e i criteri di avviso.

Interfaccia dello strumento di creazione di query

Per utilizzare un'interfaccia di creazione di query per eseguire query sui dati delle metriche, puoi specificare il tipo di metrica e il tipo di risorsa monitorata digitando i campi abilitati per la ricerca. Poiché esistono molti meno tipi di risorse rispetto a quelli di metriche, è generalmente più efficiente cercare il tipo di risorsa e poi utilizzare il menu delle metriche associate per trovarlo.

Se inserisci "prometheus" nel campo di ricerca, i risultati includono la risorsa monitorata prometheus_target, mostrata con il nome visualizzato "Target Prometheus", e l'insieme di metriche che scrivono nella risorsa. Le metriche sono classificate per nome; le due metriche di esempio vengono visualizzate come categoria Otlp. Puoi selezionare Prometheus/otlp_test_cumulative/counter o Prometheus/otlp_test_gauge/gauge.

Per ulteriori informazioni sull'uso di Query Builder, consulta Creare query utilizzando i menu.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica prometheus.googleapis.com/otlp_test_gauge/gauge:

Grafico di Metrics Explorer basato su Builder per la metrica dell'indicatore OTLP importata utilizzando l'API Prometheus.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica prometheus.googleapis.com/otlp_test_cumulative/counter:

Grafico di Metrics Explorer basato su Builder per la metrica del contatore OTLP importata utilizzando l'API Prometheus.

MQL

Per eseguire query sui dati delle metriche utilizzando MQL, utilizza un'istruzione fetch e specifica il tipo di metrica e il tipo di risorsa monitorata, separandoli con ::. Le query MQL banali per le metriche di esempio hanno il seguente aspetto:

fetch prometheus.googleapis.com/otlp_test_gauge/gauge::prometheus_target
fetch prometheus.googleapis.com/otlp_test_cumulative/counter::prometheus_target

Per ulteriori informazioni sulla creazione di query MQL, consulta Esempi di query MQL.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica prometheus.googleapis.com/otlp_test_gauge/gauge:

Grafico di MQL Metrics Explorer per la metrica dell'indicatore OTLP importata utilizzando l'API Prometheus.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica prometheus.googleapis.com/otlp_test_cumulative/counter:

Grafico MQL Metrics Explorer per la metrica del contatore OTLP importata utilizzando l'API Prometheus.

PromQL

Quando utilizzi PromQL per eseguire query sui dati delle metriche importati tramite l'API Prometheus, devi specificare solo la forma modificata del nome della metrica OTLP originale. Non è necessario specificare la stringa prometheus.googleapis.com/ con prefisso o il tipo postfisso.

Se la metrica può essere scritta per un solo tipo di risorsa monitorata, non è necessario specificare la risorsa. Come descritto in Struttura delle metriche, le metriche OTLP importate utilizzando l'API Prometheus vengono scritte solo per il tipo di risorsa monitorata prometheus_target. Le query PromQL banali per le metriche di esempio hanno il seguente aspetto:

otlp_test_gauge
otlp_test_cumulative

Per ulteriori informazioni sull'utilizzo di PromQL in Cloud Monitoring per eseguire query sulle metriche importate utilizzando l'API Prometheus, consulta Dati di Google Cloud Managed Service per Prometheus in Cloud Monitoring. Per informazioni sul linguaggio PromQL, consulta la pagina relativa all'esecuzione di query su Prometheus.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica prometheus.googleapis.com/otlp_test_gauge/gauge:

Grafico PromQL Metrics Explorer per la metrica dell'indicatore OTLP importata utilizzando l'API Prometheus.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica prometheus.googleapis.com/otlp_test_cumulative/counter:

Grafico PromQL Metrics Explorer per la metrica del contatore OTLP importata utilizzando l'API Prometheus.

Esegui query sulle metriche OTLP importate utilizzando l'API Monitoring

Questa sezione illustra come eseguire query sulle metriche OTLP importate utilizzando l'API Monitoring. Puoi selezionare l'API Cloud Monitoring impostando il campo metrics_mode del ricevitore OTLP sul valore googlecloudmonitoring.

Le query si basano sulle metriche OTLP descritte in Struttura delle metriche:

otlp.test.gauge: una metrica di misurazione OTLP che registra valori in virgola mobile a 64 bit.
otlp.test.cumlative: una metrica di contatore OTLP che registra l'aumento dei valori in virgola mobile a 64 bit.

Queste metriche vengono importate in Cloud Monitoring con i seguenti tipi di metriche, che funzionano come nomi:

workload.googleapis.com/otlp.test.gauge
workload.googleapis.com/otlp.test.cumulative

Le metriche importate utilizzando l'API Monitoring vengono scritte in base al tipo di risorsa monitorata gce_instance.

Interfaccia dello strumento di creazione di query

Se inserisci "gce_instance" nel campo di ricerca, i risultati mostrano il tipo di risorsa in base al nome visualizzato "Istanza VM" e il set di metriche che scrivono nella risorsa. Le metriche sono classificate per nome; le due metriche di esempio vengono visualizzate come categoria Otlp. Puoi selezionare Workload/otlp_test_cumulative o Workload/otlp_test_gauge.

Per ulteriori informazioni sull'uso di Query Builder, consulta Creare query utilizzando i menu.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica workload.googleapis.com/otlp.test.gauge:

Grafico di Metrics Explorer basato su Builder per la metrica dell'indicatore OTLP importata utilizzando l'API Monitoring.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica workload.googleapis.com/otlp.test.cumulative:

Grafico di Metrics Explorer basato su Builder per la metrica del contatore OTLP importata utilizzando l'API Monitoring.

MQL

fetch workload.googleapis.com/otlp.test.gauge::gce_instance
fetch workload.googleapis.com/otlp.test.cumulative::gce_instance

Per ulteriori informazioni sulla creazione di query MQL, consulta Esempi di query MQL.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica workload.googleapis.com/otlp.test.gauge:

Grafico di MQL Metrics Explorer per la metrica dell'indicatore OTLP importata utilizzando l'API Monitoring.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica workload.googleapis.com/otlp.test.cumulative:

Grafico di MQL Metrics Explorer per la metrica del contatore OTLP importata utilizzando l'API Monitoring.

PromQL

Quando utilizzi PromQL per eseguire query sui dati delle metriche importati utilizzando l'API Monitoring, devi mappare il nome della metrica alle convenzioni PromQL. Le regole di mappatura di base includono:

Sostituisci la prima / con :.
Sostituisci tutti gli altri caratteri speciali (inclusi . e altri caratteri /) con _.

Per ulteriori informazioni sulle regole di mappatura, consulta Mappatura delle metriche di Cloud Monitoring a PromQL.

I tipi di metrica di Monitoring per le metriche di esempio sono mappati a PromQL come segue:

workload_googleapis_com:otlp_test_gauge
workload_googleapis_com:otlp_test_cumulative

Se la metrica può essere scritta per un solo tipo di risorsa monitorata, non è necessario specificare la risorsa. Le metriche di esempio sono scritte in base al tipo di risorsa monitorata gce_instance, ma, come descritto in Struttura della metrica, gce_instance è solo uno dei possibili tipi di metriche. Di conseguenza, le query PromQL per queste metriche devono includere un filtro per il tipo di risorsa gce_instance. Per includere il filtro, aggiungi la seguente stringa alla fine dei nomi delle metriche mappate: {monitored_resource="gce_instance"}

Per ulteriori informazioni sull'utilizzo di PromQL in Cloud Monitoring, consulta PromQL in Cloud Monitoring. Per informazioni sul linguaggio PromQL, consulta la pagina relativa all'esecuzione di query su Prometheus.

Le query PromQL banali per le metriche di esempio hanno il seguente aspetto:

workload_googleapis_com:otlp_test_gauge{monitored_resource="gce_instance"}
workload_googleapis_com:otlp_test_cumulative{monitored_resource="gce_instance"}

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica workload.googleapis.com/otlp.test.gauge:

Grafico PromQL Metrics Explorer per la metrica dell'indicatore OTLP importata utilizzando l'API Monitoring.

Il seguente screenshot mostra il risultato dell'esecuzione di query sulla metrica workload.googleapis.com/otlp.test.cumulative:

Grafico PromQL Metrics Explorer per la metrica del contatore OTLP importata utilizzando l'API Monitoring.

Visualizza l'utilizzo e la diagnostica delle metriche in Cloud Monitoring

La pagina Gestione delle metriche di Cloud Monitoring fornisce informazioni che possono aiutarti a controllare l'importo speso per le metriche addebitabili senza influire sull'osservabilità. La pagina Gestione delle metriche riporta le seguenti informazioni:

Volumi di importazione per la fatturazione basata su byte e campioni, nei domini delle metriche e per le singole metriche.
Dati su etichette e cardinalità delle metriche.
Utilizzo delle metriche nei criteri di avviso e nelle dashboard personalizzate.
Percentuale di errori di scrittura delle metriche.

Per visualizzare la pagina Gestione delle metriche:

Nel pannello di navigazione della console Google Cloud, seleziona Monitoring, quindi Gestione delle metriche:
Vai a Gestione delle metriche
Nella barra degli strumenti, seleziona la finestra temporale. Per impostazione predefinita, la pagina Gestione delle metriche mostra informazioni sulle metriche raccolte il giorno precedente.

Per saperne di più sulla pagina Gestione delle metriche, consulta Visualizzare e gestire l'utilizzo delle metriche.

Raccogliere tracce OTLP

Se hai configurato Ops Agent per raccogliere le tracce, ma non ricevi tracce in Cloud Trace quando esegui l'applicazione, potrebbe essere necessario concedere un ruolo aggiuntivo all'account di servizio Compute Engine utilizzato dall'agente. Per impostazione predefinita, l'account di servizio ottiene i ruoli necessari per scrivere metriche e log, ma non per le tracce.

Questa sezione descrive come concedere all'account di servizio l'autorizzazione Cloud Trace necessaria.

Determinare i ruoli concessi all'account di servizio

Per visualizzare i ruoli concessi a un account di servizio, esegui questo comando gcloud projects get-iam-policy:

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

L'output potrebbe essere simile al seguente:

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

Se l'output include roles/cloudtrace.agent o roles/cloudtrace.admin, l'account di servizio dispone di autorizzazioni sufficienti per scrivere tracce. Per concedere uno di questi ruoli all'account di servizio, consulta la sezione seguente.

Concedi il ruolo Cloud Trace all'account di servizio

Per un account di servizio, il ruolo Agente Cloud Trace, roles/cloudtrace.agent, in genere è appropriato. Per concedere questo ruolo all'account di servizio, esegui questo comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

Puoi quindi eseguire il comando gcloud projects get-iam-policy per verificare che la modifica sia stata apportata:

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

L'output ora include roles/cloudtrace.agent:

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

Per saperne di più sulla gestione dei ruoli IAM, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Dopo aver autorizzato l'account di servizio utilizzato da Ops Agent per scrivere dati in Cloud Trace, quando esegui l'applicazione basata su OpenTelemetry, le tracce vengono visualizzate in Cloud Trace:

Un riquadro dei dettagli della traccia mostra una traccia OTLP.

Disattiva il ricevitore OTLP

Se raccogli le metriche e le tracce OTLP utilizzando Ops Agent, ma vuoi disabilitare la raccolta di entrambe le metriche, ma non di entrambe, procedi nel seguente modo:

Disabilita la raccolta di metriche o tracce apportando una delle seguenti modifiche al file di configurazione utente config.yaml:
- Rimuovi la pipeline otlp dal servizio metrics.
- Rimuovi la pipeline otlp dal servizio traces.
Riavvia Ops Agent.

Per disabilitare la raccolta di metriche e tracce OTLP da parte di Ops Agent:

Rimuovi la configurazione OTLP dal file di configurazione utente:
- Elimina l'intera sezione combined, che include il ricevitore otlp.
- Rimuovi la pipeline otlp dal servizio metrics.
- Elimina l'intero servizio traces.
Riavvia Ops Agent.

Passaggi successivi

Dopo aver importato le metriche e le tracce dell'applicazione, puoi utilizzare la console Google Cloud per monitorare e analizzare i dati.

Per informazioni sulle dashboard e sui tipi di grafici che puoi creare, consulta la pagina Dashboard e grafici.
Per informazioni sui criteri di avviso, consulta Utilizzo dei criteri di avviso.
Per informazioni sull'analisi dei dati di traccia, consulta Trovare ed esplorare le tracce.

Raccogliere metriche e tracce OpenTelemetry Protocol (OTLP)

Panoramica dell'utilizzo del ricevitore OTLP

Vantaggi

Limitazioni

Prerequisiti

Configurazione dell'agente operativo

Modifica il file di configurazione utente di Ops Agent

Aggiungi la sezione ricevitore combined

Aggiungere pipeline OTLP ai servizi

Riavvia Ops Agent

Linux

Windows

Raccogliere metriche OTLP

Formati di importazione per le metriche OTLP

Prezzi e quote

Struttura delle metriche

API Prometheus

API Monitoring

API Prometheus

API Monitoring

Query e formati di importazione

Esegui query sulle metriche OTLP importate utilizzando l'API Prometheus

Interfaccia dello strumento di creazione di query

MQL

PromQL

Esegui query sulle metriche OTLP importate utilizzando l'API Monitoring

Interfaccia dello strumento di creazione di query

MQL

PromQL

Visualizza l'utilizzo e la diagnostica delle metriche in Cloud Monitoring

Raccogliere tracce OTLP

Determinare i ruoli concessi all'account di servizio

Concedi il ruolo Cloud Trace all'account di servizio

Disattiva il ricevitore OTLP

Passaggi successivi

Aggiungi la sezione ricevitore `combined`