Configura le metriche di distribuzione

Questa pagina spiega come creare metriche di distribuzione basate su log utilizzando la console Google Cloud, l'API Logging e Google Cloud CLI. Per una visione generale delle metriche basate su log, vai a Panoramica delle metriche basate su log.

Panoramica

Le metriche di distribuzione richiedono sia un filtro per selezionare le voci di log pertinenti sia un estrattore di valori per acquisire il valore numerico della distribuzione. L'estrattore di valori è dello stesso tipo utilizzato per le etichette definite dall'utente.

Una metrica di distribuzione registra la distribuzione statistica dei valori estratti nei bucket a istogrammi. I valori estratti non vengono registrati singolarmente, ma la loro distribuzione nei bucket configurati viene registrata, insieme a conteggio, media e somma delle deviazioni quadrate dei valori. Puoi utilizzare il layout predefinito dei bucket a istogrammi nella tua distribuzione oppure puoi perfezionare i confini dei bucket per acquisire approssimativamente i valori.

Per ulteriori informazioni su come visualizzare e interpretare le metriche di distribuzione, consulta Metriche di distribuzione.

Prima di iniziare

Per utilizzare le metriche basate su log, devi avere un progetto Google Cloud con fatturazione abilitata:
Assicurati che il tuo ruolo Identity and Access Management includa le autorizzazioni necessarie per creare e visualizzare le metriche basate su log e per creare criteri di avviso. Per maggiori dettagli, consulta Autorizzazioni per le metriche basate su log.

Creare una metrica di distribuzione

La metrica conteggia le voci di log identificate da un filtro fornito. Puoi utilizzare espressioni regolari nel filtro e ti consigliamo di includere un tipo di risorsa. La lunghezza di un filtro non può superare i 20.000 caratteri.

Non inserire informazioni sensibili nel filtro. I filtri vengono trattati come dati di servizio.

Console

Segui questi passaggi per creare una metrica dei contatori basata su log nella console Google Cloud nel tuo progetto Google Cloud:

Nel pannello di navigazione della console Google Cloud, seleziona Logging e poi Metriche basate su log:
Vai a Metriche basate su log
Fai clic su Crea metrica. Viene visualizzato il riquadro Crea metrica di log.
Imposta il Tipo di metrica: seleziona Distribuzione.
Imposta i seguenti campi nella sezione Dettagli:
- Nome metrica di log: scegli un nome univoco tra le metriche basate su log nel progetto Google Cloud. Sono previste alcune restrizioni di denominazione; consulta la sezione Risoluzione dei problemi per i dettagli.
- Descrizione: inserisci una descrizione per la metrica.
- Unità: (facoltativo) per le metriche di distribuzione, puoi facoltativamente inserire unità quali s, ms e così via. Per ulteriori informazioni, consulta il campo unit di MetricDescriptor.
Definisci il filtro delle metriche nella sezione Selezione filtro.
1. Utilizza Seleziona ambito log per scegliere se il filtro ha come target tutti i log del progetto Google Cloud o solo i log di un bucket specifico.
2. Crea un filtro che raccolga solo le voci di log da conteggiare nella metrica utilizzando il linguaggio di query di logging. Puoi anche utilizzare espressioni regolari per creare i filtri della metrica.
3. Nome campo: inserisci il campo di voce di log che contiene il valore della distribuzione. Durante la digitazione vengono offerte delle scelte. Ad esempio:
```
 protoPayload.latency
```
4. Espressione regolare: (facoltativo) se Nome campo contiene sempre un valore numerico convertibile nel tipo double, puoi lasciare vuoto questo campo. Altrimenti, specifica un'espressione regolare che estrae il valore di distribuzione numerica dal valore del campo.
  
  Esempio. Supponiamo che il campo di voce di log latency contenga un numero seguito da ms per millisecondi. La seguente regexp sceglie il numero senza il suffisso di unità:
```
([0-9.]+)
```
  Le parentesi, note come capture group regexp, identificano la parte della corrispondenza di testo che verrà estratta. Per ulteriori dettagli, consulta Utilizzo delle espressioni regolari.
- (Facoltativo) Avanzato (bucket a istogrammi): se fai clic su Avanzate, si apre una sezione del modulo che puoi utilizzare per specificare layout di bucket personalizzati. Se non specifichi i layout dei bucket, viene fornito un layout predefinito. Per ulteriori informazioni, consulta la sezione Bucket a istogrammi in questa pagina.
1. Per vedere quali voci di log corrispondono al filtro, fai clic su Anteprima log.
(Facoltativo) Aggiungi un'etichetta nella sezione Etichette. Per istruzioni sulla creazione di etichette, vedi Creare un'etichetta.
Fai clic su Crea metrica per creare la metrica.

