Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Esegui query e visualizza i log

La query dei log in Google Distributed Cloud (GDC) con air gap ti consente di ispezionare gli eventi operativi e di controllo nei workload del progetto dopo aver raccolto i log. Puoi filtrare, visualizzare ed esportare gli stream di log nel riquadro dei log di Grafana con espressioni LogQL (Log Query Language). Per i flussi di lavoro programmatici, esegui query sull'API Log Query della tua organizzazione tramite HTTP o gRPC seguendo i metodi di accesso API standard.

Prima di iniziare

Per eseguire query e visualizzare i log, devi disporre delle autorizzazioni necessarie.

Richiedi ruoli IAM dell'organizzazione

Contatta l'amministratore dell'organizzazione IAM per richiedere i seguenti ruoli:

Organization Grafana Viewer (organization-grafana-viewer): visualizza i dati di osservabilità relativi all'organizzazione nelle dashboard dell'istanza di monitoraggio di Grafana.
Log Querier (log-query-api-querier-pa): accedi all'API Log Query per eseguire query sui log della piattaforma nel progetto platform-obs.

Richiedi ruoli IAM per il progetto

Contatta l'amministratore del progetto IAM per richiedere i seguenti ruoli:

Project Grafana Viewer (project-grafana-viewer): visualizza i dati di osservabilità relativi al progetto nelle dashboard dell'istanza di monitoraggio di Grafana nello spazio dei nomi del progetto.
Log Querier (log-query-api-querier): accedi all'API Log Query per eseguire query sui log delle applicazioni nello spazio dei nomi del progetto.

La tabella seguente riassume i requisiti di Role per i personaggi PA e AO:

Utente tipo	Oggetto	Cluster	Ruolo	Spazio dei nomi	Gruppo/utente
PA	`grafana`	server API di gestione	`project-grafana-viewer`	`platform-obs`	Gruppo
PA	`log-query-api`	server API di gestione	`log-query-api-querier-pa`	`platform-obs`	Gruppo
PA	`grafana`	server API di gestione	`project-grafana-viewer`	`platform-obs`	Utente
PA	`log-query-api`	server API di gestione	`log-query-api-querier-pa`	`platform-obs`	Utente
AO	`grafana`	server API di gestione	`project-grafana-viewer`	`PROJECT_NAMESPACE`	Gruppo
AO	`log-query-api`	server API di gestione	`log-query-api-querier`	`PROJECT_NAMESPACE`	Gruppo
AO	`grafana`	server API di gestione	`project-grafana-viewer`	`PROJECT_NAMESPACE`	Utente
AO	`log-query-api`	server API di gestione	`log-query-api-querier`	`PROJECT_NAMESPACE`	Utente

Seleziona una delle seguenti configurazioni per concedere a Grafana l'accesso a un gruppo di utenti (Config 1) o a un singolo utente (Config 2) sul server API di gestione. Per ogni configurazione, puoi eseguire il comando kubectl per creare direttamente RoleBinding o salvare il manifest YAML RoleBinding nel percorso del file Infrastructure as Code (IaC) specificato per applicarlo tramite GitOps:

Configurazione 1

Questa configurazione concede le autorizzazioni a un gruppo di utenti per accedere a PA e AO Grafana sul server API di gestione. Dopo aver impostato questa configurazione, consulta la sezione Dashboard di Grafana di questo documento per visualizzare i log su Grafana.

comando kubectl

Esegui questo comando per creare direttamente RoleBinding:

kubectl --kubeconfig KUBECONFIG create rolebinding RULE_NAME -n platform-obs --group=GROUP_NAME --role=project-grafana-viewer

Esempio:

kubectl --kubeconfig KUBECONFIG_PATH create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs

Percorso file IaC

In alternativa, per gestire RoleBinding utilizzando IaC, crea il file YAML nel seguente percorso:
```
/infrastructure/zonal/zones/ZONE/org-admin/rolebindings/GROUP_NAME/YAML_FILE
```

File YAML

Salva il seguente manifest RoleBinding nel file YAML nel percorso del file IaC:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

Configurazione 2

Questa configurazione concede a un utente le autorizzazioni per accedere a PA e AO Grafana sul server API di gestione. Dopo aver configurato questa impostazione, consulta la sezione Dashboard di Grafana di questo documento per visualizzare i log su Grafana.

comando kubectl

Esegui questo comando per creare direttamente RoleBinding:

kubectl --kubeconfig KUBECONFIG create rolebinding RULE_NAME -n platform-obs --user=EMAIL_ADDRESS --role=project-grafana-viewer

Esempio:

kubectl --kubeconfig KUBECONFIG_PATH create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obs

Percorso file IaC

In alternativa, per gestire RoleBinding utilizzando IaC, crea il file YAML nel seguente percorso:
```
/infrastructure/zonal/zones/ZONE/org-admin/rolebindings/EMAIL_ADDRESS/YAML_FILE
```

File YAML

Salva il seguente manifest RoleBinding nel file YAML nel percorso del file IaC:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

Sostituisci quanto segue:

KUBECONFIG: il percorso del file kubeconfig per il cluster specifico che contiene NAMESPACE in cui viene applicato questo RoleBinding.
KUBECONFIG_PATH: il percorso del file kubeconfig nei comandi di esempio.
RULE_NAME: il nome univoco di questa risorsa RoleBinding all'interno dello spazio dei nomi, ad esempio pa-project-grafana-viewer.
NAMESPACE: lo spazio dei nomi Kubernetes in cui viene creata e applicata questa RoleBinding. Cerca la colonna Namespace nella tabella precedente.
EMAIL_ADDRESS: l'identificatore dell'utente a cui viene concesso il ruolo, ad esempio application-operator@example.com.
ROLE: il nome del Role che contiene le autorizzazioni che vuoi concedere all'utente. Cerca i ruoli disponibili nella tabella precedente.
GROUP_NAME: il nome della Group a cui appartiene l'utente PA, ad esempio pa-group.
ZONE: il nome della zona
YAML_FILE: il nome del file YAML per la risorsa RoleBinding.

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

