Configurare le etichette per le metriche basate su log

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

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

Puoi creare etichette aggiuntive definite dall'utente nelle metriche di tipo contatore e di tipo distribuzione specificando le espressioni dell'estrattore. Un'espressione estrattore indica a Cloud Logging come estrarre il valore dell'etichetta dalle voci di log. Puoi specificare il valore dell'etichetta come uno dei seguenti:

• 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 LogEntry integrati, ad esempio 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, vedi Sintassi RE2.

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

Limitazioni delle etichette definite dall'utente

Si applicano le seguenti limitazioni 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 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 dell'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 istanze VM e definisci un'etichetta con 20 valori possibili, puoi avere fino a 2000 serie temporali per la metrica.

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 sui log, consulta Prezzi di Cloud Monitoring: metriche a pagamento. Per informazioni sui limiti applicati 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

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 sui log di sistema.

Visualizzare le etichette utilizzando Metrics Explorer

Per visualizzare le etichette di una serie temporale generata per una metrica basata su log, segui questi passaggi:

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. Individua la metrica che vuoi visualizzare, quindi seleziona Visualizza in Esplora metriche dal menu more_vert Altro della metrica.

   Prima di procedere, attendi che il grafico mostri i dati, il che potrebbe richiedere diversi minuti se hai creato una metrica basata su log.

3. Per visualizzare le etichette disponibili, espandi il campo Filtro. Potresti visualizzare etichette di risorse ed etichette di 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 della metrica: 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, procedi nel seguente modo:

   1. Modifica l'elemento Aggregazione in Nessuna aggregazione.

   2. Nel grafico, seleziona Tabella o Entrambi.

   3. Nella barra degli strumenti, seleziona view_column 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.

Crea un'etichetta

Le etichette definite dall'utente vengono create quando crei la metrica. Sia le metriche di conteggio sia le metriche di distribuzione possono avere etichette. Non puoi aggiungere etichette alle metriche basate sui log di sistema.

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

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

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

{
  ...
  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)",
  },
}

Esempi

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

Suggerimenti:

• Devi utilizzare un gruppo di acquisizione quando specifichi un'espressione estrattore.
• Se non specifichi un'espressione di estrazione, viene estratto l'intero valore del campo.

• Assicurati che l'insieme di valori possibili per qualsiasi etichetta sia vincolato. Un piccolo insieme di valori discreti (come "rosso", "verde" e "blu") è l'approccio preferito. Se, ad esempio, estrai i valori RGB a 8 bit per un'etichetta 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 unico, ID utente, indirizzi IP, URL senza parametri 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 della metrica basata sui log.

Ad esempio, per i log di controllo, il campo protoPayload è conforme alla struttura AuditLog. Pertanto, per estrarre il campo status da un log di controllo, 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.

Estrai 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.

Estrai un valore da un 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 fare qualcosa di simile a:

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

Estrai valore da un campo ripetuto

Una voce di log potrebbe 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. Fornisci i criteri per la corrispondenza quando definisci l'etichetta e l'estrattore scorre il set finché non viene trovata una corrispondenza. La prima corrispondenza viene sempre restituita, anche quando più membri del set corrispondono ai criteri.

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

{
  ...
  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 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 solo valori come get o coordination nell'etichetta. Inoltre, decidi di non includere il prefisso comune io.k8s. nel valore dell'etichetta.

Poi, configura 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]+).*