gcloud

Per creare una metrica basata su log di tipo distribuzione, crea un file contenente una rappresentazione della tua definizione di LogMetric in formato JSON o YAML. Quindi utilizza il seguente comando per leggere la configurazione dal file:

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

Per informazioni sulla descrizione dei bucket dell'istogramma per una distribuzione, consulta Bucket istogrammi.

API

Per creare una metrica di distribuzione, utilizza il metodo projects.metrics.create dell'API Logging. Puoi provare il metodo in Explorer API. Prepara gli argomenti del metodo come segue:

Imposta il campo parent sul progetto o bucket in cui deve essere creata la metrica:
- Per una metrica basata su log con ambito progetto, specifica il progetto:
```
projects/PROJECT_ID
```
- Per una metrica basata su log con ambito di bucket, specifica il bucket:
```
projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
```

Imposta il corpo della richiesta su un oggetto LogMetric. Di seguito è riportato un oggetto di esempio per una metrica di distribuzione.

{
  name:        "my-metric"
  description: "Description of my-metric."
  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
  valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",

  labelExtractors: {
    "my-label-1":
      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
    "my-label-2":
      "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
  },
  bucketOptions: { [SEE_BELOW] },

  metricDescriptor: {
      metricKind: DELTA,
      valueType: DISTRIBUTION,
      unit: "ms",

      labels: [
        {
          key: "my-label-1",
          valueType: STRING,
          description: "Description of string my-label-1.",
        },
        {
          key: "my-label-2",
          valueType: INT64,
          description: "Description of integer my-label-2.",
        }
      ]
  },
}

Note:

Si applicano alcune limitazioni di denominazione; consulta la sezione Risoluzione dei problemi per i dettagli.
metricDescriptor: un oggetto MetricDescriptor. metricKind deve essere DELTA. valueType deve essere DISTRIBUTION.

Bucket a istogrammi

Le metriche di distribuzione includono un istogramma che conteggia il numero di valori che rientrano in intervalli specificati (bucket). Una metrica di distribuzione può contenere fino a 200 bucket.

Ogni bucket ha due valori limite, L e H, che definiscono i valori più bassi e più alti coperti dal bucket. La larghezza del bucket è H - L. Poiché non possono esserci intervalli tra i bucket, il limite inferiore di un bucket corrisponde al limite più alto del bucket precedente e così via. Per fare in modo che i limiti non rientrino in più di un bucket, un bucket include il limite inferiore; il limite più alto appartiene al bucket successivo.

Tutti i layout dei bucket possono essere specificati elencando, in ordine crescente, i valori dei confini tra i singoli bucket. Il primo bucket è il bucket di underflow, che conteggia i valori inferiori al primo limite. L'ultimo bucket è il bucket di overflow, che conta i valori maggiori o uguali all'ultimo confine. Gli altri bucket conteggiano valori maggiori o uguali al limite inferiore e inferiori al limite superiore. Se ci sono n valori limite, ci sono n+1 bucket. Escludendo i bucket di underflow e overflow, ci sono n-1 bucket finiti.

Esistono tre modi diversi per specificare i limiti tra i bucket di istogrammi per le metriche di distribuzione. Puoi specificare una formula per i valori del confine o elencare i valori del confine:

Lineare(offset, width, i): tutti i bucket hanno la stessa larghezza. I limiti sono offset + width * i, per i=0,1,2,...,N. Per ulteriori informazioni sui bucket lineari, consulta la documentazione di riferimento per le API.
Esponenziale(scale, growth_factor, i): le larghezze dei bucket aumentano per valori più elevati. I limiti sono scale * growth_factorⁱ, per i=0,1,2,...,N. Per ulteriori informazioni sui bucket esponenziali, consulta la documentazione di riferimento per le API.
Esplicita: elenchi tutti i limiti per i bucket nell'array bounds. Il bucket i ha i seguenti limiti:

Limite superiore: limiti[i] per (0 <= i < N-1)
Limite inferiore: limiti[i - 1] per (1 <= i < N)

Per ulteriori informazioni sui bucket espliciti, consulta la documentazione di riferimento per le API.