Esegui query e filtra i log

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

Riquadro dei log di Grafana

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

Identifica l'endpoint Grafana

Il seguente URL è l'endpoint dell'istanza Grafana 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.

Ad esempio, l'endpoint Grafana per il progetto platform-obs nell'organizzazione org-1 è https://org-1/platform-obs/grafana.

Visualizza i log nell'interfaccia utente di Grafana

Esegui query sui log nell'interfaccia utente di Grafana:

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

Si apre una nuova pagina con l'endpoint Grafana e viene visualizzata l'interfaccia utente.
Nell'interfaccia utente, fai clic su explore Esplora nel menu di navigazione per aprire la pagina Esplora.
Dal menu della barra Esplora, seleziona un'origine dati per recuperare i log in base al tipo di universo:
- Universe a zona singola: seleziona una delle seguenti origini dati per visualizzare i dati di logging della singola zona dell'universo:
  - Log operativi: visualizza i log operativi.
  - Audit log: visualizza gli audit log.
- Universi multizona: Grafana può connettersi a zone diverse e mostrare dati tra zone. Seleziona una delle seguenti origini dati per visualizzare i dati di logging di qualsiasi zona del tuo universo, indipendentemente dalla zona a cui hai eseguito l'accesso:
  - Log operativi ZONE_NAME: visualizza i log operativi di una determinata zona.
  - Audit log ZONE_NAME: visualizza gli audit log di una determinata zona.
  Inoltre, per avere visualizzazioni dei dati tra zone in un'unica dashboard e aggiungere più zone alla query, seleziona Misto come origine dati.
  
  Nota: gli audit log sono disponibili solo per gli amministratori della piattaforma, anche se non possono creare o configurare destinazioni di audit logging. Gli operatori delle applicazioni possono accedere solo ai log operativi.
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 Query Builder. 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 query sui log, puoi esportarli. Fai clic su Esporta per scaricare i log in formato testo normale o CSV. Puoi anche selezionare un intervallo di tempo per i log.

Figura 1. Opzione di menu per eseguire query sugli audit log dall'interfaccia utente di Grafana.

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

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

Seleziona un intervallo di tempo per i log

Per eseguire query sui log in un intervallo di tempo, segui questi passaggi:

Fai clic sul menu Selettore di ora in Grafana.
Dal menu, esegui una delle seguenti azioni:
- Seleziona le opzioni relative all'intervallo di tempo, ad esempio gli ultimi 30 minuti.
- Imposta intervalli di tempo assoluti personalizzati scegliendo date e ore specifiche dal calendario e facendo clic su Applica intervallo di tempo.
Facoltativamente, fai clic su Modifica impostazioni ora per modificare le impostazioni Fuso orario e Anno fiscale dai controlli dell'intervallo di tempo.

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

API Log Query

Questa sezione descrive come accedere ai log utilizzando l'API Log Query.

Identifica l'endpoint API Log Query

L'API Log Query espone i seguenti due endpoint per eseguire query sugli audit log e sui log operativi:

Endpoint dell'audit log:
```
audit-log-query-api.ORG_DOMAIN
```
Nota: gli audit log sono disponibili solo per gli amministratori della piattaforma, anche se non possono creare o configurare destinazioni di audit logging. Gli operatori delle applicazioni possono accedere solo ai log operativi.
Endpoint del log operativo:
```
operational-log-query-api.ORG_DOMAIN
```

Sostituisci ORG_DOMAIN con il nome di dominio dell'organizzazione. Puoi visualizzare questa proprietà utilizzando il comando gdcloud config list. Il nome di dominio deve seguire la sintassi org-name.zone.google.gdch.com. Ad esempio, un'organizzazione denominata org-1, nella zona zone1 e in un ambiente di test ha un dominio come org-1.zone1.google.gdch.test.

L'API Log Query ha le seguenti tre opzioni di endpoint:

labels: elenca tutte le etichette di un progetto.
labels/labels/LABEL/values: elenca i valori delle etichette specifici per un progetto.
logs: elenca i log per un progetto specifico.

Per saperne di più, consulta la documentazione dell'API.

Invia una query

Invia una query all'endpoint 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. L'esempio seguente utilizza lo strumento curl per eseguire query sull'API. Puoi utilizzare un formato simile per i comandi wget:

Autentica la richiesta cURL:
1. Scarica e installa l'interfaccia a riga di comando gdcloud.
2. Imposta la proprietà gdcloud core/organization_console_url:
```
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 nome utente e la tua password per autenticarti e accedere.
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 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.
  
  Una volta eseguito l'accesso, puoi utilizzare l'intestazione di autorizzazione nella richiesta cURL tramite il comando gdcloud auth print-identity-token. Per saperne di più, consulta gdcloud auth print-identity-token.
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.
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 di cui vuoi eseguire una query sul valore.
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 cui 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 la creazione di una query logs_filter.

gRPC

gRPC è ampiamente supportato nei 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 basata sui buffer di protocollo forniti da Google.
Implementa l'autenticazione nel client.
Implementa i nuovi tentativi.

Per informazioni sui buffer di 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:

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
}

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 dell'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 viene inviata 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 gli audit log del cluster:

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