Configura le metriche di distribuzione

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

Panoramica

Le metriche di distribuzione richiedono un filtro per selezionare le voci di log pertinenti e un estrattore di valori per recuperare il valore numerico per la distribuzione. Il valore estrattore è dello stesso tipo utilizzato per le etichette definite dall'utente.

Una metrica di distribuzione registra la distribuzione statistica degli elementi estratti nei bucket di istogrammi. I valori estratti non vengono registrati singolarmente, ma la loro distribuzione nei bucket configurati registrate, insieme al conteggio, alla media e alla somma delle deviazioni al quadrato e i relativi valori. Puoi utilizzare il layout predefinito dei bucket degli istogrammi distribuzione on-premise, oppure puoi perfezionare i bucket limiti circa acquisire i valori.

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

Prima di iniziare

  1. Per usare le metriche basate su log, devi avere un progetto Google Cloud con Fatturazione abilitata:

    1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

    2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    3. Make sure that billing is enabled for your Google Cloud project.

    4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    5. Make sure that billing is enabled for your Google Cloud project.

  2. Assicurati che il ruolo Identity and Access Management includa le autorizzazioni necessarie per creare e visualizzare metriche basate su log e creare criteri di avviso. Per maggiori dettagli, vedi Autorizzazioni per le metriche basate su log.

Creare una metrica di distribuzione

La metrica conta le voci di log identificate da un filtro che fornisci. Puoi utilizzare espressioni regolari nel filtro. Consigliamo di includere un tipo di risorsa. La di un filtro non può superare i 20.000 caratteri.

Non inserire informazioni sensibili nel filtro. I filtri vengono trattati come dati dei servizi.

Console

Per creare una metrica del contatore basata su log nel Console Google Cloud nel tuo progetto Google Cloud:

  1. Nella console Google Cloud, vai alla pagina Metriche basate su log:

    Vai a Metriche basate su log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  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 i di metriche basate su log nel tuo progetto Google Cloud. Alcune denominazioni sono previste limitazioni; vedi Risoluzione dei problemi per maggiori dettagli.
    • Descrizione: inserisci una descrizione per la metrica.
    • (Facoltativo) Unità: per le metriche di distribuzione, puoi scegliere di inserisci le unità, ad esempio s e ms. Per ulteriori informazioni, consulta Campo unit del MetricDescriptor.

  5. Definisci il filtro delle metriche nella sezione Selezione filtro.

    1. Utilizza il menu Seleziona progetto o bucket di log per scegliere se l'istanza metrica conteggia le voci di log nel progetto Google Cloud o solo quelle voci di log in uno specifico bucket di log.

    2. Crea un filtro che raccolga solo le voci di log che vuoi conteggiare nella metrica utilizzando il linguaggio di query di Logging. Puoi anche utilizzare le espressioni regolari per creare filtri corretti.

    3. Nome campo: inserisci il campo di voce di log contenente la il valore della distribuzione. Durante la digitazione ti vengono offerte delle opzioni. Per esempio:

      protoPayload.latency

    4. Espressione regolare: (facoltativo) se il campo Nome campo è sempre contiene un valore numerico convertibile nel tipo double, puoi lascia questo campo vuoto. Altrimenti, specifica un'espressione regolare che estrae il valore della distribuzione numerica dal valore del campo.

      Esempio. Supponiamo che la tua voce di log latency contiene un numero seguito da ms per i millisecondi. La seguente regexp sceglie il numero senza il suffisso dell'unità:

      ([0-9.]+)

      Le parentesi, note come gruppo di acquisizione regexp, identificano le parte della corrispondenza di testo che verrà estratta. Consulta utilizzando le espressioni regolari per maggiori dettagli.

    • Avanzate (bucket di istogrammi): (facoltativo) fai clic su Avanzate. apre una sezione del modulo che puoi usare per specificare un bucket personalizzato layout. Se non specifichi i layout dei bucket, viene utilizzato un bucket predefinito viene fornito un layout. Per ulteriori informazioni, consulta la sezione Bucket degli istogrammi in questa pagina.
    1. Per vedere quali voci di log corrispondono al filtro, fai clic su Anteprima log.

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

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

gcloud

Per creare una metrica basata su log di tipo distribuzione, crea un file che contenga una rappresentazione della definizione di LogMetric in formato JSON o YAML. Quindi utilizza questo comando per leggere configurazione dal tuo file:

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

Per informazioni sulla descrizione dei bucket di istogrammi per una distribuzione, consulta Bucket degli 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 come segue:

  1. Imposta il campo parent sul progetto o sul bucket in cui la metrica è da creare:

    • Per una metrica basata su log con ambito a livello di 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

  2. Imposta il corpo della richiesta su un oggetto LogMetric. La persona che segue è un 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. vedi Risoluzione dei problemi per maggiori 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 negli intervalli specificati (bucket). Puoi avere fino a 200 bucket in un metrica di distribuzione.

Ogni bucket ha due valori di confine, L e H, che definiscono il valore più basso i valori più elevati coperti dal bucket. La larghezza del bucket è H - L. Poiché non possono esserci spazi vuoti tra i bucket, il limite inferiore di un bucket è corrisponde al limite più alto del bucket precedente e così via. Perciò i confini non rientrano in più di un bucket, un bucket include boundary; il limite superiore appartiene al bucket successivo.

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