La procedura per specificare i bucket a istogrammi viene spiegata nella sezione seguente:

Console

Il sottomenu Bucket istogramma si apre quando crei una metrica di distribuzione e fai clic su Altro nel modulo Editor metriche. Di seguito è mostrato il modulo secondario per il layout del bucket Lineare:

Bucket a istogrammi

Bucket lineari: compila il modulo del bucket a istogrammi come segue.

Tipo: Lineare
Valore iniziale (a): il limite inferiore del primo bucket finito. Questo valore è chiamato offset nell'API.
Numero di bucket (N): il numero di bucket finiti. Il valore deve essere maggiore o uguale a 0.
Larghezza del bucket (b): la differenza tra il limite superiore e il limite inferiore in ogni bucket limitato. Il valore deve essere maggiore di 0.

Ad esempio, se il valore iniziale è 5, il numero di bucket è 4 e la larghezza del bucket è 15, gli intervalli di bucket sono i seguenti:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

Bucket espliciti: compila il formato del bucket a istogramma come segue:

Tipo: Esplicita
Limiti (b): un elenco separato da virgole dei valori dei confini dei bucket finiti. Questo determina anche il numero di bucket e la relativa larghezza.

Ad esempio, se l'elenco dei confini è:

0, 1, 2, 5, 10, 20

esistono cinque bucket finiti con i seguenti intervalli:

(-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)

Bucket esponenziali: compila il formato del bucket a istogrammi come segue:

Tipo: Esponenziale
Numero di bucket (N): il numero totale di bucket finiti. Il valore deve essere maggiore di 0.
Scala lineare (a): la scala lineare per i bucket. Il valore deve essere maggiore di 0.
Fattore di crescita esponenziale (b): il fattore di crescita esponenziale per i bucket. Il valore deve essere maggiore di 1.

Ad esempio, se N=4, a=3 e b=2, gli intervalli dei bucket sono i seguenti:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

Per ulteriori informazioni sui bucket, consulta BucketOptions nell'API Cloud Monitoring.

API

Il layout facoltativo del bucket è specificato dal campo bucketOptions nell'oggetto LogMetric fornito a projects.metrics.create. Per l'oggetto LogMetric completo, consulta Creare una metrica di distribuzione in questa pagina. Di seguito sono riportate le aggiunte ai layout dei bucket:

Bucket lineari:

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },

L'esempio precedente crea i seguenti bucket:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

Bucket espliciti: i confini sono elencati singolarmente.

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },

L'esempio precedente crea i seguenti bucket:

(-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)

Bucket esponenziali: i confini sono scale * growthFactor ^ i, per i=0,1,2, ..., numFiniteBucket

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

L'esempio precedente crea i seguenti bucket:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

Nuova latenza metrica

La nuova metrica viene visualizzata subito nell'elenco delle metriche e nei menu di Monitoring pertinenti. Tuttavia, potrebbe essere necessario fino a un minuto prima che la metrica inizi a raccogliere dati per le voci di log corrispondenti.

Esaminare le metriche di distribuzione

Per elencare le metriche basate su log definite dall'utente nel tuo progetto Google Cloud o per ispezionare una determinata metrica nel tuo progetto Google Cloud, segui questi passaggi:

Console

Nel pannello di navigazione della console Google Cloud, seleziona Logging e poi Metriche basate su log:
Vai a Metriche basate su log
Nel riquadro Metriche definite dall'utente, vedrai le metriche basate su log definite dall'utente nell'attuale progetto Google Cloud:
Per visualizzare i dati in una metrica basata su log, fai clic su Menu nella riga della metrica e seleziona Visualizza in Metrics Explorer.

gcloud

Per elencare le metriche basate su log definite dall'utente nel tuo progetto Google Cloud, utilizza il seguente comando:

gcloud logging metrics list

Per visualizzare una metrica basata su log definita dall'utente nel tuo progetto Google Cloud, utilizza il seguente comando:

gcloud logging metrics describe METRIC_NAME

Per ricevere assistenza, utilizza il comando seguente:

gcloud logging metrics --help

Non puoi leggere i dati delle serie temporali di una metrica da Google Cloud CLI.

API

Elenca metriche

Per elencare le metriche basate su log definite dall'utente in un progetto Google Cloud, utilizza il metodo API projects.metrics.list. Inserisci i parametri del metodo come segue:

