Journalisation structurée

Dans Stackdriver Logging, les journaux structurés font référence aux entrées de journal qui utilisent le champ jsonPayload pour ajouter une structure à leur charge utile. Vous pouvez contrôler la structure des charges utiles à l'aide de l'API Stackdriver Logging ou de l'utilitaire de ligne de commande gcloud logging. Si vous utilisez l'agent Stackdriver Logging pour obtenir vos entrées de journal, vous pouvez spécifier que l'agent Logging convertisse vos charges utiles au format JSON. Pour en savoir plus sur les différents formats de charges utiles, consultez la page LogEntry.

Voici un exemple d'entrée de journal avec la charge utile structurée indiquée en gras :


        {
         insertId:  "1m9mtk4g3mwilhp"
         "jsonPayload: {
          code:  "structured-log-code"
          message:  "This is a log from the log file at test-structured-log.log"
         }
         labels: {
          compute.googleapis.com/resource_name:  "add-structured-log-resource"
         }
         logName:  "projects/my-sample-project-12345/logs/structured-log"
         receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
         resource: {
          labels: {
           instance_id:  "5351724540900470204"
           project_id:  "my-sample-project-12345"
           zone:  "us-central1-c"
          }
          type:  "gce_instance"
         }
         timestamp:  "2018-03-21T01:53:39.071920609Z"
        }

Opérations de journalisation structurée

L'agent Logging google-fluentd est une version modifiée du collecteur de données de journal Fluentd. L'agent Logging est fourni avec la configuration Fluentd par défaut et utilise les plug-ins d'entrée Fluentd pour extraire les journaux des événements à partir de sources externes telles que les fichiers sur disque ou pour analyser les enregistrements de journaux entrants.

Fluentd dispose d'une liste d'analyseurs disponibles qui extraient les journaux et les convertissent en charges utiles (JSON) structurées.

Configurez une source de journal au format [PARSER_NAME] pour pouvoir tirer parti des analyseurs intégrés fournis par Fluentd.

Les exemples de code suivants montrent la configuration Fluentd, l'enregistrement du journal d'entrée et la charge utile structurée de sortie, qui fait partie d'une entrée de journal Stackdriver Logging :

Configuration Fluentd :

  <source>
    @type tail

    format syslog # <--- This uses a predefined log format regex named
                  # `syslog`. See details at https://docs.fluentd.org/parser/syslog.

    path /var/log/syslog
    pos_file /var/lib/google-fluentd/pos/syslog.pos
    read_from_head true
    tag syslog
  </source>

Enregistrement du journal (entrée) :

  <6>Feb 28 12:00:00 192.168.0.1 fluentd[11111]: [error] Syslog test

Charge utile structurée :

    jsonPayload: {
        "pri": "6",
        "host": "192.168.0.1",
        "ident": "fluentd",
        "pid": "11111",
        "message": "[error] Syslog test"
    }

Pour en savoir plus sur le fonctionnement de l'analyseur syslog, consultez la documentation détaillée de Fluentd.

Analyseurs standards activés par défaut

Le tableau ci-dessous présente les analyseurs standards qui sont inclus dans l'agent avec l'activation de la journalisation structurée :

Nom de l'analyseur	Fichier de configuration
`syslog`	`/etc/google-fluentd/config.d/syslog.conf`
`nginx`	`/etc/google-fluentd/config.d/nginx.conf`
`apache2`	`/etc/google-fluentd/config.d/apache.conf`
`apache_error`	`/etc/google-fluentd/config.d/apache.conf`

Reportez-vous à la section Installation ci-dessous pour connaître la procédure d'activation de la journalisation structurée lors de l'installation de l'agent Logging.

Installation

Pour activer la journalisation structurée, vous devez modifier la configuration par défaut de l'agent Stackdriver Logging lors de son installation (ou de sa réinstallation). L'activation de la journalisation structurée vous permet d'obtenir la dernière version de l'agent et de remplacer les fichiers de configuration précédemment répertoriés. Le fonctionnement de l'agent lui-même ne change pas.

Lorsque vous activez la journalisation structurée, les journaux répertoriés sont convertis pour consigner en entrées de journal sous des formats différents de ceux utilisés avant l'activation des journaux structurés. Si les journaux sont exportés hors de Stackdriver Logging, ce changement peut affecter les applications de post-traitement. Dans le cas des exportations BigQuery, BigQuery refusera les nouvelles entrées de journal pour le reste de la journée en raison de leur schéma incorrect

Pour installer l'agent en activant la journalisation structurée, procédez comme suit :

Ouvrez une connexion de terminal à votre instance de VM à l'aide de SSH ou d'un outil similaire.
Téléchargez le script d'installation de l'agent Logging en exécutant la commande suivante sur votre instance de VM :
```
    curl -sSO "https://dl.google.com/cloudagents/install-logging-agent.sh"
```
Exécutez le script d'installation avec la commande suivante :
```
    sudo bash install-logging-agent.sh --structured
```
Pour vérifier que l'installation a réussi, recherchez l'entrée de test de l'agent dans la visionneuse de journaux.
Vous pouvez supprimer le script d'installation après son exécution.

Les fichiers de configuration de l'agent Stackdriver Logging se trouvent dans /etc/google-fluentd/config.d/. Ils doivent désormais inclure les analyseurs standards activés par défaut.

Pour en savoir plus, consultez la page Installer l'agent Stackdriver Logging.

Configurer le format du journal d'accès Apache

