Configura le etichette sulle metriche basate su log

Questo documento illustra le etichette delle metriche basate su log e spiega come creare e utilizzare le etichette sulle metriche dei log.

Se hai dimestichezza con le etichette, puoi passare direttamente a Creare un'etichetta in questa pagina.

Panoramica delle etichette per le metriche basate su log

Le etichette consentono alle metriche basate su log di contenere più serie temporali, una per ogni valore di etichetta. Tutte le metriche basate su log sono dotate di alcune etichette predefinite.

Puoi creare altre etichette definite dall'utente sia nella metrica del tipo di contatore che in quella del tipo di distribuzione specificando le espressioni di estrazione. Un'espressione di estrazione indica a Cloud Logging come estrarre il valore dell'etichetta dalle voci di log. Puoi specificare il valore dell'etichetta in uno dei seguenti modi:

• L'intero contenuto di un campo denominato nell'oggetto LogEntry.
• Una parte di un campo denominato che corrisponde a un'espressione regolare (regexp).

Puoi estrarre le etichette dai campi integrati LogEntry, ad esempio httpRequest.status, o da uno dei campi di payload textPayload, jsonPayload o protoPayload.

Per informazioni sulle espressioni regolari, consulta la pagina Sintassi RE2.

Nota: crea le etichette solo quando devi identificare valori per classificare o riepilogare i dati delle metriche. Non utilizzare le etichette per assegnare semplicemente nomi ai campi di dati.

Limitazioni delle etichette definite dall'utente

Le seguenti limitazioni si applicano alle etichette definite dall'utente:

• Puoi creare fino a 10 etichette definite dall'utente per metrica.

• Dopo aver creato un'etichetta, non puoi eliminarla.

  • Puoi modificare l'espressione di estrazione e la descrizione dell'etichetta che hai già creato.

  • Non puoi modificare il nome o il tipo di valore di un'etichetta già creata.

• Vengono conservati solo i primi 1024 caratteri di un valore di etichetta.

• Ogni metrica basata su log è limitata a circa 30.000 serie temporali attive, che dipendono dal numero di valori possibili per ogni etichetta, incluse le etichette predefinite.

  Ad esempio, se le voci di log provengono da 100 risorse come istanze VM e definisci un'etichetta con 20 valori possibili, puoi avere fino a 2000 serie temporali per la metrica.

Attenzione: non estrarre mai un valore dell'etichetta univoco per ogni voce di log, ad esempio i campi insertId o timestamp completi. Avrai tutte le serie temporali che contengono le voci di log, ciascuna contenente un punto.

Se hai troppe serie temporali o troppi punti dati, i costi aumenteranno e la tua attività potrebbe essere limitata. Per ulteriori informazioni sul costo delle metriche basate su log, consulta Prezzi di Cloud Monitoring: metriche addebitabili. Per informazioni sui limiti che si applicano alle metriche basate su log, consulta Quote e limiti: metriche basate su log e Risoluzione dei problemi relativi alle metriche basate su log.

Etichette predefinite

Tutte le metriche basate su log sono dotate di alcune etichette predefinite:

• Etichette delle risorse: tutte le metriche utilizzano un oggetto di risorse monitorato per identificare l'origine dei dati delle serie temporali. Ogni tipo di risorsa include un nome e una o più etichette. Esempi di tipi di risorse includono istanze VM, database Cloud SQL, bilanciatori del carico ecc.

  La risorsa e le relative etichette sono elencate separatamente dalle altre etichette delle metriche in Cloud Monitoring, ma hanno lo stesso effetto: creano serie temporali aggiuntive nella metrica. Per ulteriori informazioni, consulta Metriche, Serie temporali e Risorse.

• log: questa etichetta contiene il valore della parte LOG_ID del campo logName nelle voci di log.

• gravità: questa etichetta contiene il valore del campo severity nelle voci di log. L'etichetta di gravità viene fornita per impostazione predefinita solo nelle metriche basate su log di sistema.

Esempio: utilizzare Metrics Explorer

Il seguente screenshot di Metrics Explorer mostra le etichette in una delle metriche basate su log di sistema. Puoi ottenere l'elenco delle etichette facendo clic all'interno della casella di testo Filtro:

Lo screenshot mostra le seguenti informazioni:

• Metrics Explorer utilizza le serie temporali della metrica logging/log_entry_count e del tipo di risorsa gce_instance: istanze VM di Compute Engine.

  Questa metrica contiene anche le serie temporali di altri tipi di risorse, ma Metrics Explorer consente di esaminare un solo tipo di risorsa alla volta.