parent: il nome della risorsa del progetto Google Cloud projects/PROJECT_ID.
pageSize: il numero massimo di risultati.
pageToken: restituisce la pagina successiva dei risultati. Per informazioni sull'utilizzo dei token di pagina, consulta projects.metrics.list.

Recupero delle definizioni delle metriche

Per recuperare una singola metrica basata su log definita dall'utente, utilizza il metodo API projects.metrics.get. Inserisci i parametri del metodo come segue:

metricName: il nome della risorsa della metrica:
```
projects/PROJECT_ID/metrics/METRIC_ID
```

Lettura dei dati delle metriche

Per leggere i dati delle serie temporali in una metrica basata su log, utilizza projects.timeseries.list nell'API Cloud Monitoring. Per maggiori dettagli sui dati delle serie temporali, consulta la sezione Lettura di serie temporali.

Per leggere una singola metrica basata su log definita dall'utente, compila i parametri del metodo con questo tipo di metrica e identificatore:

logging.googleapis.com/user/METRIC_ID

Aggiorna le metriche di distribuzione

Puoi modificare una metrica basata su log definita dall'utente per cambiarne la descrizione, il filtro e i nomi dei campi a cui viene fatto riferimento nella metrica. Puoi aggiungere nuove etichette alla metrica e modificare le espressioni regolari utilizzate per estrarre i valori della metrica e delle relative etichette. Se utilizzi una metrica con ambito bucket, puoi anche aggiornare il bucket della metrica.

Non puoi modificare i nomi o i tipi delle metriche basate su log definite dall'utente o le relative etichette e non puoi eliminare le etichette esistenti in una metrica basata su log.

Per modificare una metrica basata su log:

Console

Nel pannello di navigazione della console Google Cloud, seleziona Logging e poi Metriche basate su log:
Vai a Metriche basate su log
Fai clic su Modifica metrica nel Menu per la metrica basata su log da modificare.
Modifica gli elementi consentiti nella metrica.
Fai clic su Aggiorna metrica.

gcloud

Utilizza Google Cloud CLI per modificare la descrizione, la query di filtro e il bucket di una metrica di conteggio. Puoi aggiornare uno o tutti i campi contemporaneamente.

gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

Se modifichi il bucket associato a una metrica con ambito bucket, i dati delle metriche raccolti prima della modifica non rifletteranno più la configurazione corrente. I dati delle metriche raccolti per il bucket precedente non vengono rimossi.

Per aggiornare le metriche di distribuzione o altri campi delle metriche dei contatori, escludendo METRIC_NAME, crea un file contenente la specifica rivista del tuo LogMetric in formato JSON o YAML. Quindi, aggiorna la metrica chiamando il comando update con il campo --config-from-file, sostituendo FILENAME con il nome del tuo file JSON o YAML:

gcloud logging update METRIC_NAME --config-from-file FILENAME

Per maggiori dettagli, utilizza il comando seguente:

gcloud logging metrics update --help

API

Per modificare una metrica basata su log, utilizza il metodo projects.metrics.update nell'API. Imposta i campi come segue:

metricName: il nome completo della risorsa della metrica:

projects/PROJECT_ID/metrics/METRIC_ID

Ad esempio:

projects/my-gcp-project/metrics/my-error-metric

Nel corpo della richiesta, includi un oggetto LogMetric esattamente uguale alla metrica esistente, tranne per le modifiche e le aggiunte che vuoi apportare.

Elimina metriche di distribuzione

Per eliminare una metrica basata su log definita dall'utente:

Console

Nel pannello di navigazione della console Google Cloud, seleziona Logging e poi Metriche basate su log:
Vai a Metriche basate su log
Seleziona la metrica da eliminare e fai clic su Elimina.

In alternativa, fai clic su Elimina metrica nel menu della metrica basata su log da eliminare.

gcloud

Utilizza il seguente comando per eliminare una metrica basata su log definita dall'utente nell'attuale progetto Google Cloud:

gcloud logging metrics delete METRIC_NAME

For more details, use the following command:

gcloud logging metrics delete --help

API

Per eliminare una metrica basata su log definita dall'utente, utilizza il metodo projects.metrics.delete nell'API.

Inoltre, nella pagina Metrica basata su log della console Google Cloud, il riquadro Metriche definite dall'utente dell'interfaccia delle metriche basate su log offre ulteriori funzionalità per aiutarti a gestire le metriche definite dall'utente nel tuo progetto Google Cloud. Per i dettagli, consulta Riquadro delle metriche definite dall'utente.