Par défaut, l'agent Logging stocke les données du journal d'accès Apache dans le champ jsonPayload. Exemple :

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "user"   : "some-user",
    "method" : "GET",
    "code"   : 200,
    "size"   : 777,
    "host"   : "192.168.0.1",
    "path"   : "/some-path",
    "referer": "some-referer",
    "agent"  : "Opera/12.0"
  },
  ...
}

Vous pouvez également configurer l'agent Logging pour extraire certains champs dans le champ httpRequest. Exemple :

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user"
  },
  ...
}

Comme indiqué ci-dessus, la configuration du champ httpRequest permet de tracer : la console GCP présente tous les journaux d'une requête HTTP donnée dans une hiérarchie parent-enfant.

Pour configurer cette extraction, ajoutez ce qui suit à la fin de votre fichier de configuration /etc/google-fluentd/config.d/apache.conf :

  <filter apache-access>
    @type record_transformer
    enable_ruby true
    <record>
      httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "serverIp" => record['host'],
      "referer" => record['referer']} }
    </record>
    remove_keys method, path, size, code, agent, host, referer
  </filter>

Pour plus d'informations sur la configuration de vos entrées de journal, consultez la section Modifier des enregistrements de journal.

Configurer le format du journal d'accès nginx

Par défaut, l'agent Logging stocke les données du journal d'accès nginx dans le champ jsonPayload. Exemple :

  {
    "logName": ...,
    "resource": ...,
    "httpRequest": ...,
    "jsonPayload": {
      "remote":"127.0.0.1",
      "host":"192.168.0.1",
      "user":"some-user",
      "method":"GET",
      "path":"/some-path",
      "code":"200",
      "size":"777",
      "referrer":"some-referrer",
      "agent":"Opera/12.0",
      "http_x_forwarded_for":"192.168.3.3"
    },
    ...
  }

Vous pouvez également configurer l'agent Logging pour extraire certains champs dans le champ httpRequest. Exemple :

  {
    "logName": ...,
    "resource": ...,
    "httpRequest": {
      "requestMethod": "GET",
      "requestUrl": "/some-path",
      "requestSize": "777",
      "status": "200",
      "userAgent": "Opera/12.0",
      "remoteIp": "127.0.0.1",
      "serverIp": "192.168.0.1",
      "referrer":"some-referrer",
    },
    "jsonPayload": {
      "user":"some-user",
      "http_x_forwarded_for":"192.168.3.3"
    },
    ...
  }

Comme indiqué ci-dessus, la configuration du champ httpRequest permet de tracer : la console GCP présente tous les journaux d'une requête HTTP donnée dans une hiérarchie parent-enfant.

Pour configurer cette extraction, ajoutez ce qui suit à la fin de votre fichier de configuration /etc/google-fluentd/config.d/nginx.conf :

<filter nginx-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "remoteIp" => record['remote'], "serverIp" => record['host'], "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, remote, host, referer
</filter>

Pour plus d'informations sur la configuration de vos entrées de journal, consultez la section Modifier des enregistrements de journal.

Écrire votre propre analyseur

Si vos journaux ne sont pas compatibles avec les analyseurs standards, vous avez la possibilité d'écrire les vôtres. Les analyseurs consistent en une expression régulière permettant de faire correspondre les enregistrements du journal et d'appliquer des libellés aux éléments.

Les 3 exemples de code suivants affichent une ligne de journal dans l'enregistrement de journal, une configuration avec une expression régulière indiquant le format de la ligne de journal et l'entrée de journal ingérée :

Ligne de journal dans l'enregistrement du journal :
```
REPAIR CAR $500
```

Configuration avec une expression régulière qui indique le format de la ligne de journal :

$ sudo vim /etc/google-fluentd/config.d/test-structured-log.conf
$ cat /etc/google-fluentd/config.d/test-structured-log.conf
<source>
  @type tail

  # Format indicates the log should be translated from text to
  # structured (JSON) with three fields, "action", "thing" and "cost",
  # using the following regex:
  format /(?<action>\w+) (?<thing>\w+) \$(?<cost>\d+)/
  # The path of the log file.
  path /tmp/test-structured-log.log
  # The path of the position file that records where in the log file
  # we have processed already. This is useful when the agent
  # restarts.
  pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
  read_from_head true
  # The log tag for this log input.
  tag structured-log
</source>

Entrée de journal correspondante :

 {
  insertId:  "eps2n7g1hq99qp"
  jsonPayload: {
    action:  "REPAIR"
    thing:  "CAR"
    cost:  "500"
  }
  labels: {
    compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/structured-log"
  receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
  resource: {
    labels: {
      instance_id:  "3914079432219560274"
      project_id:  "my-sample-project-12345"
      zone:  "us-central1-c"
    }
    type:  "gce_instance"
  }
  timestamp:  "2018-03-21T01:47:05.051902169Z"
 }

Afficher les journaux structurés

Pour rechercher des journaux et afficher les entrées de journaux dans la visionneuse de journaux, consultez la page Afficher les journaux.

Pour lire les entrées de journaux à l'aide du SDK ou de l'API, consultez la section relative à la lecture des entrées de journaux.

Dépannage

Pour résoudre les problèmes courants rencontrés lors de l'installation de l'agent Stackdriver Logging ou de l'interaction avec ce dernier, consultez la page relative au dépannage de l'agent.

Cette page vous a-t-elle été utile ? Évaluez-la :

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Dernière mise à jour : juin 10, 2019