OpenCensus è un progetto open source gratuito le cui librerie:
- Offri un supporto indipendente dal fornitore per la raccolta di dati di traccia e metriche 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, è 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 tue metriche a Cloud Monitoring tramite l'API Monitoring.
OpenCensus offre inoltre un buon supporto per il tracciamento delle applicazioni; consulta OpenCensus Tracciamento per una panoramica generale. Cloud Trace consiglia di utilizzare OpenCensus per la strumentazione di traccia. Per raccogliere dati di metriche e tracce dai 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 con fatturazione abilitata. Se necessario:
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
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.
Installa OpenCensus
Per utilizzare le metriche raccolte da OpenCensus nel tuo progetto Google Cloud, devi rendere disponibili le librerie di metriche OpenCensus e l'utilità di esportazione Stackdriver per la tua applicazione. L'esportatore Stackdriver esporta le metriche raccolte da OpenCensus nel tuo progetto Google Cloud. e poi utilizzare Cloud Monitoring per monitorare o rappresentare graficamente le metriche.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Per utilizzare OpenCensus è necessaria la versione 1.11 o successive di Go. Le dipendenze vengono gestite automaticamente.Java
Per eseguire l'autenticazione 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
nel tuo
file pom.xml
:
Node.js
Per eseguire l'autenticazione 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 core ed degli esportatori OpenCensus, assicurati di aver preparato l'ambiente per lo sviluppo in 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 eseguire l'autenticazione 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 OpenCensus e di Stackdriver Exporter utilizzando questo 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 utilizzare OpenCensus per le metriche prevede tre passaggi:
- Importa le statistiche OpenCensus e i pacchetti dell'utilità di esportazione OpenCensus Stackdriver.
- Inizializza l'esportatore Stackdriver.
- Usa l'API OpenCensus per instrumentare il codice.
L'esempio seguente è un programma minimo che scrive dati di metriche utilizzando OpenCensus. Il programma esegue un loop e raccoglie le misure di latenza e, al termine del loop, esporta le statistiche in Cloud Monitoring ed esce:
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione 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 scoprire come viene realizzata la vista OpenCensus come descrittore della metrica di Cloud Monitoring.
Puoi quindi utilizzare il nome della vista come stringa di ricerca quando selezioni una metrica da tracciare.
-
Nella console Google Cloud, vai alla pagina Metrics Explorer leaderboard:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato il cui sottotitolo è Monitoring.
- Nell'elemento Metrica, espandi il menu Seleziona una metrica, inserisci
OpenCensus/task_latency_distribution
nella barra dei filtri, poi 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 su 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 ciascuna barra rappresentano i bucket nella distribuzione della latenza.
Lettura delle metriche di OpenCensus in Cloud Monitoring
Utilizzi 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 utilizzando l'API Cloud Monitoring o le librerie client, consulta i seguenti documenti:
- Elenca metriche e tipi di risorse spiega come elencare ed esaminare i tipi di risorse e di metriche nel tuo sistema.
- La sezione Recupero dei 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 da Metrics Explorer. Quando usi gli strumenti di creazione di grafici, ti consigliamo di usare il nome della vista OpenCensus per filtrare l'elenco delle metriche. Per maggiori informazioni, consulta Selezionare le metriche quando si utilizza Metrics Explorer.
Recupera i descrittori della metrica
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 di OpenCensus. Puoi determinare questi nomi recuperando i descrittori delle metriche creati dall'esportatore e osservando 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 di
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 dei nomiprojects/PROJECT_ID
. Questo documento utilizza un progetto con IDa-gcp-project
.Inserisci un filtro nel campo
filter
. In un progetto esistono molti descrittori delle metriche. Con i filtri puoi eliminare i descrittori che non ti interessano.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 in un tipo incorporato in una serie temporale. Per informazioni dettagliate, visita la paginaTimeSeries
.Fai clic su Execute (Esegui).
Di seguito è riportato 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 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.
Recuperare i dati delle metriche
Per recuperare manualmente i dati delle serie temporali da un tipo di metrica:
- Vai alla pagina di riferimento
timeSeries.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 dei nomiprojects/PROJECT_ID
. Nel campo
filter
, inserisci il seguente valore:metric.type="custom.googleapis.com/opencensus/task_latency_distribution"
Inserisci i valori per i campi
interval.startTime
einterval.endTime
. Questi valori devono essere inseriti come timestamp, ad esempio2018-10-11T15:48:38-04:00
. Assicurati che il valorestartTime
sia precedente al valore diendTime
.Fai clic sul pulsante Esegui.
- Inserisci il nome del progetto nel campo
Di seguito viene mostrato il risultato di un recupero:
{ "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:
- 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 Compute Engine. Per informazioni sull'utilizzo di altre risorse monitorate, consulta Impostare la risorsa monitorata per l'utilità di esportazione. - Descrizione del tipo di metrica e del tipo dei valori.
- I punti dati effettivi raccolti nell'intervallo di tempo richiesto.
In che modo Monitoring rappresenta le metriche di OpenCensus
È supportato l'utilizzo diretto dell'API Cloud Monitoring per le metriche definite dall'utente; il suo utilizzo è descritto in Creare metriche definite dall'utente con l'API. L'utilità di esportazione OpenCensus per Cloud Monitoring utilizza infatti questa API per conto tuo. 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 alcuni usi della terminologia. Mentre Cloud Monitoring fa riferimento a "metriche", OpenCensus a volte si riferisce alle "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, consulta Metriche di OpenCensus.
I modelli dei dati per le statistiche di OpenCensus e le metriche di Cloud Monitoring non rientrano in un mapping 1:1 accurato. Molti degli stessi concetti esistono in ciascuno, ma non sono direttamente intercambiabili.
Una vista OpenCensus è analoga a
MetricDescriptor
nell'API Monitoring. Una vista descrive come raccogliere e aggregare misurazioni individuali. I tag sono inclusi in tutte le misurazioni registrate.Un tag OpenCensus è una coppia chiave-valore. In genere, un tag OpenCensus corrisponde a
LabelDescriptor
nell'API Monitoring. I tag consentono di acquisire informazioni contestuali che puoi usare 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 riassumirli. Queste funzioni vengono utilizzate durante l'esportazione per determinare
MetricKind
,ValueType
e l'unità riportata nel descrittore della metrica di Cloud Monitoring.Una misurazione OpenCensus è un punto dati raccolto. Le misurazioni devono essere aggregate in viste. 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 a unaTimeSeries
nell'API Monitoring.
Passaggi successivi
OpenCensus fornisce la documentazione di riferimento autorevole per l'API Metrics e per l'esportatore Stackdriver. La seguente tabella fornisce i link a questi 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 statistiche Metriche NodeJS API NodeJS Esportazione statistiche Metriche Python API Python Esportazione statistiche Metriche