Configura le etichette nelle metriche basate su log

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

Se hai familiarità con le etichette, puoi andare 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 combinazione di valori delle etichette. Tutte le metriche basate su log includono alcune etichette predefinite.

Puoi creare altre etichette definite dall'utente sia nelle metriche di tipo contatore sia in quelle di tipo distribuzione specificando le espressioni dell'estrattore. Un'espressione dell'estrattore 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 LogEntry campi integrati, come httpRequest.status, o da uno dei campi del payload textPayload, jsonPayload, o protoPayload. Tuttavia, non puoi estrarre l'ID di un gruppo di errori dal campo errorGroups.

Per informazioni sulle espressioni regolari, consulta Sintassi RE2.

Non inserire informazioni sensibili nell'espressione dell'estrattore e non estrarre dati sensibili nelle etichette. Questi dati vengono trattati come dati di servizio.

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

Limitazioni delle etichette definite dall'utente

Alle etichette definite dall'utente si applicano le seguenti limitazioni:

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

• Una volta creata, non puoi eliminare un'etichetta.

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

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

• 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 , a seconda del numero di valori possibili per ogni etichetta, incluse le etichette predefinite.

  Ad esempio, se le voci di log provengono da 100 risorse, come le 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 di etichetta univoco per ogni voce di log, ad esempio i campi completi insertId o timestamp. Avrai tante serie temporali quante sono le voci di log, ognuna contenente un punto.

Se hai troppe serie temporali o troppi punti dati, i costi aumenteranno e la tua attività potrebbe essere limitata. Per saperne di più sul costo delle metriche basate su log, consulta Prezzi di Google Cloud Observability. Per informazioni sui limiti applicabili alle metriche basate su log, consulta Quote e limiti: metriche basate su log e Risolvere i problemi relativi alle metriche basate su log.

Etichette predefinite

La maggior parte delle metriche basate su log include alcune etichette predefinite:

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

  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 saperne di più, consulta Metriche, serie temporali e risorse.

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

• severity: 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.

Visualizzare le etichette utilizzando Metrics Explorer

Per visualizzare le etichette su una serie temporale generata per una metrica basata su log:

1. Nella Google Cloud console, 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. Trova la metrica che vuoi visualizzare, quindi seleziona Visualizza in Esplora metriche dal menu Altro della metrica.

   Prima di procedere, attendi che il grafico visualizzi i dati. Questa operazione potrebbe richiedere diversi minuti dopo la creazione di una metrica basata su log.

3. Per visualizzare le etichette disponibili, espandi il campo Filtro. Potresti visualizzare le etichette delle risorse e le etichette delle metriche. L'elenco delle etichette è specifico per il tipo di risorsa e il tipo di metrica. Ad esempio:

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

   • Il tipo di metrica logging/log_entry_count ha due etichette delle metriche: log e severity. In questa sezione vengono visualizzate anche le etichette definite dall'utente.

4. Per verificare che un'etichetta definita dall'utente estragga i dati corretti dalle voci di log:

   1. Modifica l'elemento Aggregazione in Nessuna aggregazione.

   2. Nel grafico, seleziona Tabella o Entrambi.

   3. Nella barra degli strumenti, seleziona Menu di visualizzazione delle colonne, quindi seleziona le etichette. Questo menu mostra tutte le etichette per le quali sono presenti dati.

      Se non vedi un'etichetta che hai creato, verifica il nome del campo e l'espressione dell'estrattore.

Creare un'etichetta

Puoi creare etichette definite dall'utente quando crei la metrica. Sia le metriche dei contatori sia le metriche di distribuzione possono avere etichette. Non puoi aggiungere etichette alle metriche basate su log di sistema.

Per creare un'etichetta, devi specificare il campo nella voce di log, quindi definire un'espressione che estrae un valore dal campo specificato.

Console

1. Quando crei una metrica basata su log, il riquadro Crea una metrica basata su 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:

   1. Nella sezione Selezione filtro, fai clic su Anteprima dei log.
   2. Nel riquadro Visualizza log, scegli una voce di log e fai clic sul pulsante di espansione accanto.
   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 deve superare i 100 caratteri di lunghezza.
      • Deve corrispondere all'espressione regolare [a-zA-Z][a-zA-Z0-9_]*.
      • Deve essere composto da più della 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, BOOLEANO o INTERO.

      Per saperne di più sui vari tipi di dati che possono essere utilizzati per creare metriche basate su log, consulta Tipi di dati per le metriche basate su log.

   4. Nome campo: inserisci il nome del campo della voce di log che contiene il valore dell'etichetta. Ti vengono offerte delle scelte durante la digitazione. In questo esempio, il campo è:

      labels."compute.googleapis.com/resource_id"
      

   5. Espressione regolare: se il valore dell'etichetta è costituito da l'intero contenuto del campo, puoi lasciare vuoto questo campo. In caso contrario, specifica un gruppo Capture di espressioni regolari 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 sia il numero dell'istanza, esistono molte espressioni regolari che estraggono il numero corretto. Ad esempio, nell'espressione seguente, le parentesi sono un gruppo Capture che identifica la parte di testo da estrarre:

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

      Per informazioni sulle espressioni regolari, consulta 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 creare una metrica basata su log con etichette personalizzate, devi creare un file che contenga una rappresentazione della definizione di LogMetric in formato JSON o YAML, incluse le etichette personalizzate. Quindi, crea la metrica chiamando il comando create con il flag --config-from-file, sostituendo FILENAME con il nome del file JSON o YAML:

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

