Logs abfragen und ansehen

Mit der Logabfrage in der GDC-Appliance (Google Distributed Cloud) mit Air Gap können Sie Betriebs- und Audit-Ereignisse in Ihren Projektarbeitslasten prüfen, nachdem Sie Logs erfasst haben. Sie können Logstreams im Grafana-Logbereich mit Log Query Language-Ausdrücken (LogQL) filtern, visualisieren und exportieren. Für programmatische Workflows können Sie die Log Query API Ihrer Organisation über HTTP oder gRPC abfragen. Folgen Sie dazu den Standardmethoden für den API-Zugriff.

Hinweis

Bitten Sie den IAM-Administrator Ihrer Organisation oder den IAM-Administrator Ihres Projekts, Ihnen eine der vordefinierten Rollen „Organization Grafana Viewer“ oder „Project Grafana Viewer“ zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Abfragen und Visualisieren von Logs in der Grafana-Benutzeroberfläche benötigen. Je nach erforderlicher Zugriffsebene und Berechtigungen können Sie Grafana-Rollen in einer Organisation oder einem Projekt erhalten.

Alternativ können Sie Ihren Project IAM Admin bitten, Ihnen die Rolle „Log Query API Querier“ in Ihrem Projekt-Namespace zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Abfragen von Logs über die Log Query API benötigen.

Weitere Informationen zu diesen Rollen finden Sie unter IAM-Berechtigungen vorbereiten.

Abfragen für Ihre Logs erstellen

Wenn Sie Logs über die Benutzeroberfläche der Systemmonitoring-Instanz abfragen, können Sie die Datenquelle auswählen, aus der Betriebslogs aus Ihrem Projekt abgerufen werden sollen, und erhalten eine integrierte Ansicht Ihrer Abfragen. Wenn Sie Ergebnisse filtern möchten, suchen Sie mithilfe von Ausdrücken der Abfragesprache nach Logs nach Labels. Sie können beispielsweise die Labels cluster und namespace in Ihren Abfragen auf die Werte festlegen, die Ihren Cluster bzw. Projekt-Namespace identifizieren.

Endpunkt der Systemmonitoring-Instanz

Für Anwendungsoperatoren (AO)

Die folgende URL ist der Endpunkt der Monitoring-Instanz Ihres Projekts:

https://GDC_URL/PROJECT_NAMESPACE/grafana

Ersetzen Sie Folgendes:

  • GDC_URL: Die URL Ihrer Organisation in GDC.
  • PROJECT_NAMESPACE: Der Namespace Ihres Projekts.

Für Plattformadministratoren

Die folgende URL ist der Endpunkt der Monitoring-Instanz Ihres Projekts:

https://GDC_URL/platform-obs/grafana

Ersetzen Sie GDC_URL durch die URL Ihrer Organisation in GDC.

Logs abfragen und filtern

Wählen Sie eine der folgenden Methoden aus, um Abfragen zu erstellen und Logs aus Ihren Projektarbeitslasten zu filtern:

In diesem Abschnitt wird beschrieben, wie Sie über das Logfeld in Grafana auf Ihre Logs zugreifen.

Grafana-Endpunkt identifizieren

Für Anwendungsoperatoren (AO)

Die folgende URL ist der Endpunkt der Monitoring-Instanz Ihres Projekts:

https://GDC_URL/PROJECT_NAMESPACE/grafana

Ersetzen Sie Folgendes:

  • GDC_URL: Die URL Ihrer Organisation in GDC.
  • PROJECT_NAMESPACE: Der Namespace Ihres Projekts.

Für Plattformadministratoren

Die folgende URL ist der Endpunkt der Monitoring-Instanz Ihres Projekts:

https://GDC_URL/platform-obs/grafana

Ersetzen Sie GDC_URL durch die URL Ihrer Organisation in GDC.

Logs in der Grafana-Benutzeroberfläche ansehen

Fragen Sie Logs in der Grafana-Benutzeroberfläche ab:

  1. Wählen Sie in der GDC-Konsole Ihr Projekt aus.
  2. Wählen Sie im Navigationsmenü Vorgänge > Logging aus.
  3. Klicken Sie auf Alle in Grafana Loki ansehen.

