OpenCensus è un progetto open source gratuito le cui librerie:
- Fornisci assistenza indipendente dal fornitore per la raccolta di dati di metriche e tracce in più lingue.
- Puoi 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 personalizzate, è un'API proprietaria di basso livello. OpenCensus fornisce un'API che segue lo stile della community del linguaggio, insieme a un esportatore che invia i tuoi dati di metrica a Cloud Monitoring tramite l'API Monitoring per te.
Anche OpenCensus offre un buon supporto per il tracciamento delle applicazioni; consulta OpenCensus Tracking per una panoramica generale. Cloud Trace consiglia l'utilizzo di OpenCensus per la strumentazione delle tracce. Per raccogliere dati di metriche e tracce dai servizi, puoi utilizzare 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, è necessario avere un progetto Cloud con fatturazione abilitata. Se necessario, procedi nel seguente modo:
-
Nella pagina del selettore dei progetti in Google Cloud Console, seleziona o crea un progetto Google Cloud.
-
Assicurati che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata su un progetto.
- Assicurati che l'API Monitoring sia abilitata. Per maggiori dettagli, consulta Abilitare l'API Monitoring.
Per le applicazioni in esecuzione al di fuori di Google Cloud, il tuo progetto Cloud deve autenticare la tua applicazione. In genere, la configurazione dell'autenticazione viene creata creando un account di servizio per il progetto e configurando una variabile di ambiente.
Per le applicazioni in esecuzione su un'istanza Amazon Elastic Compute Cloud (Amazon EC2), crea l'account di servizio per il progetto connettore AWS.
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 progetto Google Cloud, devi rendere disponibili le librerie di metriche OpenCensus e l'esportatore Stackdriver. L'esportatore Stackdriver esegue l'esportazione delle metriche raccolte da OpenCensus nel tuo progetto Google Cloud. Puoi quindi utilizzare Cloud Monitoring per registrare o monitorare tali metriche.
Go
Per utilizzare OpenCensus è necessaria la versione 1.11 o successive di Go. Le dipendenze vengono gestite automaticamente per te.
Java
Per Maven, aggiungi quanto segue all'elemento
dependencies
nel file
pom.xml
:
Node.js
- Prima di installare le librerie di core ed esportatori di OpenCensus, assicurati di aver preparato il tuo 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 o del punto di accesso principale dell'applicazione, prima di qualsiasi altro codice:
Python
Installa il core OpenCensus e le librerie dell'esportatore Stackdriver 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.
Scrivi metriche personalizzate 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 OpenCensus Stackdriver.
- Inizializzare l'esportatore Stackdriver.
- Usa l'API OpenCensus per strumenti per il codice.
L'esempio seguente è un programma minimo che scrive i dati di metrica 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
Java
Node.js
Python
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 la sezione Recupero dei descrittori delle metriche per vedere come si realizza la vista OpenCensus come descrittore della metrica Cloud Monitoring.
Puoi quindi utilizzare il nome vista come stringa di ricerca quando selezioni una metrica da rappresentare su grafico.
- Nella console Google Cloud, vai alla pagina Metrics Explorer in Monitoring.
- Nella barra degli strumenti, seleziona la scheda Explorer.
- Seleziona la scheda Configurazione.
- Espandi il menu Seleziona una metrica, inserisci
OpenCensus/task_latency_distribution
nella barra dei filtri e utilizza i sottomenu per selezionare una metrica e un tipo di risorsa 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 Personalizzato.
- Nel menu Metriche attive, seleziona Distribuzione della latenza di attività.
- Fai clic su Applica.
- Facoltativo: per configurare la modalità di visualizzazione dei dati, aggiungi filtri e utilizza i menu Raggruppa per, Aggregatore e di tipo grafico. Per questo grafico, espandi il menu Grafico a linee e seleziona Grafico mappa termica. Per ulteriori informazioni, consulta la pagina Selezionare le metriche quando si utilizza Metrics Explorer.
- Facoltativo: modifica le impostazioni del grafico:
- Per le quote e altre metriche che segnalano un campione al giorno, imposta il periodo di tempo su almeno una settimana e il tipo di grafico su Grafico a barre in pila.
- Per le metriche con valore di distribuzione, imposta il tipo di grafico su Grafico termico.
Il seguente screenshot mostra le serie temporali raccolte dopo l'esecuzione del programma in un ambiente locale:
Ogni barra nella mappa termica rappresenta un'esecuzione del programma e i componenti colorati di ogni barra rappresentano i bucket nella distribuzione della latenza.
Leggi le metriche di OpenCensus in Cloud Monitoring
Utilizzi metriche personalizzate, comprese quelle scritte da OpenCensus, come quelle integrate. Puoi tracciarne i grafici, impostare avvisi, leggerli e monitorarli.
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 utilizzando librerie client, consulta i seguenti documenti:
- Le metriche di navigazione spiegano come elencare ed esaminare le metriche personalizzate e integrate.
- Leggere le metriche spiega come recuperare i dati delle serie temporali da metriche personalizzate e integrate utilizzando l'API Monitoring.
Ad esempio, lo screenshot mostrato nella sezione precedente è di Metrics Explorer. Quando usi gli strumenti di creazione di grafici, ti consigliamo di utilizzare il nome della vista OpenCensus per filtrare l'elenco delle metriche. Per ulteriori informazioni, consulta Selezionare le metriche quando si utilizza Metrics Explorer.
Recupera descrittori della metrica
Per recuperare i dati delle metriche utilizzando direttamente l'API Monitoring, è necessario conoscere i nomi di Cloud Monitoring in cui sono state esportate le metriche OpenCensus. Puoi determinare questi nomi recuperando i descrittori delle metriche creati dall'esportatore e quindi esaminando 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 nella pagina di riferimento, completa i seguenti campi:
Inserisci il nome del tuo 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 sono presenti molti descrittori delle metriche. L'uso del filtro ti consente di 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 dettagli, visita la paginaTimeSeries
.Fai clic su Execute (Esegui).
Di seguito è mostrato il descrittore della metrica restituita:
{ "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 a recuperare manualmente i dati
associati al tipo di metrica. Il valore del campo type
viene mostrato anche nella console Google Cloud quando grafici la metrica.
Recuperare i dati delle metriche
Per recuperare manualmente i dati delle serie temporali da un tipo di metrica:
- Vai alla pagina di riferimento di
timeSeries.list
. Nel widget Prova questa API nella pagina di riferimento, completa i seguenti campi:
- Inserisci il nome del tuo 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 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 valorestartTime
sia precedente al valoreendTime
.Fai clic sul pulsante Esegui.
- Inserisci il nome del tuo 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 della metrica restituita includono quanto segue:
- Informazioni sulla risorsa monitorata in cui sono stati raccolti i dati.
OpenCensus può rilevare automaticamente le risorse monitorate
gce_instance
,k8s_container
eaws_ec2_instance
. Questi dati provengono da un programma in esecuzione su un'istanza di Compute Engine. Per informazioni sull'utilizzo di altre risorse monitorate, consulta la pagina Impostare una 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.
In che modo Monitoring rappresenta le metriche di OpenCensus
È supportato l'utilizzo diretto dell'API Cloud Monitoring per le metriche personalizzate; è descritto in Creare metriche personalizzate con l'API. Di fatto, l'esportatore OpenCensus per Cloud Monitoring utilizza questa API per te. Questa sezione fornisce alcune informazioni sul modo in cui Cloud Monitoring rappresenta le metriche scritte da OpenCensus.
I costrutti usati dall'API OpenCensus sono diversi dai costrutti usati da Cloud Monitoring, così come alcuni utilizzi della terminologia. Dove Cloud Monitoring si riferisce alle "metriche", a volte OpenCensus si riferisce alle "statistiche". Ad esempio, il componente di OpenCensus che invia dati sulle metriche a Cloud Monitoring è chiamato "esportatore di statistiche per Stackdrdiver".
Per una panoramica del modello OpenCensus per le metriche, consulta la pagina Metriche di OpenCensus.
I modelli di dati per le statistiche di OpenCensus e le metriche di Cloud Monitoring non rientrano in una mappatura 1:1 ordinata. Molti di questi concetti sono già presenti in ognuno di essi, ma non sono intercambiabili direttamente.
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 di OpenCensus è una coppia chiave-valore. Un tag OpenCensus corrisponde generalmente a
LabelDescriptor
nell'API Monitoring. I tag consentono di acquisire informazioni contestuali che puoi utilizzare per filtrare e raggruppare le metriche.Una misura di OpenCensus descrive i dati delle metriche da registrare. Un'aggregazione OpenCensus è una funzione applicata ai dati utilizzati per riassumerla. Queste funzioni vengono utilizzate nell'esportazione per determinare
MetricKind
,ValueType
e l'unità indicata nel descrittore della metrica Cloud Monitoring.Una misurazione di 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 di visualizzazione, analogamente a unTimeSeries
nell'API Monitoring.
Passaggi successivi
OpenCensus fornisce la documentazione di riferimento autorevole per l'API delle metriche e per l'esportatore Stackdriver. La seguente tabella fornisce i link ai seguenti documenti di riferimento:
Lingua Documentazione di riferimento per le API Documentazione dell'esportatore Guida rapida Go API Go Statistiche ed esportatori di tracce Metriche Java API Java Esportatore statistiche Metriche NodeJS API Node.js Esportatore statistiche Metriche Python API Python Esportatore statistiche Metriche