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 informations 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'historique d'activité de votre projet grâce au panneau "Journaux" de votre instance Grafana. Ce panneau vous permet d'interroger et d'identifier des journaux spécifiques, ce qui vous offre une observabilité précise des données adaptée à vos besoins. Grafana fournit une interface conviviale pour filtrer et analyser les données de votre charge de travail, et créer 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 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 de projet IAM de vous accorder le rôle "Requêteur 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

Lorsque vous interrogez des journaux depuis l'UI de l'instance de surveillance du système, vous pouvez choisir la source de données à partir de laquelle récupérer les journaux opérationnels de votre projet et 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 du 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 est le 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 les administrateurs de plate-forme

L'URL suivante est le 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" de Grafana.

Identifier votre point de terminaison Grafana

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

L'URL suivante est le 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 les administrateurs de plate-forme

L'URL suivante est le 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 de 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 > Journalisation.
  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 Explorer Explorer dans le menu de navigation pour ouvrir la page Explorer.
  2. Dans le menu de la barre Explorer, sélectionnez une source de données pour récupérer les journaux, en fonction de votre type d'univers :

  • Univers à une seule zone : 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 : affiche 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 obtenir des visualisations de données multizones 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 dans le panneau "Journaux" à l'aide d'expressions LogQL (Log Query Language). Vous pouvez effectuer cette étape de l'une des deux 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 plage de dates 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électionnez une période pour vos journaux

    Pour interroger les journaux dans une plage de temps, procédez comme suit :

    1. Cliquez sur le menu 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 plages de dates absolues personnalisées en choisissant des dates et heures spécifiques dans le calendrier, puis en cliquant sur Appliquer la période.

    3. Vous pouvez également cliquer sur Modifier les paramètres temporels pour modifier les paramètres Fuseau horaire et Année fiscale à partir des commandes de plage de dates.

    Les paramètres temporels sont enregistrés pour chaque 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é core/organization_console_url de gdcloud :

        gdcloud config set core/organization_console_url https://GDC_URL

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

      3. Se connecter 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 à l'aide de la commande gdcloud auth print-identity-token. Pour en savoir plus, consultez gdcloud auth print-identity-token.

    2. Pour lister 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 lister des valeurs d'étiquette 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 :

      • LOG_QUERY_API_ENDPOINT : point de terminaison de l'API Log Query à partir duquel vous souhaitez interroger les journaux.
      • PROJECT_NAMESPACE : espace de noms de votre projet.
      • LABEL : libellé spécifique dont vous souhaitez interroger la valeur.

    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 :

      • LOG_QUERY_API_ENDPOINT : point de terminaison de l'API Log Query à partir duquel vous souhaitez interroger les journaux.
      • PROJECT_NAMESPACE : espace de noms de votre projet.
      • LABEL : libellé spécifique pour lequel vous souhaitez interroger les journaux.
      • LABEL_VALUE : valeur du libellé pour lequel vous souhaitez interroger les journaux.

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

    gRPC

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

    Pour interroger des journaux à l'aide de gRPC, vous devez remplir les conditions préalables suivantes :

    • Créez votre propre bibliothèque cliente à partir des tampons de protocole fournis par Google.
    • Implémentez l'authentification dans le client.
    • Implémentez des 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 comment utiliser des libellés et des 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"}