Configura le metriche di distribuzione

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

Una metrica di distribuzione registra la distribuzione statistica dei valori estratti nei bucket dell'istogramma. I valori estratti non vengono registrati singolarmente, ma viene registrata la loro distribuzione nei bucket configurati, insieme al conteggio, alla media e alla somma della deviazione al quadrato dei valori. Puoi utilizzare il layout predefinito dei segmenti dell'istogramma nella distribuzione oppure puoi perfezionare i limiti dei segmenti per acquisire approssimativamente i valori.

Per ulteriori informazioni sulla visualizzazione e l'interpretazione delle metriche di distribuzione, consulta Metriche di distribuzione.

Prima di iniziare

  1. Per utilizzare le metriche basate su log, devi disporre di un progetto Google Cloud con la 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.

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

      7. Creare una metrica di distribuzione

      La metrica conta le voci di log identificate da un filtro che fornisci. Puoi utilizzare le 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 del servizio.

      Console

      Per creare una metrica di conteggio basata su log nella consoleGoogle Cloud del 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 log.

      3. Imposta il Tipo di metrica: seleziona Distribuzione.

      4. Imposta i seguenti campi nella sezione Dettagli:

        • Nome metrica basata su log: scegli un nome univoco tra le metriche basate su log nel tuo progetto Google Cloud . Sono previste alcune limitazioni per la denominazione; per maggiori dettagli, consulta la sezione Risoluzione dei problemi.
        • Descrizione: inserisci una descrizione per la metrica.
        • Unità: (facoltativo) per le metriche di distribuzione, puoi facoltativamente inserire unità quali s e ms. Per ulteriori informazioni, consulta il campo unit di MetricDescriptor.

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

        1. Utilizza il menu Seleziona progetto o bucket di log per scegliere se la metrica conta le voci di log nel tuo progetto Google Cloud o solo quelle voci di log in un bucket di log specifico.

        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 i filtri della metrica.

        3. Nome campo: inserisci il campo voce di log che contiene il valore della distribuzione. Durante la digitazione ti 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. In caso contrario, specifica un'espressione regolare che estrae il valore numerico della distribuzione dal valore del campo.

          Esempio. Supponiamo che il campo della voce di log latency contenga un numero seguito da ms per i millisecondi. La seguente espressione regolare sceglie il numero senza il suffisso dell'unità:

          ([0-9.]+)

          Le parentesi, note come gruppo di acquisizione di un'espressione regolare, identificano la parte della corrispondenza di testo che verrà estratta. Per maggiori dettagli, vedi Utilizzo delle espressioni regolari.

        • Avanzate (bucket dell'istogramma): (facoltativo) se fai clic su Avanzate, si apre una sezione del modulo che puoi utilizzare per specificare layout personalizzati dei bucket. Se non specifichi i layout dei bucket, viene fornito un layout predefinito. Per ulteriori informazioni, vedi Bucket dell'istogramma in questa pagina.
        1. Per vedere quali voci di log corrispondono al filtro, fai clic su Visualizza l'anteprima dei log.

      6. (Facoltativo) Aggiungi un'etichetta nella sezione Etichette. Per istruzioni su come creare etichette, vedi 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 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 dell'istogramma.

      API

      Per creare una metrica di distribuzione, utilizza il metodo projects.metrics.create dell'API Logging. Se utilizzi il riquadro Explorer API nella pagina di riferimento, prepara gli argomenti nel seguente modo:

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

        • Per una metrica basata su log con ambito di progetto, specifica il progetto:
        projects/PROJECT_ID
        • Per una metrica basata su log con ambito bucket, specifica il bucket:
        projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID

      2. 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 alla denominazione. Per ulteriori 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 conta il numero di valori che rientrano in intervalli specificati (bucket). Puoi avere fino a 200 bucket in una metrica di distribuzione.

      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 spazi vuoti tra i bucket, il limite inferiore di un bucket è uguale al limite superiore del bucket precedente e così via. Affinché i limiti non rientrino in più di un bucket, un bucket include il limite inferiore, mentre il limite 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 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 limite. Gli altri bucket conteggiano i valori maggiori o uguali al limite inferiore e minori del limite superiore. Se sono presenti n valori limite, allora 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 segmenti dell'istogramma per le metriche di distribuzione. Specifica una formula per i valori limite oppure elenca i valori limite:

      • Lineare(offset, larghezza, 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 il riferimento API.

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

      • Esplicito: elenchi tutti i limiti per i bucket nell'array bounds. Il bucket i ha questi confini:

        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 il riferimento API.

      Il modo in cui specifichi i bucket dell'istogramma è spiegato nella sezione seguente:

      Console

      Il sottomenu Bucket dell'istogramma si apre quando crei una metrica di distribuzione e fai clic su Altro nel modulo Editor metriche. Il seguente modulo secondario riguarda il layout dei 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 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 del bucket dell'istogramma come segue:

      • Type: Explicit
      • Limiti (b): un elenco separato da virgole dei valori limite dei bucket finiti. Determina anche il numero di bucket e la loro larghezza.

      Ad esempio, se l'elenco dei confini è:

      0, 1, 2, 5, 10, 20

      poi 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 dei bucket dell'istogramma 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 del bucket facoltativo è specificato dal campo bucketOptions nell'oggetto LogMetric fornito a projects.metrics.create. Per l'oggetto LogMetric completo, vedi Creare una metrica di distribuzione in questa pagina. Le aggiunte ai 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 limiti 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 limiti sono scala * fattore di crescita ^ 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 della nuova metrica

      La nuova metrica viene visualizzata immediatamente nell'elenco delle metriche e nei menu di monitoraggio pertinenti. Tuttavia, potrebbe essere necessario fino a un minuto prima che la metrica inizi a raccogliere i 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 esaminare una metrica specifica nel tuo progetto Google Cloud :

      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, vengono visualizzate le metriche basate su log definite dall'utente nel progetto Google Cloud corrente:

      3. Per visualizzare i dati in una metrica basata sui log, fai clic sul menu nella riga della metrica e seleziona Visualizza in Esplora metriche.

      gcloud

      Per elencare le metriche basate sui 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 questo comando:

      gcloud logging metrics describe METRIC_NAME

      Per ricevere assistenza, utilizza il comando seguente:

      gcloud logging metrics --help

      Non puoi leggere i dati della serie temporale di una metrica da Google Cloud CLI.

      API

      Elenca metriche

      Per elencare le metriche basate sui log definite dall'utente in un progetto Google Cloud , utilizza il metodo API projects.metrics.list. Compila 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: recupera la pagina successiva dei 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 API projects.metrics.get. Compila 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 informazioni dettagliate sui dati delle serie temporali, vedi Lettura delle serie temporali.

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

      logging.googleapis.com/user/METRIC_ID

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

      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 nel menu per la metrica basata sui 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, la query di filtro e il bucket di una metrica del contatore. 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 riflettono più la configurazione attuale. 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, escluso METRIC_NAME, crea un file che contenga la specifica rivista del tuo LogMetric in formato JSON o YAML. Poi, aggiorna la metrica chiamando il comando update con il campo --config-from-file, sostituendo FILENAME con il nome del file JSON o YAML:

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

      Per ulteriori 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 che sia esattamente uguale alla metrica esistente, ad eccezione delle modifiche e delle aggiunte che vuoi apportare.

      Elimina le 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 che vuoi eliminare e fai clic su Elimina.

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

      gcloud

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

      gcloud logging metrics delete METRIC_NAME

      Per ulteriori dettagli, utilizza il comando seguente:

      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 fornisce più funzionalità per aiutarti a gestire le metriche definite dall'utente nel tuo progettoGoogle Cloud . Per maggiori dettagli, consulta la sezione Metriche definite dall'utente.