Dans Cloud Logging, les journaux structurés font référence aux entrées de journal qui utilisent le champ jsonPayload pour ajouter une structure à leurs charges utiles. Si vous utilisez l'API Cloud Logging ou l'outil de ligne de commande gcloud, vous pouvez contrôler la structure de vos charges utiles. Si vous utilisez l'agent Cloud Logging pour obtenir vos entrées de journal, vous pouvez indiquer à l'agent Logging de convertir vos charges utiles au format JSON.
Si vous utilisez le service BindPlane pour ingérer les journaux, vos charges utiles sont au format JSON et structurées en fonction du système source. Pour plus d'informations sur la recherche et l'affichage des journaux ingérés via BindPlane, consultez la documentation BindPlane sur la recherche de données de journaux.
Pour plus d'informations sur les différents formats de charge utile, reportez-vous à la section 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
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.
En configurant une source de journal avec le format [PARSER_NAME], vous pouvez exploiter les 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 Cloud 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 testCharge utile structurée (sortie) :
jsonPayload: { "pri": "6", "host": "192.168.0.1", "ident": "fluentd", "pid": "11111", "message": "[error] Syslog test" }
Pour plus d'informations sur le fonctionnement de l'analyseur syslog, consultez la documentation détaillée de Fluentd.
Analyseurs standards activés par défaut
Le tableau suivant présente les analyseurs standards inclus dans l'agent si vous activez 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 Logging lors de son installation (ou de sa réinstallation). L'activation de la journalisation structurée remplace 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 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 Cloud 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 obtenir des instructions sur l'installation de l'agent Logging et l'activation de la journalisation structurée, consultez la page Installer l'agent Logging.
Les fichiers de configuration de l'agent Logging se trouvent dans /etc/google-fluentd/config.d/. Ils doivent désormais inclure les analyseurs standards activés par défaut.
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"
},
...
}
La configuration du champ httpRequest, comme illustré dans l'exemple précédent, facilite le traçage : Google Cloud Console présente tous les journaux d'une requête HTTP donnée dans une hiérarchie parent-enfant.
Pour configurer cette extraction, ajoutez les éléments suivants à la fin de /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"
},
...
}
La configuration du champ httpRequest, comme illustré dans l'exemple précédent, facilite le traçage : Google Cloud Console présente tous les journaux d'une requête HTTP donnée dans une hiérarchie parent-enfant.
Pour configurer cette extraction, ajoutez les éléments suivants à la fin de /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 pouvez é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 $500Configuration 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 journal à l'aide de la visionneuse de journaux de Cloud Console, consultez la section Afficher les journaux.
Pour lire des entrées de journaux à l'aide de l'outil de ligne de commande gcloud ou de l'API, consultez la page Lire les 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.