Interrogation et affichage des journaux

Cette page fournit des instructions détaillées sur la façon d'interroger et de visualiser vos journaux à l'aide de l'interface utilisateur Grafana pour obtenir des insights sur les événements et l'activité de votre service.

Après avoir collecté les journaux de vos charges de travail et services déployés dans l'appliance isolée Google Distributed Cloud (GDC), vous pouvez commencer à les analyser. Pour analyser les journaux, vous pouvez les visualiser et les filtrer dans des panneaux Grafana informatifs ou des appels gRPC pour un accès programmatique.

Vous pouvez accéder à vos journaux de la manière suivante :

  • Panneaux Grafana : obtenez des insights sur l'enregistrement d'activité de votre projet via le panneau "Journaux" de votre instance Grafana. Ce panneau vous permet d'interroger et d'identifier des journaux spécifiques, en fournissant une observabilité des données précise et adaptée à vos besoins. Grafana fournit une interface conviviale pour filtrer et analyser les données de votre charge de travail, en créant des tableaux de bord et des panneaux personnalisés pour une visualisation complète.

Avant de commencer

Pour obtenir les autorisations nécessaires pour interroger et visualiser les journaux dans l'interface utilisateur Grafana, demandez à votre administrateur IAM de l'organisation ou administrateur IAM du projet de vous accorder l'un des rôles prédéfinis Lecteur Grafana de l'organisation ou Lecteur Grafana du projet. Selon le niveau d'accès et les autorisations dont vous avez besoin, vous pouvez obtenir des rôles Grafana dans une organisation ou un projet.

Vous pouvez également demander à votre administrateur IAM du projet de vous accorder le rôle Interrogateur de l'API Log Query dans l'espace de noms de votre projet pour obtenir les autorisations nécessaires pour interroger les journaux à partir de l'API Log Query.

Pour en savoir plus sur ces rôles, consultez Préparer les autorisations IAM.

Créer des requêtes pour vos journaux

L'interrogation des journaux à partir de l'interface utilisateur de l'instance de surveillance du système vous permet de choisir la source de données à partir de laquelle récupérer les journaux opérationnels de votre projet et d'obtenir une vue intégrée de vos requêtes. Pour filtrer les résultats, recherchez les journaux par libellés à l'aide d'expressions de langage de requête. Par exemple, vous pouvez définir les libellés cluster et namespace dans vos requêtes sur les valeurs qui identifient respectivement votre cluster et l'espace de noms de votre projet.

Point de terminaison de l'instance de surveillance du système

Pour l'opérateur d'application (AO)

L'URL suivante correspond au point de terminaison de l'instance de surveillance de votre projet :

https://GDC_URL/PROJECT_NAMESPACE/grafana

Remplacez les éléments suivants :

  • GDC_URL : URL de votre organisation dans GDC.
  • PROJECT_NAMESPACE : espace de noms de votre projet.

Pour l'administrateur de plate-forme (PA)

L'URL suivante correspond au point de terminaison de l'instance de surveillance de votre projet :

https://GDC_URL/platform-obs/grafana

Remplacez GDC_URL par l'URL de votre organisation dans GDC.

Interroger et filtrer vos journaux

Sélectionnez l'une des méthodes suivantes pour créer des requêtes et filtrer les journaux de vos charges de travail de projet :

Cette section explique comment accéder à vos journaux à l'aide du panneau "Journaux" dans Grafana.

Identifier votre point de terminaison Grafana

Pour l'opérateur d'application (AO)

L'URL suivante correspond au point de terminaison de l'instance de surveillance de votre projet :

https://GDC_URL/PROJECT_NAMESPACE/grafana

Remplacez les éléments suivants :

  • GDC_URL : URL de votre organisation dans GDC.
  • PROJECT_NAMESPACE : espace de noms de votre projet.

Pour l'administrateur de plate-forme (PA)

L'URL suivante correspond au point de terminaison de l'instance de surveillance de votre projet :

https://GDC_URL/platform-obs/grafana

Remplacez GDC_URL par l'URL de votre organisation dans GDC.

Afficher les journaux dans l'interface utilisateur Grafana

Interrogez les journaux dans l'interface utilisateur Grafana :

  1. Dans la console GDC, sélectionnez votre projet.
  2. Dans le menu de navigation, sélectionnez Opérations > Logging.
  3. Cliquez sur Tout afficher dans Grafana Loki.

Une nouvelle page s'ouvre sur votre point de terminaison Grafana et affiche l'interface utilisateur.

  1. Dans l'interface utilisateur, cliquez sur explore Explore dans le menu de navigation pour ouvrir la page Explore.
  2. Dans le menu de la barre Explore, sélectionnez une source de données pour récupérer les journaux, en fonction du type de votre univers :

  • Univers à zone unique : sélectionnez l'une des sources de données suivantes pour afficher les données de journalisation de la zone unique de votre univers :

  • Journaux opérationnels : affichez les journaux opérationnels.

  • Journaux d'audit : affichez les journaux d'audit.

  • Journaux opérationnels ZONE_NAME : affichez les journaux opérationnels d'une zone spécifique.

  • Journaux d'audit ZONE_NAME : affichez les journaux d'audit d'une zone spécifique.