Per saperne di più, 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 complete ai metodi, consulta Creare metriche dei contatori o Creare metriche di distribuzione.

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

La sintassi è la seguente:

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

Gli elementi della 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 dell'estrattore può essere una delle seguenti:

  EXTRACT(FIELD)
  

  REGEXP_EXTRACT(FIELD, REGEXP)
  

Per informazioni sulle espressioni regolari, consulta 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 saperne di più, consulta il LogMetric tipo.

Esempi

Questa sezione fornisce alcuni esempi che potrebbero aiutarti a iniziare a creare etichette sulle metriche basate su log definite dall'utente. Dopo aver creato un'etichetta, ti consigliamo di verificarla utilizzando Esplora metriche.

Suggerimenti:

• Quando specifichi un'espressione dell'estrattore, devi utilizzare un gruppo Capture.
• Se non specifichi un'espressione dell'estrattore, viene estratto l'intero valore del campo.

• Assicurati che l'insieme dei valori possibili per qualsiasi etichetta sia vincolato. L'approccio preferito è un piccolo insieme di valori discreti (ad esempio "rosso", "verde" e "blu"). Se, ad esempio, estrai i valori RGB a 8 bit per un'etichetta di colore, puoi avere oltre 16 milioni di valori diversi. Ciò significa che potresti avere oltre 16 milioni di serie temporali.

  Non estrarre valori ad alta risoluzione come timestamp, qualsiasi tipo di identificatore univoco, ID utente, indirizzi IP, URL non parametrizzati e così via.

Estrarre il codice di stato da un audit log

Se un campo non contiene caratteri speciali, puoi utilizzare il nome del campo nell'etichetta per la metrica basata su log.

Ad esempio, per gli audit log, il campo protoPayload è conforme alla struttura AuditLog. Pertanto, per estrarre il campo status da un audit log, puoi impostare il nome del campo su protoPayload.status.code e lasciare vuota l'espressione dell'estrattore.

Se vuoi estrarre solo la prima cifra del codice di errore, puoi impostare l'espressione dell'estrattore su (\d)\d\d.

Estrarre il valore da un campo con caratteri speciali

Se un campo in una voce di log contiene caratteri speciali, racchiudilo tra virgolette doppie.

Ad esempio, per estrarre l'intero valore dell'etichetta k8s-pod/k8s-app, imposta il nome del campo su labels."k8s-pod/k8s-app" e lascia vuota l'espressione.

Estrarre un valore da un payload di testo

Nota: per assicurarti che l'insieme dei valori possibili per l'etichetta sia vincolato, specifica sempre un'espressione dell'estrattore per i campi del payload di testo.

Considera una voce di log con il seguente formato:

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

Per estrarre il valore dello stato, ad esempio deferred, dalle voci di log con il formato precedente, puoi procedere nel seguente modo:

• Nome campo: textPayload
• Espressione dell'estrattore: ^unfinished.*state: ([a-z]+)

Estrarre il valore da un campo ripetuto

Una voce di log può contenere un campo con campi ripetuti. In JSON, questi campi vengono visualizzati utilizzando le parentesi quadre ([]). Dal punto di vista delle etichette, considera i campi ripetuti come un insieme e l'estrattore di etichette come un iteratore. Quando definisci l'etichetta, fornisci i criteri per la corrispondenza e l'estrattore scorre l'insieme finché non viene trovata una corrispondenza. Viene sempre restituita la prima corrispondenza, anche quando più membri dell'insieme soddisfano i criteri.

Decidi di creare una metrica basata su log che conteggia gli audit log. Prima di configurare l'etichetta, esamini diversi audit log e noti che il formato di protoPayload è conforme alla AuditLog struttura. Di seguito è illustrata una parte di una voce di audit log.

{
  ...
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    authenticationInfo: {1}
    authorizationInfo: [
      0: {
        granted: true
        permission: "io.k8s.coordination.v1.leases.get"
        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"
      }
    ]
    requestMetadata: {2}
    status: {1}
    ...
  }
  ...
}

Decidi di creare un'etichetta per la metrica basata su log che memorizza le informazioni del campo permission. Noti che questi campi sono formattati come io.k8s.xyz, dove xyz è una stringa che fornisce maggiori dettagli sulla richiesta. Questa stringa potrebbe avere un valore come get o potrebbe avere una formattazione più complessa come io.k8s.coordination.v1.leases.get.

Per ridurre al minimo il numero di valori delle etichette, non vuoi estrarre le informazioni dettagliate. Vuoi memorizzare nell'etichetta solo valori come get o coordination. Inoltre, decidi di non includere il prefisso comune, io.k8s., nel valore dell'etichetta.

Il passo successivo è configurare l'etichetta. Poiché il campo permission è un campo ripetuto, con il campo authorizationInfo come padre, imposta il nome del campo nel seguente modo:

protoPayload.authorizationInfo.permission

Infine, crea la seguente espressione regolare:

io.k8s.([a-z]+).*