Configura le metriche di distribuzione

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina spiega come creare metriche basate su log di distribuzione con Google Cloud Console, l'API Logging e Google Cloud CLI. Per una visione generale delle metriche basate su log, consulta 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 per la distribuzione. Il valore dell'estrattore è lo stesso utilizzato per le etichette definite dall'utente.

Una metrica di distribuzione registra la distribuzione statistica dei valori estratti nei bucket degli istogrammi. I valori estratti non vengono registrati individualmente, ma la loro distribuzione nei bucket configurati viene registrata insieme al conteggio, alla media e alla somma delle deviazioni al quadrato dei valori. Puoi utilizzare il layout predefinito dei bucket dell'istogramma nella distribuzione oppure ottimizzare i confini dei bucket per acquisire approssimativamente i valori.

Creare una metrica di distribuzione

Quando filtri per le voci di log che vuoi conteggiare nella metrica, puoi utilizzare le espressioni regolari. Tieni presente che la lunghezza di un filtro non può superare i 20.000 caratteri.

console

Per creare una metrica contatore basata su log nella console Google Cloud del progetto Google Cloud:

  1. Vai alla pagina Logging > Metrics-based Metrics:

    Vai alle metriche basate su log

  2. Fai clic su Crea metrica. Viene visualizzato il riquadro Crea metrica di log.

  3. Imposta il tipo di metrica: seleziona Distribuzione.

  4. Imposta i seguenti campi nella sezione Dettagli:

    • Nome metrica di log: scegli un nome univoco tra le metriche basate su log nel progetto Cloud. Sono previste alcune limitazioni di denominazione; per i dettagli, consulta la sezione Risoluzione dei problemi.
    • Descrizione: inserisci una descrizione per la metrica.
    • (Facoltativo) Unità: per le metriche di distribuzione, puoi facoltativamente inserire unità quali s, ms e così via. Per ulteriori informazioni, consulta il campo unit di MetricDescriptor.
  5. Definisci il filtro della metrica nella sezione Selezione filtro.

    1. Crea un filtro che raccoglie solo le voci di log che vuoi conteggiare nella metrica utilizzando il linguaggio di query di logging. Puoi anche utilizzare espressioni regolari per creare filtri delle metriche.

    2. Nome campo: inserisci il campo della voce di log contenente il valore della distribuzione. Vengono offerte varie opzioni durante la digitazione. Ad esempio:

       protoPayload.latency
      
    3. (Facoltativo) Espressione di estrazione: se Nome campo contiene sempre un valore numerico convertibile in tipo double, puoi lasciare vuoto questo campo. Altrimenti, specifica un'espressione regolare che estragga il valore di distribuzione numerico dal valore del campo.

      Esempio. Supponiamo che il campo della voce di log latency contenga un numero seguito da ms per millisecondi. Il seguente regexp sceglie il numero senza il suffisso unità:

      ([0-9.]+)
      

      Le parentesi, note come gruppo di acquisizione regexp, identificano la parte della corrispondenza di testo che verrà estratta. Per ulteriori dettagli, consulta la pagina relativa all'utilizzo delle espressioni regolari.

    • (Facoltativo) Avanzate (bucket 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, ne viene fornito uno predefinito. Per ulteriori informazioni, consulta la sezione Bucket a istogrammi in questa pagina.

    Fai clic su Anteprima log per aprire un riquadro contenente le voci di log corrispondenti al filtro.

  6. (Facoltativo) Aggiungi un'etichetta nella sezione Etichette. Per istruzioni sulla creazione delle etichette, consulta la sezione Creare un'etichetta.

  7. Fai clic su Crea metrica per creare la metrica.

gcloud

Per creare una metrica di distribuzione utilizzando Google Cloud CLI, specifica la configurazione completa della metrica utilizzando il flag --config-from-file. Il formato di configurazione è JSON o YAML. Per una descrizione completa della configurazione LogMetric, consulta projects.metrics.

Server

Per creare una metrica di distribuzione, utilizza il metodo projects.metrics.create dell'API Logging. Puoi provare il metodo in Explorer API. Preparare gli argomenti al metodo nel modo seguente:

  1. Imposta il campo parent sul progetto in cui deve essere creata la metrica:

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

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/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 sulle metriche di distribuzione:

  • Sono previste alcune limitazioni di denominazione; per i dettagli, consulta la sezione Risoluzione dei problemi.

  • 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 di confine, L e H, che definiscono i valori più bassi e più alti coperti dal bucket. La larghezza del bucket è H - L. Poiché non possono essere presenti intervalli vuoti tra i bucket, il limite inferiore di un bucket è uguale al limite superiore del bucket precedente, e così via. Per evitare che i limiti rientrino in più di un bucket, un bucket include il suo limite inferiore e quello superiore appartiene al bucket successivo.

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

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 limite oppure elencare i valori limite:

  • Lineare(offset, width, i): ogni bucket ha la stessa larghezza. I limiti sono offset + larghezza * i, per i=0,1,2,...,N. Per ulteriori informazioni sui bucket lineari, consulta il riferimento API.

  • Esponenziale(scale, growth_factor, i): le larghezze del bucket aumentano per valori più elevati. I limiti sono scale * growth_factori, per i=0,1,2,...,N. Per ulteriori informazioni sui bucket esponenziali, consulta il riferimento API.

  • Espresso: elenca tutti i limiti per i bucket nell'array bounds. Il bucket i ha questi 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.

Il modo in cui specifichi i bucket a istogrammi è spiegato nella sezione seguente:

console

Il sottomenu Bucket a istogrammi si apre quando crei una metrica di distribuzione e fai clic su Altro nel modulo Editor delle metriche. Il modulo secondario è illustrato di seguito per il layout dei bucket Lineare:

Bucket a istogrammi

Bucket lineari: compila il modulo del bucket istogramma come segue.

  • Tipo: Lineare
  • Valore iniziale (a): il limite inferiore del primo bucket limitato. Questo valore è chiamato offset nell'API.
  • Numero di bucket (N): il numero di bucket limitati. 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 finito. 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 dei bucket sono i seguenti:

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

Bucket espliciti: compila il modulo dell'istogramma come segue:

  • Tipo: esplicito
  • Limiti (b): un elenco separato da virgole di valori di confine dei bucket finali. Determina anche il numero di bucket e le relative larghezze.

Ad esempio, se l'elenco dei confini è:

0, 1, 2, 5, 10, 20

quindi ci sono cinque bucket limitati con i seguenti intervalli:

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

Bucket esponenziali: compila il modulo dell'istogramma come segue:

  • Tipo: esponenziale
  • Numero di bucket (N): il numero totale di bucket limitati. 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.

Server

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
    }
  },

