OpenCensus è un progetto open source gratuito le cui librerie:
- Fornisci un'assistenza indipendente dal fornitore per la raccolta di dati di metriche e traccia in più lingue.
- Può esportare i dati raccolti in varie applicazioni di backend, tra cui Cloud Monitoring, utilizzando gli esportatori.
Sebbene Cloud Monitoring fornisca un'API che supporta la definizione e la raccolta di metriche definite dall'utente, si tratta di un'API proprietaria di basso livello. OpenCensus fornisce un'API che segue lo stile della community linguistica, insieme a un esportatore che invia i dati delle metriche a Cloud Monitoring tramite l'API Monitoring per te.
OpenCensus offre inoltre un buon supporto per il tracciamento delle applicazioni; per una panoramica generale, consulta la pagina relativa al tracciamento di OpenCensus. Cloud Trace consiglia di utilizzare OpenCensus per la strumentazione di traccia. Per raccogliere i dati delle metriche e di traccia dai tuoi servizi, puoi usare un'unica distribuzione di librerie. Per informazioni sull'utilizzo di OpenCensus con Cloud Trace, consulta Librerie client per Trace.
Prima di iniziare
Per utilizzare Cloud Monitoring, devi avere un progetto Google Cloud in cui la fatturazione sia abilitata. Se necessario, procedi nel seguente modo:
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.
- Assicurati che l'API Monitoring sia abilitata. Per maggiori dettagli, consulta Abilitazione dell'API Monitoring.
Per le applicazioni in esecuzione al di fuori di Google Cloud, il progetto Google Cloud deve autenticare l'applicazione. In genere, l'autenticazione viene configurata creando un account di servizio per il progetto e configurando una variabile di ambiente.
Per le applicazioni eseguite su un'istanza Amazon Elastic Compute Cloud (Amazon EC2), crea l'account di servizio per il progetto del connettore AWS dell'istanza.
Per informazioni sulla creazione di un account di servizio, consulta la guida introduttiva all'autenticazione.
Installare OpenCensus
Per utilizzare le metriche raccolte da OpenCensus nel tuo progetto Google Cloud, devi rendere disponibili per la tua applicazione le librerie delle metriche di OpenCensus e l'utilità di esportazione di Stackdriver. Stackdriver Exporter esporta le metriche raccolte da OpenCensus nel tuo progetto Google Cloud. Puoi quindi utilizzare Cloud Monitoring per creare un grafico o monitorare queste metriche.
Go
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Per utilizzare OpenCensus è necessario Go 1.11 o versioni successive. Le dipendenze vengono gestite automaticamente.Java
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Per Maven, aggiungi quanto segue all'elementodependencies
del file pom.xml
:
Node.js
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
- Prima di installare le librerie di esportazione principali e di esportazione di OpenCensus, assicurati di aver preparato l'ambiente per lo sviluppo di Node.js.
- Il modo più semplice per installare OpenCensus è con
npm:
npm install @opencensus/core npm install @opencensus/exporter-stackdriver
- Inserisci le istruzioni
require
mostrate di seguito nella parte superiore dello script principale o del punto di ingresso dell'applicazione, prima di qualsiasi altro codice:
Python
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Installa le librerie del core di OpenCensus e di Stackdriver Exporter utilizzando il seguente comando:pip install -r opencensus/requirements.txt
Il file requirements.txt
si trova nel repository GitHub per questi esempi,
python-docs-samples.
Scrivere metriche definite dall'utente con OpenCensus
La strumentazione del codice per l'utilizzo di OpenCensus per le metriche prevede tre passaggi:
- Importa le statistiche di OpenCensus e i pacchetti di esportazione di Stackdriver OpenCensus.
- Inizializza l'utilità di esportazione di Stackdriver.
- Usa l'API OpenCensus per instrumentare il tuo codice.
L'esempio seguente è un programma minimo che scrive dati delle metriche utilizzando OpenCensus. Il programma esegue un loop e raccoglie le misure di latenza; al termine del ciclo esporta le statistiche in Cloud Monitoring ed esce:
Go
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Il programma crea una vista OpenCensus denominata task_latency_distribution
. Questa stringa diventa parte del nome della metrica quando viene esportata in Cloud Monitoring. Consulta Recupero dei descrittori delle metriche per vedere come la vista OpenCensus viene realizzata come descrittore della metrica di Cloud Monitoring.
Puoi quindi utilizzare il nome della vista come stringa di ricerca quando selezioni una metrica da rappresentare in un grafico.
-
Nella console Google Cloud, vai alla pagina leaderboard 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
OpenCensus/task_latency_distribution
nella barra dei filtri e utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:- Nel menu Risorse attive, seleziona la risorsa monitorata. Se esegui il programma in un ambiente locale, seleziona Globale.
- Nel menu Categorie di metriche attive, seleziona Personalizzata.
- Nel menu Metriche attive, seleziona Distribuzione della latenza delle attività.
- Fai clic su Applica.
Il seguente screenshot mostra le serie temporali raccolte dopo l'esecuzione del programma in un ambiente locale:
Ogni barra della mappa termica rappresenta un'esecuzione del programma e i componenti colorati di ogni barra rappresentano i bucket nella distribuzione della latenza.
Leggere le metriche OpenCensus in Cloud Monitoring
Puoi usare metriche definite dall'utente, incluse quelle scritte da OpenCensus, come le metriche integrate. Puoi creare grafici, impostare avvisi, leggere e monitorare in altro modo.
Questa sezione illustra come utilizzare Explorer API per leggere i dati delle metriche. Per informazioni su come leggere i dati delle metriche con l'API Cloud Monitoring o le librerie client, consulta i seguenti documenti:
- Elenco dei tipi di metriche e risorse spiega come elencare ed esaminare i tipi di risorse e di metriche nel sistema.
- Recupera i dati delle serie temporali spiega come recuperare i dati delle serie temporali dalle metriche utilizzando l'API Monitoring.
Ad esempio, lo screenshot mostrato nella sezione precedente proviene daMetrics Explorere. Quando utilizzi gli strumenti di creazione dei grafici, ti consigliamo di utilizzare il nome della vista OpenCensus per filtrare l'elenco delle metriche. Per saperne di più, consulta Selezionare le metriche quando si utilizza Esplora metriche.
Recupera i descrittori delle metriche
Per recuperare i dati delle metriche utilizzando direttamente l'API Monitoring, devi conoscere i nomi di Cloud Monitoring in cui sono state esportate le metriche OpenCensus. Per determinare questi nomi, puoi recuperare i descrittori delle metriche creati dall'esportatore e poi esaminare il campo type
. Per maggiori dettagli sui descrittori delle metriche, consulta
MetricDescriptor
.
Per visualizzare i descrittori delle metriche creati per le metriche esportate:
- Vai alla pagina di riferimento
metricDescriptors.list
. Nel widget Prova questa API della pagina di riferimento, completa i seguenti campi:
Inserisci il nome del progetto nel campo
name
. Utilizza la seguente struttura del nomeprojects/PROJECT_ID
. Questo documento utilizza un progetto con IDa-gcp-project
.Inserisci un filtro nel campo
filter
. Un progetto contiene molti descrittori delle metriche. L'applicazione di filtri consente di eliminare i descrittori che non sono di interesse.Ad esempio, poiché il nome della vista OpenCensus diventa parte del nome della metrica, puoi aggiungere un filtro come il seguente:
metric.type=has_substring("task_latency_distribution")
La chiave
metric.type
è un campo di un tipo incorporato in una serie temporale. Per informazioni dettagliate, visita la paginaTimeSeries
.Fai clic su Execute (Esegui).
Di seguito viene mostrato il descrittore della metrica restituito:
{ "metricDescriptors": [ { "name": "projects/a-gcp-project/metricDescriptors/custom.googleapis.com/opencensus/task_latency_distribution", "labels": [ { "key": "opencensus_task", "description": "Opencensus task identifier" } ], "metricKind": "CUMULATIVE", "valueType": "DISTRIBUTION", "unit": "ms", "description": "The distribution of the task latencies", "displayName": "OpenCensus/task_latency_distribution", "type": "custom.googleapis.com/opencensus/task_latency_distribution" } ] }
Questa riga nel descrittore della metrica indica il nome del tipo di metrica in Cloud Monitoring:
"type": "custom.googleapis.com/opencensus/task_latency_distribution"
Ora hai a disposizione le informazioni necessarie per recuperare manualmente i dati associati al tipo di metrica. Il valore del campo type
viene visualizzato anche
nella console Google Cloud quando crei un grafico della metrica.
Recupera i dati delle metriche
Per recuperare manualmente i dati delle serie temporali da un tipo di metrica:
- Vai alla
timeSeries.list
pagina di riferimento. Nel widget Prova questa API della pagina di riferimento, completa i seguenti campi:
- Inserisci il nome del progetto nel campo
name
. Utilizza la seguente struttura del nomeprojects/PROJECT_ID
. Nel campo
filter
, inserisci il seguente valore:metric.type="custom.googleapis.com/opencensus/task_latency_distribution"
Inserisci i valori nei campi
interval.startTime
einterval.endTime
. Questi valori devono essere inseriti come timestamp, ad esempio2018-10-11T15:48:38-04:00
. Assicurati che il valore distartTime
sia precedente al valore diendTime
.Fai clic sul pulsante Esegui.
- Inserisci il nome del progetto nel campo
Di seguito viene mostrato il risultato di uno di questi recuperi:
{ "timeSeries": [ { "metric": { "labels": { "opencensus_task": "java-3424@docbuild" }, "type": "custom.googleapis.com/opencensus/task_latency_distribution" }, "resource": { "type": "gce_instance", "labels": { "instance_id": "2455918024984027105", "zone": "us-east1-b", "project_id": "a-gcp-project" } }, "metricKind": "CUMULATIVE", "valueType": "DISTRIBUTION", "points": [ { "interval": { "startTime": "2019-04-04T17:49:34.163Z", "endTime": "2019-04-04T17:50:42.917Z" }, "value": { "distributionValue": { "count": "100", "mean": 2610.11, "sumOfSquaredDeviation": 206029821.78999996, "bucketOptions": { "explicitBuckets": { "bounds": [ 0, 100, 200, 400, 1000, 2000, 4000 ] } }, "bucketCounts": [ "0", "0", "1", "6", "13", "15", "44", "21" ] } } } ] }, [ ... data from additional program runs deleted ...] ] }
I dati delle metriche restituiti includono quanto segue:
- Informazioni sulla risorsa monitorata su cui sono stati raccolti i dati.
OpenCensus può rilevare automaticamente
gce_instance
,k8s_container
eaws_ec2_instance
risorse monitorate. Questi dati provengono da un programma eseguito su un'istanza di Compute Engine. Per informazioni sull'utilizzo di altre risorse monitorate, consulta Impostare la risorsa monitorata per l'esportatore. - Descrizione del tipo di metrica e del tipo di valori.
- I punti dati effettivi raccolti nell'intervallo di tempo richiesto.
Rappresentazione delle metriche di OpenCensus da parte di Monitoring
È supportato l'uso diretto dell'API Cloud Monitoring per metriche definite dall'utente; il suo utilizzo è descritto in Creare metriche definite dall'utente con l'API. Infatti, l'esportatore OpenCensus per Cloud Monitoring utilizza questa API per te. Questa sezione fornisce alcune informazioni su come Cloud Monitoring rappresenta le metriche scritte da OpenCensus.
I costrutti utilizzati dall'API OpenCensus sono diversi da quelli utilizzati da Cloud Monitoring, così come un certo uso della terminologia. Quando Cloud Monitoring fa riferimento a "metriche", OpenCensus a volte fa riferimento a "statistiche". Ad esempio, il componente di OpenCensus che invia i dati delle metriche a Cloud Monitoring è chiamato "esportatore di statistiche per Stackdrdiver".
Per una panoramica del modello OpenCensus per le metriche, vedi Metriche OpenCensus.
I modelli dei dati per le statistiche di OpenCensus e le metriche di Cloud Monitoring non rientrano in una mappatura 1:1. Molti degli stessi concetti esistono in ognuno di essi, ma non sono direttamente intercambiabili.
Una vista OpenCensus è analoga a
MetricDescriptor
nell'API Monitoring. Una vista descrive come raccogliere e aggregare le singole misurazioni. I tag sono inclusi in tutte le misurazioni registrate.Un tag OpenCensus è una coppia chiave-valore. Un tag OpenCensus corrisponde in genere a
LabelDescriptor
nell'API Monitoring. I tag consentono di acquisire informazioni contestuali che puoi utilizzare per filtrare e raggruppare le metriche.Una misura OpenCensus descrive i dati delle metriche da registrare. Un'aggregazione di OpenCensus è una funzione applicata ai dati utilizzati per riepilogarli. Queste funzioni vengono utilizzate nell'esportazione per determinare
MetricKind
,ValueType
e unità segnalata nel descrittore della metrica di Cloud Monitoring.Una misurazione OpenCensus è un punto dati raccolto. Le misurazioni devono essere aggregate in visualizzazioni. In caso contrario, le singole misurazioni vengono eliminate. Una misurazione OpenCensus è analoga a una
Point
nell'API Monitoring. Quando le misurazioni vengono aggregate nelle viste, i dati aggregati vengono archiviati come dati delle viste, in modo analogo aTimeSeries
nell'API Monitoring.
Passaggi successivi
OpenCensus fornisce la documentazione di riferimento autorevole per l'API delle metriche e per l'esportatore di Stackdriver. La tabella seguente fornisce i link ai seguenti documenti di riferimento:
Lingua Documentazione di riferimento per le API Documentazione dell'esportatore Guida rapida Go API Go Esportatori di statistiche e tracce Metriche Java API Java Esportazione delle statistiche Metriche NodeJS API NodeJS Esportazione delle statistiche Metriche Python API Python Esportazione delle statistiche Metriche