Auf einer neuen Seite wird Ihr Grafana-Endpunkt geöffnet und die Benutzeroberfläche angezeigt.

  1. Klicken Sie auf der Benutzeroberfläche im Navigationsmenü auf Explore Explore, um die Seite Explore zu öffnen.
  2. Wählen Sie im Menü in der Leiste Explore eine Datenquelle aus, um Logs abzurufen, je nach Universumstyp:

  • Universen mit einer einzelnen Zone: Wählen Sie eine der folgenden Datenquellen aus, um Logging-Daten aus der einzelnen Zone Ihres Universums anzuzeigen:

  • Betriebslogs: Betriebslogs anzeigen.

  • Audit-Logs: Audit-Logs anzeigen.

  • Betriebslogs ZONE_NAME: Zeigt Betriebslogs aus einer bestimmten Zone an.

  • Audit-Logs ZONE_NAME: Audit-Logs aus einer bestimmten Zone anzeigen.

Wenn Sie zonenübergreifende Datenvisualisierungen in einem einzigen Dashboard anzeigen und Ihrer Abfrage mehrere Zonen hinzufügen möchten, wählen Sie Gemischt als Datenquelle aus.

  1. Geben Sie eine Abfrage ein, um im Logbereich mithilfe von LogQL-Ausdrücken (Log Query Language) nach Logs zu suchen. Sie können diesen Schritt über eine der beiden folgenden Methoden ausführen:

    • Verwenden Sie die interaktive Query Builder-Oberfläche. Klicken Sie dann auf Abfrage ausführen.
    • Geben Sie die Abfrage direkt in das Textfeld ein und drücken Sie Umschalttaste + Eingabetaste, um die Abfrage auszuführen.

    Auf der Seite werden die Logs angezeigt, die Ihrer Abfrage entsprechen. Nachdem Sie Protokolle abgefragt haben, können Sie sie exportieren. Klicken Sie auf Exportieren, um Logs im Nur-Text- oder CSV-Format herunterzuladen. Sie können auch einen Zeitraum für Ihre Protokolle auswählen.

    Auf der Seite „Erkunden“ ist die Option „Audit-Logs“ ausgewählt, um Audit-Logs abzurufen.

    Abbildung 1. Menüoption zum Abfragen von Audit-Logs über die Grafana-Benutzeroberfläche.

    In Abbildung 1 wird mit der Option Audit-Logs die Oberfläche angezeigt, über die Sie Abfragen in Grafana erstellen können, um Audit-Logs abzurufen.

    Beispiele für Labels und Werte zum Abfragen verschiedener Logs finden Sie unter Beispielabfragen und ‑labels.

    Zeitraum für Ihre Logs auswählen

    So fragen Sie Logs in einem Zeitraum ab:

    1. Klicken Sie in Grafana auf das Menü Zeitauswahl.

    2. Führen Sie im Menü eine der folgenden Aktionen aus:

      • Wählen Sie Optionen für relative Zeiträume aus, z. B. die letzten 30 Minuten.
      • Sie können benutzerdefinierte absolute Zeiträume festlegen, indem Sie im Kalender bestimmte Datumsangaben und Uhrzeiten auswählen und auf Zeitraum anwenden klicken.

    3. Optional: Klicken Sie auf Zeiteinstellungen ändern, um die Einstellungen für Zeitzone und Geschäftsjahr über die Steuerelemente für den Zeitraum zu ändern.

    Zeiteinstellungen werden für jedes Dashboard einzeln gespeichert. Weitere Informationen zu Abfragen über einen bestimmten Zeitraum finden Sie unter https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

    Abfrage senden

    Senden Sie eine Abfrage an den Log Query API-Endpunkt mithilfe von HTTP- oder gRPC-Clients.

    HTTP

    Folgen Sie der Anleitung, um mit einem HTTP-Client direkt auf die API zuzugreifen. Sie können die Authentifizierung von kubectl verwalten lassen oder selbst übernehmen.

    Fragen Sie die Log Query API mit HTTP-Clients wie curl, wget oder einem von Ihnen erstellten und verwalteten HTTP-Client ab. Im folgenden Beispiel wird das Tool curl verwendet, um die API abzufragen. Sie können ein ähnliches Format für wget-Befehle verwenden:

    1. Authentifizieren Sie die cURL-Anfrage:

      1. Laden Sie die gdcloud CLI herunter und installieren Sie sie.

      2. Legen Sie das gdcloud-Attribut core/organization_console_url fest:

        gdcloud config set core/organization_console_url https://GDC_URL

        Ersetzen Sie GDC_URL durch die URL einer Organisation in GDC.

      3. Melden Sie sich mit dem konfigurierten Identitätsanbieter an:

        gdcloud auth login

      4. Verwenden Sie Ihren Nutzernamen und Ihr Passwort, um sich zu authentifizieren und anzumelden.

      5. Exportieren Sie das Identitätstoken für das angegebene Konto in eine Umgebungsvariable:

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

        Ersetzen Sie LOG_QUERY_API_ENDPOINT durch den Log Query API-Endpunkt, von dem aus Sie Logs abfragen möchten, und die Domain, zu der Sie eine Verbindung herstellen möchten. Der Wert für das Flag audiences kann daher beispielsweise https://operational-log-query-api.org-1.zone1.google.gdch.test sein.

        Wenn die Anmeldung erfolgreich ist, können Sie den Autorisierungsheader in Ihrer cURL-Anfrage mit dem Befehl gdcloud auth print-identity-token verwenden. Weitere Informationen finden Sie unter gdcloud auth print-identity-token.

    2. Wenn Sie alle Labels für ein Projekt auflisten möchten, senden Sie die folgende Abfrage:

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

      Ersetzen Sie Folgendes:

      • LOG_QUERY_API_ENDPOINT: der Log Query API-Endpunkt, von dem Sie Logs abfragen möchten.
      • PROJECT_NAMESPACE: Ihr Projekt-Namespace.

    3. Wenn Sie bestimmte Labelwerte für ein Projekt auflisten möchten, senden Sie die folgende Abfrage:

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

      Ersetzen Sie Folgendes:

      • LOG_QUERY_API_ENDPOINT: der Log Query API-Endpunkt, von dem Sie Logs abfragen möchten.
      • PROJECT_NAMESPACE: Ihr Projekt-Namespace.
      • LABEL: das spezifische Label, dessen Wert Sie abfragen möchten.

    4. Wenn Sie Logs für ein bestimmtes Projekt abfragen möchten, erstellen Sie eine logs_filter-Abfrage und fügen Sie sie in den Text der Anfrage ein:

      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

      Ersetzen Sie Folgendes:

      • LOG_QUERY_API_ENDPOINT: der Log Query API-Endpunkt, von dem Sie Logs abfragen möchten.
      • PROJECT_NAMESPACE: Ihr Projekt-Namespace.
      • LABEL: das spezifische Label, für das Sie Logs abfragen möchten.
      • LABEL_VALUE: Der Labelwert, für den Sie Logs abfragen möchten.

      In der API-Dokumentation finden Sie alle Optionen zum Erstellen einer logs_filter-Abfrage.

    gRPC

    gRPC wird von vielen Programmiersprachen unterstützt und bietet eine effizientere Kommunikationsmethode als HTTP-Clients.

    Wenn Sie Logs mit gRPC abfragen möchten, müssen die folgenden Voraussetzungen erfüllt sein:

    • Erstellen Sie Ihre eigene Clientbibliothek auf Grundlage der von Google bereitgestellten Protokollzwischenspeicher.
    • Authentifizierung im Client implementieren
    • Wiederholungsversuche implementieren

    Informationen zu den Protokollzwischenspeichern finden Sie in der API-Dokumentation.

    Im folgenden Beispiel wird gezeigt, wie Sie Logs aus einem Go-Programm mit einem nicht authentifizierten gRPC-Client abfragen. In diesem Beispiel wird davon ausgegangen, dass Sie ein Golang-Paket erstellt haben, das eine Bazel-Build-Datei zum Importieren von Codeabhängigkeiten enthält:

    1. Speichern Sie den folgenden Code in einem Go-Programm mit dem Namen 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. Führen Sie das Go-Programm aus:

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

      Ersetzen Sie Folgendes:

      • PATH_TO_API: der Pfad zur API-Datei.
      • LOG_QUERY_API_ENDPOINT: der Log Query API-Endpunkt, von dem Sie Logs abfragen möchten.

      Wenn das Server-Flag nicht angegeben ist, wird die Standardanfrage an localhost gesendet.

Beispielabfragen und ‑labels

Im Folgenden finden Sie einige der Standardlabels, die Sie zum Abfragen von Logs verwenden können:

  • cluster ist der Name des Clusters.
  • namespace: Ihr Projekt-Namespace.
  • node: der Knotenname.
  • pod: der Pod-Name.
  • container: der Containername.

Die folgenden Codebeispiele zeigen die Verwendung von Labels und Werten zum Abfragen verschiedener Logs:

  • Server-Logs auswählen:

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

  • Wählen Sie Cluster-Audit-Logs aus:

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