Configurare le etichette per le metriche basate su log

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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

Se hai dimestichezza con le etichette, puoi andare direttamente a Crea 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 sono dotate di alcune etichette predefinite.

Puoi creare etichette definite dall'utente aggiuntive nelle metriche di tipo contatore e distribuzione specificando le espressioni di estrazione. Un'espressione di 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.
• Parte di un campo denominato che corrisponde a un'espressione regolare (regexp).

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

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

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

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.

• Dopo aver creato un'etichetta, non puoi più 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 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 le 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 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 delle metriche basate su log.

Etichette predefinite

La maggior parte delle metriche basate su log è dotata di alcune etichette predefinite:

• Etichette delle risorse: tutte le metriche utilizzano un oggetto risorsa 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 sono: istanze VM, database Cloud SQL e bilanciatori del carico.

  La risorsa e le relative etichette sono elencate separatamente dalle altre etichette di 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.

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

Visualizza le etichette utilizzando Esplora metriche

Per visualizzare le etichette su 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 e seleziona Visualizza in Esplora metriche dal menu more_vert Altro della metrica.

   Prima di procedere, attendi che il grafico mostri i dati. L'operazione potrebbe richiedere diversi minuti quando crei una metrica basata su log.

3. Per visualizzare le etichette disponibili, espandi il campo Filtro. Potresti vedere etichette delle risorse ed etichette delle metriche. L'elenco di 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. Anche le etichette definite dall'utente vengono visualizzate in questa sezione.

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

   1. Cambia l'elemento Aggregation in Non aggregato.

   2. Nel grafico, seleziona Tabella o Entrambe.

   3. Nella barra degli strumenti, seleziona view_column Menu di visualizzazione delle colonne, poi seleziona le etichette. Questo menu mostra tutte le etichette relative a cui sono presenti dati.

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

Crea un'etichetta

Puoi creare etichette definite dall'utente al momento della creazione della metrica. Sia le metriche contatore che le metriche di distribuzione possono avere etichette. Non puoi aggiungere etichette alle metriche basate su 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 possono aiutarti a iniziare con la creazione di 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 di estrazione, devi utilizzare un gruppo di acquisizione.
• Se non specifichi un'espressione estrattore, 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 univoco, ID utente, indirizzi IP, URL non parametrizzati e così via.

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

Estrai valore da un campo con caratteri speciali

Se un campo in una voce di log contiene caratteri speciali, racchiudi il campo tra virgolette.

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

Prendi in considerazione una voce di log con il formato seguente:

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

Per estrarre il valore per lo stato, ad esempio deferred dalle voci di log con il formato precedente, potresti eseguire un'operazione simile a:

• Nome campo: textPayload
• Espressione 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 al momento della definizione dell'etichetta e l'estrattore esegue l'iterazione del set finché non viene trovata una corrispondenza. La prima corrispondenza viene sempre restituita, 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, esamina diversi audit log e noti che il formato dell'etichetta protoPayload è conforme alla struttura di AuditLog. Di seguito viene 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 per archiviare le informazioni dal campo permission. Noti che questi campi sono formattati come io.k8s.xxx, dove xxx è una stringa che fornisce ulteriori dettagli sulla richiesta. Questa stringa potrebbe avere un valore come get o avere una formattazione più complessa, ad esempio io.k8s.coordination.v1.leases.get.

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

Ora devi configurare l'etichetta. Poiché il campo permission è ripetuto e il campo padre è il campo authorizationInfo, puoi impostare il nome del campo come segue:

protoPayload.authorizationInfo.permission

Infine, crea la seguente espressione regolare:

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