• Il tipo di risorsa gce_instance ha tre etichette di risorse: project_id, instance_id e zone.

• La metrica ha due etichette di metrica: log e severity. Le etichette definite dall'utente appaiono anche in questa sezione.

Crea un'etichetta

Le etichette definite dall'utente vengono create durante la creazione della metrica. Le metriche dei contatori e della distribuzione possono avere etichette. Non puoi aggiungere etichette alle metriche basate su log di sistema.

Console

1. Quando crei una metrica basata su log, il riquadro Crea metrica di log include un'opzione per aggiungere etichette.

2. Fai clic su Aggiungi etichetta.

   Suggerimento: per visualizzare i campi e i valori all'interno di una voce di log, procedi nel seguente modo:

   1. Nella sezione Selezione filtro, fai clic su Visualizza l'anteprima dei log.
   2. Nel riquadro Visualizza log, scegli una voce di log e fai clic sull'espansione accanto a questa voce.
   3. Fai clic su Espandi campi nidificati.

3. Imposta i seguenti campi nella sezione Etichette:

   1. Nome etichetta: inserisci un nome per l'etichetta. Ad esempio, ID.
      

      Il nome deve soddisfare i seguenti criteri:

      • Non superare i 100 caratteri.
      • Trova l'espressione regolare [a-zA-Z][a-zA-Z0-9_]*.
      • Sono composti da altri elementi oltre alla stringa "log".

   2. Descrizione: descrivi l'etichetta. Cerca di essere il più specifico possibile sul formato dei valori dei log previsti. Ad esempio: Instance number.

   3. Tipo di etichetta: scegli Stringa, Booleana o Intero.

   4. Nome campo: inserisci il nome del campo di voce di log contenente il valore dell'etichetta. Puoi scegliere tra varie opzioni di digitazione. In questo esempio, il campo è:

      labels."compute.googleapis.com/resource_id"
      

   5. Espressione regolare: se il valore dell'etichetta è costituito da tutti i contenuti del campo, puoi lasciare vuoto questo campo. In alternativa, specifica un gruppo di acquisizione regexp che estrae il valore dell'etichetta dal valore del campo.

      Ad esempio, supponiamo che il campo contenga in genere testo come il seguente:

      The instance number is 0123456789; the ID is my-test-instance22
      

      Se vuoi che il valore dell'etichetta corrisponda al numero dell'istanza, esistono molte espressioni regolari che estraggono il numero corretto. Ad esempio, nella seguente espressione, le parentesi sono un gruppo di acquisizione che identifica la parte del testo che verrà estratto:

      The instance number is ([0-9]+); .*
      

      Per ulteriori informazioni sulle espressioni regolari, consulta la pagina Sintassi RE2.

4. Fai clic su Fine per creare l'etichetta. Puoi aggiungere altre etichette ripetendo questi passaggi.

5. Per completare la creazione della metrica, fai clic su Crea metrica.

gcloud

Per istruzioni sulla creazione di una metrica basata su log con etichette che utilizzano Google Cloud CLI, consulta gcloud logging metrics create.

API

Le etichette vengono specificate come parte dell'oggetto LogMetric nel corpo della richiesta delle chiamate al metodo projects.metrics.create dell'API Logging. Per informazioni sulle chiamate ai metodi complete, consulta Creazione di metriche del contatore o Creazione delle metriche di distribuzione.

Per ogni etichetta, devi aggiungere un segmento ai campi metricDescriptor e labelExtractors di LogMetric.

La sintassi è la seguente:

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

Gli elementi di sintassi hanno il seguente significato:

• LABEL_NAME: il nome dell'etichetta come stringa.
• VALUE_TYPE: il tipo di etichetta: STRING, BOOL o INT64.
• LABEL_DESCRIPTION: una descrizione dell'etichetta.

• EXTRACTOR_EXPRESSION: una stringa che combina il nome del campo della voce di log con un'espressione regolare facoltativa. L'espressione di estrazione può essere una delle seguenti:

  EXTRACT(FIELD)
  

  REGEXP_EXTRACT(FIELD, REGEXP)
  

Per ulteriori informazioni sulle espressioni regolari, consulta la pagina Sintassi RE2.

Di seguito è riportato un esempio con due etichette:

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

Per maggiori dettagli, vedi il tipo LogMetric.