Esegui query e visualizza i log

Questa pagina fornisce istruzioni dettagliate su come eseguire query e visualizzare i log utilizzando l'interfaccia utente di Grafana per ottenere informazioni sulle attività e sugli eventi del servizio.

Dopo aver raccolto i log dai carichi di lavoro e dai servizi di cui è stato eseguito il deployment nell'appliance con air gap Google Distributed Cloud (GDC), puoi iniziare ad analizzarli. Per analizzare i log, puoi visualizzarli e filtrarli in pannelli Grafana informativi o chiamate gRPC per l'accesso programmatico.

Puoi accedere ai log nel seguente modo:

  • Pannelli Grafana: ottieni informazioni dettagliate sul record di attività del tuo progetto tramite il pannello Log dell'istanza Grafana. Questo pannello ti consente di eseguire query e individuare log specifici, fornendo un'osservabilità granulare dei dati in base alle tue esigenze. Grafana fornisce un'interfaccia intuitiva per filtrare e analizzare i dati dei carichi di lavoro, creando dashboard e pannelli personalizzati per una visualizzazione completa.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per eseguire query e visualizzare i log nell'interfaccia utente di Grafana, chiedi all'amministratore IAM dell'organizzazione o del progetto di concederti uno dei ruoli predefiniti Visualizzatore Grafana dell'organizzazione o Visualizzatore Grafana del progetto. A seconda del livello di accesso e delle autorizzazioni di cui hai bisogno, potresti ottenere ruoli Grafana in un'organizzazione o un progetto.

In alternativa, per ottenere le autorizzazioni necessarie per eseguire query sui log dall'API Log Query, chiedi all'amministratore IAM del progetto di concederti il ruolo di query dell'API Log Query nello spazio dei nomi del progetto.

Per saperne di più su questi ruoli, consulta Preparare le autorizzazioni IAM.

Creare query per i log

L'esecuzione di query sui log dall'interfaccia utente dell'istanza di monitoraggio del sistema consente di scegliere l'origine dati da cui recuperare i log operativi del progetto e ottenere una visualizzazione integrata delle query. Per filtrare i risultati, cerca i log per etichette utilizzando le espressioni del linguaggio di query. Ad esempio, puoi impostare le etichette cluster e namespace nelle query sui valori che identificano rispettivamente lo spazio dei nomi del cluster e del progetto.

Endpoint dell'istanza di monitoraggio del sistema

Per l'operatore dell'applicazione (AO)

Il seguente URL è l'endpoint dell'istanza di monitoraggio del tuo progetto:

https://GDC_URL/PROJECT_NAMESPACE/grafana

Sostituisci quanto segue:

  • GDC_URL: l'URL della tua organizzazione in GDC.
  • PROJECT_NAMESPACE: lo spazio dei nomi del progetto.

Per l'amministratore della piattaforma (PA)

Il seguente URL è l'endpoint dell'istanza di monitoraggio del tuo progetto:

https://GDC_URL/platform-obs/grafana

Sostituisci GDC_URL con l'URL della tua organizzazione in GDC.

Eseguire query e filtrare i log

Seleziona uno dei seguenti metodi per creare query e filtrare i log dai carichi di lavoro del progetto:

Questa sezione descrive come accedere ai log utilizzando il pannello Log in Grafana.

Identificare l'endpoint Grafana

Per l'operatore dell'applicazione (AO)

Il seguente URL è l'endpoint dell'istanza di monitoraggio del tuo progetto:

https://GDC_URL/PROJECT_NAMESPACE/grafana

Sostituisci quanto segue:

  • GDC_URL: l'URL della tua organizzazione in GDC.
  • PROJECT_NAMESPACE: lo spazio dei nomi del progetto.

Per l'amministratore della piattaforma (PA)

Il seguente URL è l'endpoint dell'istanza di monitoraggio del tuo progetto:

https://GDC_URL/platform-obs/grafana

Sostituisci GDC_URL con l'URL della tua organizzazione in GDC.

Visualizzare i log nell'interfaccia utente di Grafana

Registra le query nell'interfaccia utente di Grafana:

  1. Nella console GDC, seleziona il progetto.
  2. Nel menu di navigazione, seleziona Operazioni > Logging.
  3. Fai clic su Visualizza tutto in Grafana Loki.

Si apre una nuova pagina con l'endpoint Grafana e viene visualizzata l'interfaccia utente.

  1. Nell'interfaccia utente, fai clic su Esplora Esplora dal menu di navigazione per aprire la pagina Esplora.
  2. Dal menu della barra Esplora, seleziona un'origine dati per recuperare i log, in base al tipo di universo:

  • Universi a zona singola: seleziona una delle seguenti origini dati per visualizzare i dati di logging della zona singola del tuo universo:

  • Log operativi: visualizza i log operativi.

  • Audit log: visualizza i log di controllo.

  • Log operativi ZONE_NAME: visualizza i log operativi di una zona specifica.

  • Audit log ZONE_NAME: mostra gli audit log di una zona specifica.