Nell'esempio precedente vengono creati i bucket seguenti:

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

Bucket espliciti: i limiti sono elencati singolarmente.

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

Nell'esempio precedente vengono creati i bucket seguenti:

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

Bucket esponenziali: i limiti sono scale * growthfactor ^ i, per i=0,1,2, ..., numFiniteBuckets

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

Nell'esempio precedente vengono creati i bucket seguenti:

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

Nuova latenza delle metriche

La nuova metrica viene visualizzata nell'elenco delle metriche e nei relativi menu di Monitoring. 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 progetto Google Cloud o per ispezionare una determinata metrica nel progetto Cloud, procedi come segue:

console

Vai alla pagina Metriche basate su log:

Vai alle metriche basate su log

Nel riquadro Metriche definite dall'utente, vedrai le metriche basate sull'utente definite dall'utente nel progetto Cloud attuale:

Per visualizzare i dati in una metrica basata su log, fai clic sul menu nella riga della metrica e seleziona Visualizza in Metrics Explorer.

gcloud

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

gcloud logging metrics list

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

gcloud logging metrics describe METRIC_NAME

Per ricevere assistenza, utilizza il comando seguente:

gcloud logging metrics --help

Non puoi leggere le metriche di una serie temporale di una metrica da Google Cloud CLI.

Server

Elenca metriche

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

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

Recuperare le definizioni delle metriche

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

  • metricName: il nome della metrica.

    projects/PROJECT_ID/metrics/METRIC_ID
    

Lettura dei dati delle metriche

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

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

logging.googleapis.com/user/METRIC_ID

Aggiorna 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 si fa riferimento nella metrica. Puoi aggiungere nuove etichette alla metrica e modificare le espressioni regolari utilizzate per estrarre i valori per la metrica e le relative etichette.

Non puoi modificare i nomi o i tipi di metriche basate su log definiti 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

  1. Vai alla pagina Metriche basate su log:

    Vai alle metriche basate su log

  2. Fai clic su Modifica metrica nel menu per la metrica basata su log da modificare.

  3. Modifica gli elementi consentiti nella metrica.

  4. Fai clic su Aggiorna metrica.

gcloud

Puoi modificare la descrizione e la query solo per una metrica esistente utilizzando Google Cloud CLI.

Per aggiornare una metrica basata su log, utilizza il comando seguente. Puoi specificare uno o entrambi i flag:

gcloud logging metrics update METRIC_NAME --description=DESCRIPTION --log-filter=FILTER

Per maggiori dettagli, utilizza il comando seguente:

gcloud logging metrics update --help

Server

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 che esatto esattamente come la metrica esistente, ad eccezione delle modifiche e delle aggiunte che vuoi apportare.

Elimina metriche di distribuzione

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

console

  1. Vai alla pagina Metriche basate su log:

    Vai alle metriche basate su log

  2. Seleziona la metrica da eliminare e fai clic su Elimina.

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

gcloud

Utilizza il seguente comando per eliminare una metrica basata su log definita dall'utente nel progetto Cloud corrente:

gcloud logging metrics delete METRIC_NAME

Per maggiori dettagli, utilizza il comando seguente:

gcloud logging metrics delete --help

Server

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

Inoltre, nella pagina Metrica basata su log di Google Cloud Console, 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 progetto Cloud. Per ulteriori dettagli, consulta il riquadro Metriche definite dall'utente.