De plus, pour afficher des visualisations de données interzones dans un seul tableau de bord et ajouter plusieurs zones à votre requête, sélectionnez Mixte comme source de données.

  1. Saisissez une requête pour rechercher des journaux à partir du panneau "Journaux" à l'aide d'expressions LogQL (langage de requête de journal). Vous pouvez effectuer cette étape de l'une des manières suivantes :

    • Utilisez l'interface interactive du générateur de requêtes. Cliquez ensuite sur Exécuter la requête.
    • Saisissez votre requête directement dans le champ de texte, puis appuyez sur Maj+Entrée pour l'exécuter.

    La page affiche les journaux correspondant à votre requête. Après avoir interrogé les journaux, vous pouvez les exporter. Cliquez sur Exporter pour télécharger les journaux au format texte brut ou CSV. Vous pouvez également sélectionner une période pour vos journaux.

    L'option "Journaux d'audit" est sélectionnée sur la page "Explorer" pour obtenir les journaux d'audit.

    Figure 1 : Option de menu permettant d'interroger les journaux d'audit à partir de l'interface utilisateur Grafana.

    Dans la figure 1, l'option Journaux d'audit affiche l'interface qui vous permet de créer des requêtes à partir de Grafana pour récupérer les journaux d'audit.

    Pour obtenir des exemples de libellés et de valeurs permettant d'interroger différents journaux, consultez Exemples de requêtes et de libellés.

    Sélectionner une période pour vos journaux

    Pour interroger les journaux sur une période donnée, procédez comme suit :

    1. Cliquez sur le menu Time Picker (Sélecteur de période) dans Grafana.

    2. Dans le menu, effectuez l'une des actions suivantes :

      • Sélectionnez des options de période relative, par exemple les 30 dernières minutes.
      • Définissez des périodes absolues personnalisées en choisissant des dates et heures spécifiques dans le calendrier, puis en cliquant sur Apply time range (Appliquer la période).

    3. Vous pouvez également cliquer sur Change time settings (Modifier les paramètres de période) pour modifier les paramètres Timezone (Fuseau horaire) et Fiscal year (Exercice fiscal) à partir des commandes de période.

    Les paramètres de période sont enregistrés par tableau de bord. Pour en savoir plus sur les requêtes sur une période donnée, consultez https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

    Envoyer une requête

    Envoyez une requête au point de terminaison de l'API Log Query à l'aide de clients HTTP ou gRPC.

    HTTP

    Suivez les instructions pour accéder directement à l'API avec un client HTTP. Vous pouvez vous appuyer sur kubectl pour gérer l'authentification ou la gérer vous-même.

    Interrogez l'API Log Query à l'aide de clients HTTP tels que curl, wget ou un client HTTP que vous créez et gérez. L'exemple suivant utilise l'outil curl pour interroger l'API. Vous pouvez utiliser un format semblable pour les commandes wget :

    1. Authentifiez la requête cURL :

      1. Téléchargez et installez la gdcloud CLI.

      2. Définissez la propriété gdcloud core/organization_console_url :

        gdcloud config set core/organization_console_url https://GDC_URL

        Remplacez GDC_URL par l'URL d'une organisation dans GDC.

      3. Connectez-vous avec le fournisseur d'identité configuré :

        gdcloud auth login

      4. Utilisez votre nom d'utilisateur et votre mot de passe pour vous authentifier et vous connecter.

      5. Exportez le jeton d'identité du compte spécifié vers une variable d'environnement :

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

        Remplacez LOG_QUERY_API_ENDPOINT par le point de terminaison de l'API Log Query à partir duquel vous souhaitez interroger les journaux et le domaine auquel vous souhaitez vous connecter. Par conséquent, la valeur de l'option audiences peut être, par exemple, https://operational-log-query-api.org-1.zone1.google.gdch.test.

        Une fois la connexion établie, vous pouvez utiliser l'en-tête d'autorisation dans votre requête cURL via la commande gdcloud auth print-identity-token. Pour en savoir plus, consultez gdcloud auth print-identity-token.

    2. Si vous souhaitez répertorier tous les libellés d'un projet, envoyez la requête suivante :

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

      Remplacez les éléments suivants :

    3. Si vous souhaitez répertorier des valeurs de libellé spécifiques pour un projet, envoyez la requête suivante :

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

      Remplacez les éléments suivants :

    4. Si vous souhaitez interroger les journaux d'un projet spécifique, créez une requête logs_filter et incluez-la dans le corps de la requête :

      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

      Remplacez les éléments suivants :

      Consultez la documentation de l'API pour voir toutes les options permettant de créer une requête logs_filter.

    gRPC

    gRPC est largement compatible avec les langages de programmation et fournit une méthode de communication plus efficace que les clients HTTP.

    Pour interroger les journaux à l'aide de gRPC, vous devez répondre aux prérequis suivants :

    • Créez votre propre bibliothèque cliente basée sur les tampons de protocole fournis par Google.
    • Implémentez l'authentification dans le client.
    • Implémentez les nouvelles tentatives.

    Pour en savoir plus sur les tampons de protocole, consultez la documentation de l'API.

    L'exemple suivant montre comment interroger les journaux à partir d'un programme Go à l'aide d'un client gRPC non authentifié. L'exemple suppose que vous avez créé un package golang qui inclut un fichier de compilation Bazel pour importer les dépendances de code :

    1. Enregistrez le code suivant dans un programme Go nommé 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. Exécutez le programme Go :

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

      Remplacez les éléments suivants :

      Si l'option de serveur n'est pas spécifiée, la requête par défaut est envoyée à localhost.

Exemples de requêtes et de libellés

Voici quelques-uns des libellés par défaut que vous pouvez utiliser pour interroger les journaux :

  • cluster : nom du cluster.
  • namespace : espace de noms de votre projet.
  • node : nom du nœud.
  • pod : nom du pod.
  • container : nom du conteneur.

Les exemples de code suivants montrent l'utilisation de libellés et de valeurs pour interroger différents journaux :

  • Sélectionnez les journaux du serveur :

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

  • Sélectionnez les journaux d'audit du cluster :

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