Inoltre, per visualizzare i dati tra zone diverse in un'unica dashboard e aggiungere più zone alla query, seleziona Mista come origine dati.

  1. Inserisci una query per cercare i log nel riquadro Log utilizzando le espressioni LogQL (Log Query Language). Puoi eseguire questo passaggio in uno dei seguenti modi:

    • Utilizza l'interfaccia interattiva di creazione delle query. Quindi, fai clic su Esegui query.
    • Inserisci la query direttamente nel campo di testo e premi Maiusc+Invio per eseguirla.

    La pagina mostra i log corrispondenti alla tua query. Dopo aver eseguito una query sui log, puoi esportarli. Fai clic su Esporta per scaricare i log in formato CSV o testo normale. Puoi anche selezionare un intervallo di tempo per i log.

    L'opzione Log di controllo è selezionata nella pagina Esplora per ottenere i log di controllo.

    Figura 1. Opzione di menu per eseguire query sui log di controllo dall'interfaccia utente di Grafana.

    Nella figura 1, l'opzione Audit log mostra l'interfaccia che ti consente di creare query da Grafana per recuperare gli audit log.

    Per esempi di etichette e valori per eseguire query su log diversi, vedi Query ed etichette di esempio.

    Seleziona un intervallo di tempo per i log

    Per eseguire query sui log in un intervallo di tempo:

    1. Fai clic sul menu Selettore ora in Grafana.

    2. Dal menu, esegui una delle seguenti azioni:

      • Seleziona le opzioni dell'intervallo di tempo relativo, ad esempio gli ultimi 30 minuti.
      • Imposta intervalli di tempo assoluti personalizzati scegliendo date e orari specifici dal calendario e facendo clic su Applica intervallo di tempo.

    3. (Facoltativo) Fai clic su Modifica impostazioni ora per modificare le impostazioni di Fuso orario e Anno fiscale dai controlli dell'intervallo di tempo.

    Le impostazioni dell'ora vengono salvate per ogni dashboard. Per ulteriori informazioni sulle query in un intervallo di tempo, vedi https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

    Inviare una query

    Invia una query all'endpoint dell'API Log Query utilizzando client HTTP o gRPC.

    HTTP

    Segui le istruzioni per accedere direttamente all'API con un client HTTP. Puoi affidarti a kubectl per gestire l'autenticazione o gestirla in autonomia.

    Esegui query sull'API Log Query utilizzando client HTTP come curl, wget o un client HTTP che crei e gestisci. Il seguente esempio utilizza lo strumento curl per eseguire query sull'API e puoi utilizzare un formato simile per i comandi wget:

    1. Autentica la richiesta cURL:

      1. Scarica e installa gcloud CLI.

      2. Imposta la proprietà core/organization_console_url di gcloud:

        gdcloud config set core/organization_console_url https://GDC_URL

        Sostituisci GDC_URL con l'URL di un'organizzazione in GDC.

      3. Accedi con il provider di identità configurato:

        gdcloud auth login

      4. Utilizza il tuo utente e la tua password per l'autenticazione e l'accesso.

      5. Esporta il token di identità per l'account specificato in una variabile di ambiente:

        export TOKEN="$($HOME/gdcloud auth print-identity-token --audiences=https://LOG_QUERY_API_ENDPOINT)"

        Sostituisci LOG_QUERY_API_ENDPOINT con l'endpoint dell'API Log Query da cui vuoi eseguire query sui log e il dominio a cui vuoi connetterti. Pertanto, il valore del flag audiences può essere, ad esempio, https://operational-log-query-api.org-1.zone1.google.gdch.test.

        Se l'accesso va a buon fine, puoi utilizzare l'intestazione di autorizzazione nella richiesta cURL tramite il comando gdcloud auth print-identity-token. Per saperne di più, consulta la pagina gdcloud auth print-identity-token.

    2. Se vuoi elencare tutte le etichette di un progetto, invia la seguente query:

      curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels \
-H "Content-Type: application/json" -v

      Sostituisci quanto segue:

      • LOG_QUERY_API_ENDPOINT: l'endpoint API Log Query da cui vuoi eseguire query sui log.
      • PROJECT_NAMESPACE: lo spazio dei nomi del progetto.

    3. Se vuoi elencare valori etichetta specifici per un progetto, invia la seguente query:

      curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels/labels/LABEL/values \
-H "Content-Type: application/json" -v

      Sostituisci quanto segue:

      • LOG_QUERY_API_ENDPOINT: l'endpoint API Log Query da cui vuoi eseguire query sui log.
      • PROJECT_NAMESPACE: lo spazio dei nomi del progetto.
      • LABEL: l'etichetta specifica per la quale vuoi eseguire una query sul valore.

    4. Se vuoi eseguire query sui log per un progetto specifico, crea una query logs_filter e includila nel corpo della richiesta:

      curl -X GET -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/logs \