Esistono tre modi diversi per specificare il limite tra bucket di istogrammi per le metriche di distribuzione. Specifica una formula per i valori limite o elencali:

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

  • Exponential(scale, growth_factor, i): aumento delle larghezze del bucket per valori più alti. I limiti sono scale * growth_factori, per i=0,1,2,...,N. Per saperne di più sui bucket esponenziali, consulta Riferimento API.

  • Esplicito: elenca tutti i limiti per i bucket nel un array bounds. Il bucket i ha questi limiti:

    Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)

    Per ulteriori informazioni sui bucket espliciti, consulta Riferimento API.

La modalità di specifica dei bucket di istogrammi è spiegata nella sezione seguente:

Console

Quando crei una distribuzione, il sottomenu Bucket istogrammi si apre metrica e fai clic su Altro nel modulo Editor metriche. Il seguente modulo secondario riguarda il layout del bucket Lineare:

Bucket a istogrammi

Bucket lineari: compila il modulo del bucket dell'istogramma 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 bucket (b): la differenza tra il limite superiore e quello inferiore in ciascun 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 del bucket a istogrammi come segue:

  • Tipo: Esplicito
  • Limiti (b): un elenco separato da virgole dei valori limite dei bucket finiti. Questo determina anche il numero di bucket e la loro con una larghezza di banda.

Ad esempio, se l'elenco dei confini è:

0, 1, 2, 5, 10, 20

ci sono 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 modulo 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 nei bucket. Il valore deve essere maggiore di 1.

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

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

Per saperne di più sui bucket, consulta BucketOptions nel l'API Cloud Monitoring.

API

Il layout facoltativo del bucket viene specificato dal campo bucketOptions in l'oggetto LogMetric fornito a projects.metrics.create. Per l'oggetto LogMetric completo, consulta Creare una metrica di distribuzione in questa pagina. Le aggiunte per i layout dei bucket sono le seguenti:

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 vengono 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, ..., numFiniteBuckets

{ # 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)

Latenza nuova metrica

La nuova metrica viene visualizzata immediatamente nell'elenco delle metriche e nei relativi menu di Monitoring. Tuttavia, potrebbe essere necessario minuto affinché la metrica inizi a raccogliere i dati per le voci di log corrispondenti.

Ispezionare le metriche di distribuzione

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

Console

  1. Nella console Google Cloud, vai alla pagina Metriche basate su log:

    Vai a Metriche basate su log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Nel riquadro Metriche definite dall'utente, puoi vedere le metriche definite dall'utente nell'attuale progetto Google Cloud:

  3. Per visualizzare i dati in una metrica basata su log, fai clic sull'icona Menu in riga della metrica e seleziona Visualizza in Esplora metriche.

gcloud

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

gcloud logging metrics list

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

gcloud logging metrics describe METRIC_NAME

Per ricevere assistenza, utilizza il seguente comando:

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, usa il metodo API projects.metrics.list. Compila i parametri nella sezione come segue:

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

Recuperare le definizioni delle metriche

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

  • metricName: il nome 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 Lettura di serie temporali.

Per leggere una singola metrica basata su log definita dall'utente, compila il campo 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 descrizione, filtro e i nomi dei campi indicati nella metrica. Puoi aggiungere nuove etichette al e modificare le espressioni regolari utilizzate per estrarre i valori per la la metrica e le relative etichette. Se utilizzi una metrica con ambito a livello di bucket, puoi anche aggiornare il bucket della metrica.

Non puoi modificare i nomi o i tipi di 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

  1. Nella console Google Cloud, vai alla pagina Metriche basate su log:

    Vai a Metriche basate su log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Fai clic su Modifica metrica nella Menu per la metrica basata su log che vuoi modificare.

  3. Modifica gli elementi consentiti nella metrica.

  4. Fai clic su Aggiorna metrica.

gcloud

Utilizza Google Cloud CLI per modificare la descrizione e il filtro di una metrica contatore la query e il bucket. 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 basata su bucket, tutti i dati delle metriche raccolti prima della modifica non riflettono più la configurazione corrente. I dati delle metriche raccolti per il bucket precedente non viene rimosso.

Per aggiornare le metriche di distribuzione o altri campi delle metriche contatore, escludendo le METRIC_NAME, crea un file contenente la specifica aggiornata di il tuo LogMetric in formato JSON o YAML. Quindi, aggiorna 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 la 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 è esattamente uguale alla metrica esistente, ad eccezione della metrica le modifiche e le aggiunte che vuoi apportare.

Elimina metriche di distribuzione

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

Console

  1. Nella console Google Cloud, vai alla pagina Metriche basate su log:

    Vai a Metriche basate su log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  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 comando seguente per eliminare una metrica basata su log definita dall'utente nel progetto Google Cloud attuale:

gcloud logging metrics delete METRIC_NAME

Per maggiori dettagli, utilizza il comando seguente:

gcloud logging metrics delete --help

API

Per eliminare una metrica basata su log definita dall'utente, utilizza 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 fornisce altre funzionalità per aiutarti a gestire le metriche definite dall'utente nel tuo progetto Google Cloud. Per maggiori dettagli, consulta il riquadro delle metriche definite dall'utente.