-H "Content-Type: application/json" -d \
'{"logs_filter": {"labels_equal": {"LABEL": "LABEL_VALUE"}}}' -v

      Sostituisci quanto segue:

      • LOG_QUERY_API_ENDPOINT: l'endpoint API Log Query da cui vuoi eseguire query sui log.
      • PROJECT_NAMESPACE: lo spazio dei nomi del progetto.
      • LABEL: l'etichetta specifica per la quale vuoi eseguire query sui log.
      • LABEL_VALUE: il valore dell'etichetta per cui vuoi eseguire query sui log.

      Consulta la documentazione dell'API per visualizzare tutte le opzioni per creare una query logs_filter.

    gRPC

    gRPC è ampiamente supportato in tutti i linguaggi di programmazione e fornisce un metodo di comunicazione più efficiente rispetto ai client HTTP.

    Per eseguire query sui log utilizzando gRPC, devi soddisfare i seguenti prerequisiti:

    • Crea la tua libreria client in base ai buffer di protocollo forniti da Google.
    • Implementa l'autenticazione nel client.
    • Implementa i tentativi.

    Per informazioni sui buffer del protocollo, consulta la documentazione dell'API.

    L'esempio seguente mostra come eseguire query sui log da un programma Go utilizzando un client gRPC non autenticato. L'esempio presuppone che tu abbia creato un pacchetto golang che include un file di build Bazel per importare le dipendenze del codice:

    1. Salva il seguente codice in un programma Go denominato client.go:

      package main
import (
        "context"
        "crypto/tls"
        "flag"
        "fmt"
        "google.golang.org/grpc/credentials"
        "google.golang.org/grpc/metadata"
        pb "<import path to generated log query api protos>/pkg/apis/public/logging/v1/proto"
        "google.golang.org/grpc"
)

var serverAddr = flag.String("server", "localhost:8080", "server address")

func main() {
        flag.Parse()
        tc := credentials.NewTLS(&tls.Config{InsecureSkipVerify: true})
        conn, err := grpc.Dial(*serverAddr, grpc.WithTransportCredentials(tc))

        if err != nil {
                panic(error.Error(fmt.Errorf("create client connection failed: %v", err)))
        }
        defer conn.Close()

        c := pb.NewLogsClient(conn)
        md := metadata.Pairs("clienttest", "test")
        ctx := metadata.NewOutgoingContext(context.Background(), md)

        err = listLabels(ctx, c, "project-foo")
        if err != nil {
                panic(error.Error(err))
        }

        if err := listLabelValues(ctx, c, "project-foo", "resource-bar"); err != nil {
                panic(error.Error(err))
        }

        if err := listLogs(ctx, c, "project-foo", &pb.ListLogsFilter{
                LabelsEqual:    map[string]string{"resource-bar": "resource-bar-value"},
                OrderAscending: true,
        }); err != nil {
                panic(error.Error(err))
        }
}

// List all labels for a project.

func listLabels(ctx context.Context, c pb.LogsClient, project string) error {
        lbr := &pb.ListLabelsRequest{
                Parent:   project,
                PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLabels(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list labels: %v", err)
        }
        fmt.Printf("%v", resp)
        return nil
}

// List specific label values for a project.

func listLabelValues(ctx context.Context, c pb.LogsClient, project string, label string) error {
        lbr := &pb.ListLabelValuesRequest{
                Parent:   project,
                Label:    label,
                PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLabelValues(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list label values: %v", err)
        }
        fmt.Printf("%v", resp)
        return nil
}

// List logs for a specific project.

func listLogs(ctx context.Context, c pb.LogsClient, project string, lf *pb.ListLogsFilter) error {
        lbr := &pb.ListLogsRequest{
                Parent:     project,
                LogsFilter: lf,
                PageSize:   5, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLogs(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list logs: %v", err)
        }
        fmt.Printf("logs: %v", resp)
        return nil
}

    2. Esegui il programma Go:

      go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443

      Sostituisci quanto segue:

      • PATH_TO_API: il percorso del file API.
      • LOG_QUERY_API_ENDPOINT: l'endpoint API Log Query da cui vuoi eseguire query sui log.

      Se il flag del server non è specificato, la richiesta predefinita arriva a localhost.

Query ed etichette di esempio

Di seguito sono riportate alcune delle etichette predefinite che puoi utilizzare per eseguire query sui log:

  • cluster: il nome del cluster.
  • namespace: lo spazio dei nomi del progetto.
  • node: il nome del nodo.
  • pod: il nome del pod.
  • container: il nome del container.

I seguenti esempi di codice mostrano l'utilizzo di etichette e valori per eseguire query su log diversi:

  • Seleziona i log del server:

    {cluster="admin", namespace="kube-system", resources="k8s_container", container="kube-apiserver"}

  • Seleziona i log di controllo del cluster:

    {cluster="admin", resources="k8s_audit"}