Configurer l'agent Logging

Cette page fournit des détails sur les configurations par défaut et personnalisées de l'agent Cloud Logging.

La plupart des utilisateurs n'ont pas besoin de lire cette page. Lisez-la si :

vous souhaitez obtenir des détails techniques approfondis sur la configuration de l'agent Cloud Logging ;
vous souhaitez modifier la configuration de l'agent Cloud Logging.

Configuration par défaut

L'agent Logging google-fluentd est une version modifiée du collecteur de données de journal fluentd. L'agent Logging est fourni avec une configuration par défaut. Dans la plupart des cas, aucune configuration supplémentaire n'est requise.

Dans sa configuration par défaut, l'agent Logging transmet à Cloud Logging les journaux figurant dans la liste des journaux par défaut. Vous pouvez configurer l'agent pour qu'il diffuse des journaux supplémentaires. Pour en savoir plus, consultez la section Personnaliser la configuration de l'agent Logging sur cette page.

Fonctionnement de l'agent Logging

L'agent Logging utilise des plug-ins d'entrée fluentd pour récupérer et extraire des journaux d'événements à partir de sources externes, telles que des fichiers sur disque, ou pour analyser les enregistrements de journaux entrants. Les plug-ins d'entrée sont fournis avec l'agent ou peuvent être installés séparément en tant que gems Ruby. Consultez la liste des plug-ins fournis avec l'agent.

L'agent lit les enregistrements de journal stockés dans les fichiers journaux à l'aide de l'instance de VM via le plug-in intégré in_tail de fluentd. Chaque enregistrement de journal est converti en une structure d'entrée de journal pour Cloud Logging. Le contenu de chaque enregistrement de journal représente la majeure partie de la charge utile des entrées de journal, mais celles-ci contiennent également des éléments standards tels que l’horodatage et le niveau de gravité. L'agent Logging requiert que chaque enregistrement de journal soit tagué avec un tag au format de chaîne. Toutes les requêtes et tous les plug-ins de sortie correspondent à un ensemble de tags spécifique. Le nom du journal suit généralement le format projects/[PROJECT-ID]/logs/[TAG]. Par exemple, le nom de journal suivant inclut le tag structured-log :

projects/my-sample-project-12345/logs/structured-log

Le plug-in de sortie transforme chaque message structuré internalisé en une entrée de journal dans Cloud Logging. La charge utile devient la charge utile de type texte ou JSON.

Les sections suivantes de cette page présentent en détail la configuration par défaut.

Définitions de configuration par défaut

Les sections suivantes décrivent les définitions de configuration par défaut pour syslog, le plug-in d'entrée de transfert, les configurations d'entrée pour les journaux d'applications tierces, comme ceux figurant dans la liste des journaux par défaut et notre plug-in de sortie Google Cloud fluentd.

Emplacement du fichier de configuration racine

Linux : /etc/google-fluentd/google-fluentd.conf

Ce fichier de configuration racine importe également tous les fichiers de configuration du dossier /etc/google-fluentd/config.d.
Windows : C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

Si vous exécutez une version de l'agent Logging antérieure à la version v1-5, l'emplacement est le suivant : C:\GoogleStackdriverLoggingAgent\fluent.conf

Configuration de Syslog

Emplacements des fichiers de configuration : /etc/google-fluentd/config.d/syslog.conf
Description : ce fichier inclut la configuration nécessaire pour spécifier syslog en tant qu'entrée de journal.
Consultez le dépôt de configuration.

Nom de la configuration	Type	Par défaut	Description
`format`	chaîne	`/^(?<message>(?<time>[^ ]\s[^ ]* [^ ]) .)$/`	Format du fichier syslog.
`path`	chaîne	`/var/log/syslog`	Chemin du fichier syslog.
`pos_file`	chaîne	`/var/lib/google-fluentd/pos/syslog.pos`	Chemin du fichier de position pour cette entrée de journal. `fluentd` enregistre la dernière position lue dans ce fichier. Consultez la documentation détaillée de `fluentd`.
`read_from_head`	Bool	`true`	Indique s'il faut commencer à lire les journaux à partir du haut du fichier plutôt qu'à partir du bas. Consultez la documentation détaillée de `fluentd`.
`tag`	chaîne	`syslog`	Tag de journal pour cette entrée de journal.

Configuration du plug-in d'entrée `in_forward`

Emplacements des fichiers de configuration : /etc/google-fluentd/config.d/forward.conf
Description : ce fichier inclut la configuration nécessaire au plug-in d'entrée in_forward de fluentd. Le plug-in d'entrée in_forward vous permet de transmettre des journaux via un socket TCP.
Consultez la documentation détaillée de fluentd pour en savoir plus sur ce plug-in et le dépôt de configuration.

Nom de la configuration	Type	Par défaut	Description
`port`	Ent	`24224`	Port à surveiller
`bind`	chaîne	`127.0.0.1`	Adresse de liaison à surveiller. Par défaut, seules les connexions de localhost sont acceptées. Pour ouvrir cette adresse, cette configuration doit être définie sur `0.0.0.0`.

Configuration des entrées de journal des applications tierces

Emplacements des fichiers de configuration : /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
Description : ce répertoire inclut des fichiers de configuration permettant de spécifier les fichiers journaux des applications tierces en tant qu'entrées de journal. Chaque fichier, à l'exception de syslog.conf et forward.conf, représente une application (par exemple, apache.conf pour l'application Apache).
Consultez le dépôt de configuration.

Nom de la configuration	Type	Par défaut	Description
`format`¹	chaîne	Varie selon l'application	Format du journal. Consultez la documentation détaillée de `fluentd`.
`path`	chaîne	Varie selon l'application	Chemin du ou des fichiers journaux. Plusieurs chemins peuvent être spécifiés, séparés par une virgule. L'astérisque (*) et le format "strftime" peuvent être inclus pour ajouter/supprimer le fichier de manière dynamique. Consultez la documentation détaillée de `fluentd`.
`pos_file`	chaîne	Varie selon l'application	Chemin du fichier de position pour cette entrée de journal. `fluentd` enregistre la dernière position lue dans ce fichier. Consultez la documentation détaillée de `fluentd`.
`read_from_head`	Bool	`true`	Indique s'il faut commencer à lire les journaux à partir du haut du fichier plutôt qu'à partir du bas. Consultez la documentation détaillée de `fluentd`.
`tag`	chaîne	Varie selon le nom de l'application.	Tag de journal pour cette entrée de journal.

¹ Si vous utilisez le stanza <parse>, spécifiez le format du journal à l'aide de @type.

Configuration du plug-in de sortie Google Cloud `fluentd`

Emplacements des fichiers de configuration :
- Linux : /etc/google-fluentd/google-fluentd.conf
- Windows : C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf
  
  Si vous exécutez une version de l'agent Logging antérieure à la version v1-5, l'emplacement est le suivant : C:\GoogleStackdriverLoggingAgent\fluent.conf
Description : ce fichier inclut des options de configuration permettant de contrôler le comportement du plug-in de sortie Google Cloud fluentd.
Accédez au dépôt de configuration.

Nom de la configuration	Type	Par défaut	Description
`buffer_chunk_limit`	chaîne	`512KB`	Au fur et à mesure de l'arrivée des enregistrements de journal, ceux qui ne peuvent pas être écrits assez rapidement sur les composants en aval sont envoyés dans une file d'attente de fragments. Cette configuration définit une taille limite pour chaque fragment. Par défaut, nous définissons la taille limite des fragments avec prudence pour éviter de dépasser la taille de fragment recommandée de 5 Mo par requête d'écriture dans l'API Logging. Les entrées de journal figurant dans la requête API peuvent être cinq à huit fois plus volumineuses que l'entrée de journal d'origine, en raison de toutes les métadonnées supplémentaires associées. Un fragment de mémoire tampon est vidé si l'une des deux conditions est remplie : 1. `flush_interval` est impliqué. 2. La taille de la mémoire tampon atteint la limite définie dans la configuration `buffer_chunk_limit`.
`flush_interval`	chaîne	`5s`	Au fur et à mesure de l'arrivée des enregistrements de journal, ceux qui ne peuvent pas être écrits assez rapidement sur les composants en aval sont envoyés dans une file d'attente de fragments. La configuration définit le délai avant de pouvoir vider un fragment de mémoire tampon. Un fragment de mémoire tampon est vidé si l'une des deux conditions est remplie : 1. `flush_interval` est impliqué. 2. La taille de la mémoire tampon atteint la limite définie dans la configuration `buffer_chunk_limit`.
`disable_retry_limit`	Bool	`false`	Applique une limite au nombre de tentatives de vidage des fragments de mémoire tampon en cas d'échec. Consultez les spécifications détaillées dans `retry_limit`, `retry_wait` et `max_retry_wait`.
`retry_limit`	Ent	`3`	Lorsqu'un fragment de mémoire tampon ne peut pas être vidé, `fluentd` réessaie plus tard, par défaut. Cette configuration définit le nombre de tentatives à effectuer avant de supprimer un fragment de mémoire tampon problématique.
`retry_wait`	Ent	`10s`	Lorsqu'un fragment de mémoire tampon ne peut pas être vidé, `fluentd` réessaie plus tard, par défaut. Cette configuration définit l'intervalle d'attente en secondes avant de réessayer une première fois. L'intervalle d'attente est doublé à chaque nouvelle tentative (20 s, 40 s,…), jusqu'à atteindre `retry_ limit` ou `max_retry_wait`.
`max_retry_wait`	Ent	`300`	Lorsqu'un fragment de mémoire tampon ne peut pas être vidé, `fluentd` réessaie plus tard, par défaut. L'intervalle d'attente double à chaque nouvelle tentative (20 s, 40 s,...). Cette configuration définit la durée maximale d'un intervalle d'attente en secondes. Si l'intervalle d'attente atteint cette limite, le doublement s'arrête.
`num_threads`	Ent	`8`	Nombre de vidages de journaux pouvant être traités simultanément par le plug-in de sortie.
`use_grpc`	Bool	`true`	Indique si gRPC doit être utilisé à la place de REST/JSON pour communiquer avec l'API Logging. Avec gRPC activé, l'utilisation du processeur est généralement moindre.
`grpc_compression_algorithm`	enum	`none`	Si vous utilisez gRPC, définit le schéma de compression à utiliser. Il peut s'agir de `none` ou `gzip`.
`partial_success`	Bool	`true`	Indique la compatibilité avec l'ingestion partielle des journaux. Si ce paramètre est défini sur `true`, les entrées de journal non valides d'un ensemble complet sont supprimées et les entrées de journal valides sont correctement ingérées dans l'API Logging. S'il est défini sur `false`, l'ensemble complet est supprimé s'il contient des entrées de journal non valides.
`enable_monitoring`	Bool	`true`	Si ce paramètre est défini sur `true`, l'agent Logging exporte la télémétrie interne. Pour en savoir plus, consultez la section Télémétrie du plug-in de sortie.
`monitoring_type`	chaîne	`opencensus`	Type de surveillance. Les options acceptées sont `opencensus` et `prometheus`. Pour en savoir plus, consultez la section Télémétrie du plug-in de sortie.
`autoformat_stackdriver_trace`	Bool	`true`	Si ce paramètre est défini sur `true`, la trace est reformatée lorsque la valeur du champ de charge utile structurée `logging.googleapis.com/trace` correspond au format `traceId` de ResourceTrace. Les détails concernant le formatage automatique sont disponibles sur cette page à la section Champs spéciaux dans les charges utiles structurées.

Configuration de la surveillance

Télémétrie du plug-in de sortie

L'option enable_monitoring détermine si le plug-in de sortie Google Cloud fluentd collecte sa télémétrie interne. Lorsque ce paramètre est défini sur true, l'agent Logging enregistre le nombre d'entrées de journal à envoyer à Cloud Logging et le nombre réel d'entrées de journal ingérées avec succès par Cloud Logging. Lorsque la valeur est false, aucune métrique n'est collectée par le plug-in de sortie.

L'option monitoring_type contrôle la manière dont cette télémétrie est exposée par l'agent. Pour obtenir la liste des métriques, consultez la section suivante.

Lorsqu'il est défini sur prometheus, l'agent Logging expose les métriques au format Prometheus sur le point de terminaison Prometheus (localhost:24231/metrics par défaut). Consultez la page Prometheus et configuration du plug-in prometheus_monitor pour en savoir plus sur la personnalisation de cette méthode. Sur les VM Compute Engine, pour que ces métriques soient écrites dans l'API Monitoring, l'agent de surveillance doit également être installé et exécuté.

Lorsque ce paramètre est défini sur opencensus (valeur par défaut depuis la version v1.6.25), l'agent Logging écrit directement ses propres métriques d'état dans l'API Monitoring. Cette opération nécessite que le rôle roles/monitoring.metricWriter soit attribué au compte de service Compute Engine par défaut, même si l'agent Monitoring n'est pas installé.

Les métriques suivantes sont écrites dans l'API Monitoring par l'agent Monitoring et par l'agent Logging en mode opencensus :

agent.googleapis.com/agent/uptime avec un libellé version : temps d'activité de l'agent Logging.
agent.googleapis.com/agent/log_entry_count avec une libellé response_code : nombre d'entrées de journal écrites par l'agent Logging.
agent.googleapis.com/agent/log_entry_retry_count avec une libellé response_code : nombre d'entrées de journal écrites par l'agent Logging.
agent.googleapis.com/agent/request_count avec un libellé response_code : nombre de requêtes API de l'agent Logging.

Ces métriques sont décrites plus en détail sur la page Métriques d'agent.

De plus, les métriques Prometheus suivantes sont exposées par le plug-in de sortie en mode prometheus :

uptime avec un libellé version : temps d'activité de l'agent Logging.
stackdriver_successful_requests_count avec les libellés grpc et code : nombre de requêtes réussies adressées à l'API Logging.
stackdriver_failed_requests_count avec les libellés grpc et code : nombre de requêtes infructueuses pour l'API Logging, réparties par code d'erreur.
stackdriver_ingested_entries_count avec les libellés grpc et code : nombre d'entrées de journal ingérées par l'API Logging.
stackdriver_dropped_entries_count avec les libellés grpc et code : nombre d'entrées de journal rejetées par l'API Logging.
stackdriver_retried_entries_count avec les libellés grpc et code : nombre d'entrées de journal qui n'ont pas pu être ingérées par le plug-in de sortie Google Cloud fluentd en raison d'une erreur temporaire et ont fait l'objet d'une nouvelle tentative.

Prometheus et configuration du plug-in prometheus_monitor

Emplacements des fichiers de configuration : /etc/google-fluentd/google-fluentd.conf
Description : ce fichier inclut des options de configuration permettant de contrôler le comportement des plug-ins prometheus et prometheus_monitor. Le plug-in prometheus_monitor surveille l'infrastructure principale de Fluentd. Le plug-in prometheus expose les métriques, y compris celles du plug-in prometheus_monitor et celles du plug-in google_cloud ci-dessus via un port local au format Prometheus. Pour en savoir plus, consultez la page https://docs.fluentd.org/deployment/monitoring-prometheus.
Accédez au dépôt de configuration.

Pour la surveillance de Fluentd, le serveur de métriques HTTP Prometheus intégré est activé par défaut. Vous pouvez supprimer la section suivante de la configuration pour éviter le démarrage de ce point de terminaison :

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

Traiter les charges utiles

La plupart des journaux compatibles avec la configuration par défaut de l'agent Logging proviennent de fichiers journaux et sont ingérés en tant que charges utiles non structurées (texte) dans les entrées de journal.

La seule exception est que le plug-in d'entrée in_forward, qui est également activé par défaut, accepte uniquement les journaux structurés et les ingère en tant que charges utiles structurées (JSON) dans les entrées de journal. Pour plus d'informations, consultez la section Diffuser des enregistrements de journal structurés (JSON) via le plug-in in_forward sur cette page.

Lorsque la ligne de journal est un objet JSON sérialisé et que l'option detect_json est activée, le plug-in de sortie transforme l'entrée de journal en charge utile structurée (JSON). Cette option est activée par défaut dans les instances de VM s'exécutant dans un environnement flexible App Engine ou Google Kubernetes Engine. Cette option n'est pas activée par défaut dans les instances de VM s'exécutant dans l'environnement standard App Engine. Les objets JSON analysés avec l'option detect_json sont toujours ingérés en tant que jsonPayload.

Vous pouvez personnaliser la configuration des agents pour qu'ils soient compatibles avec l'ingestion de journaux structurés à partir de ressources supplémentaires. Pour en savoir plus, consultez la section Diffuser des enregistrements de journal structurés (JSON) dans Cloud Logging.

La charge utile des enregistrements de journal diffusés par un agent Logging personnalisé peut être un message texte non structuré unique (textPayload) ou un message JSON structuré (jsonPayload).

Champs spéciaux dans les charges utiles structurées

Lorsque l'agent Logging reçoit un enregistrement de journal structuré, il déplace les clés correspondant à la table suivante dans le champ correspondant de l'objet LogEntry. Dans le cas contraire, la clé fait partie du champ LogEntry.jsonPayload. Ce comportement vous permet de définir des champs spécifiques dans l'objet LogEntry, qui est écrit dans l'API Logging. Par exemple, si l'enregistrement de journal structuré contient une clé de severity, l'agent Logging renseigne le champ LogEntry.severity.

Champ de journal JSON	`LogEntry` champ	Fonction de l'agent Cloud Logging	Exemple de valeur
`severity`	`severity`	L'agent Logging tente de faire correspondre différentes chaînes de gravité courantes, qui incluent la liste des chaînes LogSeverity reconnues par l'API Logging.	`"severity":"ERROR"`
`message`	`textPayload` (ou partie de `jsonPayload`)	Message qui s'affiche sur la ligne d'entrée de journal dans l'explorateur de journaux.	`"message":"There was an error in the application."` Remarque : Le champ `message` est enregistré en tant que `textPayload` s'il s'agit du seul champ restant après le déplacement des autres champs spécifiques par l'agent Logging et si `detect_json` était désactivé. Sinon, `message` reste dans `jsonPayload`. `detect_json` ne s'applique pas aux environnements de journalisation gérés tels que Google Kubernetes Engine. Si votre entrée de journal contient une trace de la pile d'exception, celle-ci doit être définie dans le champ de journal JSON `message`, de sorte qu'elle puisse être analysée et enregistrée dans Error Reporting.
`log` (ancienne version de Google Kubernetes Engine uniquement)	`textPayload`	Ne s'applique qu'à l'ancienne version de Google Kubernetes Engine : si après déplacement des champs spéciaux, il ne reste plus qu'un champ `log`, ce champ est enregistré en tant que `textPayload`.
`httpRequest`	`httpRequest`	Un enregistrement structuré au format du champ `HttpRequest` de `LogEntry`.	`"httpRequest":{"requestMethod":"GET"}`
champs liés au temps	`timestamp`	Pour en savoir plus, consultez la section Champs liés au temps.	`"time":"2020-10-12T07:20:50.52Z"`
`logging.googleapis.com/insertId`	`insertId`	Pour en savoir plus, consultez la section `insertId` de la page `LogEntry`.	`"logging.googleapis.com/insertId":"42"`
`logging.googleapis.com/labels`	`labels`	La valeur de ce champ doit être un enregistrement structuré. Pour en savoir plus, consultez la section `labels` de la page `LogEntry`.	`"logging.googleapis.com/labels":` `{"user_label_1":"value_1","user_label_2":"value_2"}`
`logging.googleapis.com/operation`	`operation`	La valeur de ce champ est également utilisée par l'explorateur de journaux pour regrouper les entrées de journal associées. Pour en savoir plus, consultez la section `operation` de la page `LogEntry`.	`"logging.googleapis.com/operation":` `{"id":"get_data","producer":"github.com/MyProject/MyApplication",` `"first":"true"}`
`logging.googleapis.com/sourceLocation`	`sourceLocation`	Les informations d'emplacement du code source associées à l'entrée de journal, le cas échéant. Pour en savoir plus, consultez la section `LogEntrySourceLocation` de la page `LogEntry`.	`"logging.googleapis.com/sourceLocation":` `{"file":"get_data.py","line":"142","function":"getData"}`
`logging.googleapis.com/spanId`	`spanId`	ID de délai dans la trace associée à l'entrée de journal. Pour en savoir plus, consultez la section `spanId` de la page `LogEntry`.	`"logging.googleapis.com/spanId":"000000000000004a"`
`logging.googleapis.com/trace`	`trace`	Nom de ressource de la trace associée à l'entrée de journal, le cas échéant. Pour en savoir plus, consultez la section `trace` de la page `LogEntry`.	`"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"` Remarque : Si vous n'écrivez pas dans `stdout` ou `stderr`, la valeur de ce champ doit être au format `projects/[PROJECT-ID]/traces/[TRACE-ID]`. Cela permet à l'explorateur de journaux et au lecteur de traces de regrouper les entrées de journal et de les afficher en parallèle avec les traces. Si le paramètre `autoformat_stackdriver_trace` est défini sur "true" et que `[V]` correspond au format `traceId` de ResourceTrace, le champ `trace` de LogEntry possède la valeur `projects/[PROJECT-ID]/traces/[V]`.
`logging.googleapis.com/trace_sampled`	`traceSampled`	La valeur de ce champ doit être `true` ou `false`. Pour en savoir plus, consultez la section `traceSampled` de la page `LogEntry`.	`"logging.googleapis.com/trace_sampled": false`

Champs liés au temps

En général, les informations temporelles concernant une entrée de journal sont stockées dans le champ timestamp de l'objet LogEntry:

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

Lorsque la source d'une entrée de journal est une donnée structurée, l'agent Logging utilise les règles suivantes pour rechercher des informations temporelles dans les champs de l'entrée jsonPayload :

Recherchez un champ timestamp qui est un objet JSON incluant les champs seconds et nanos, qui représentent respectivement un nombre de secondes signé de l'époque UTC et un nombre non négatif de secondes fractionnaires :
```
jsonPayload: {
  ...
  "timestamp": {
    "seconds": CURRENT_SECONDS,
    "nanos": CURRENT_NANOS
  }
}
```
Si la recherche précédente échoue, recherchez une paire de champs timestampSeconds et timestampNanos :
```
jsonPayload: {
  ...
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS
}
```
Si la recherche précédente échoue, recherchez un champ time qui est une chaîne au format RFC 3339 :
```
jsonPayload: {
  ...
  "time": CURRENT_TIME_RFC3339
}
```

Lorsque des informations temporelles sont trouvées, l'agent Logging les utilise pour définir la valeur de LogEntry.timestamp et ne copie pas ces informations depuis l'enregistrement structuré dans l'objet LogEntry.jsonPayload.

Les champs d'informations temporelles qui ne sont pas utilisés pour définir la valeur du champ LogEntry.timestamp sont copiés à partir de l'enregistrement structuré dans l'objet LogEntry.jsonPayload. Par exemple, si l'enregistrement structuré contient un objet JSON timestamp et un champ time, les données de l'objet JSON timestamp sont utilisées pour définir LogEntry.timestamp. L'objet LogEntry.jsonPayload contient un champ time, car ce champ n'a pas été utilisé pour définir la valeur LogEntry.timestamp.

Personnaliser la configuration de l'agent

Outre la liste des journaux par défaut diffusés par l'agent Logging, vous pouvez personnaliser ce dernier pour qu'il envoie des journaux supplémentaires à Logging ou pour ajuster les paramètres de l'agent en ajoutant des configurations d'entrée.

Les définitions de configuration figurant dans ces sections ne s'appliquent qu'au plug-in de sortie fluent-plugin-google-cloud et spécifient la manière dont les journaux sont transformés et ingérés dans Cloud Logging.

Emplacement principal des fichiers de configuration :
- Linux : /etc/google-fluentd/google-fluentd.conf
- Windows : C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf
  
  Si vous exécutez une version de l'agent Logging antérieure à la version v1-5, l'emplacement est le suivant : C:\GoogleStackdriverLoggingAgent\fluent.conf
Description : ce fichier inclut des options de configuration permettant de contrôler le comportement du plug-in de sortie fluent-plugin-google-cloud.
Consultez le dépôt de configuration.

Diffuser des journaux à partir d'entrées supplémentaires

Vous pouvez personnaliser l'agent Logging pour envoyer des journaux supplémentaires à Logging en ajoutant des configurations d'entrée.

Diffuser des journaux non structurés (texte) via des fichiers journaux

Dans l'invite de commande Linux, créez un fichier journal :
```
touch /tmp/test-unstructured-log.log
```

Créez un fichier de configuration nommé test-unstructured-log.conf dans le répertoire de configuration supplémentaire /etc/google-fluentd/config.d :

sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
<source>
    @type tail
    <parse>
        # 'none' indicates the log is unstructured (text).
        @type none
    </parse>
    # The path of the log file.
    path /tmp/test-unstructured-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-unstructured-log.pos
    read_from_head true
    # The log tag for this log input.
    tag unstructured-log
</source>
EOF

Pour créer un fichier, vous pouvez également ajouter les informations de configuration à un fichier de configuration existant.

Redémarrez l'agent pour appliquer les modifications de la configuration :
```
sudo service google-fluentd restart
```

Générez un enregistrement de journal dans le fichier journal :

echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log

Consultez l'explorateur de journaux pour afficher l'entrée de journal ingérée :

{
  insertId:  "eps2n7g1hq99qp"
  labels: {
  compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/unstructured-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"
  }
  textPayload:  "This is a log from the log file at test-unstructured-log.log"
  timestamp:  "2018-03-21T01:47:05.051902169Z"
}

Diffuser des journaux structurés (JSON) via des fichiers journaux

Vous pouvez configurer l'agent Logging pour exiger que certaines entrées de journal soient structurées. Vous pouvez également personnaliser l'agent Logging pour qu'il ingère du contenu au format JSON à partir d'un fichier journal. Lorsque l'agent est configuré pour ingérer du contenu JSON, l'entrée doit être mise en forme de sorte que chaque objet JSON se trouve sur une nouvelle ligne :

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

Pour que l'agent Logging ingère du contenu au format JSON, procédez comme suit :

Dans l'invite de commande Linux, créez un fichier journal :
```
touch /tmp/test-structured-log.log
```

Créez un fichier de configuration nommé test-structured-log.conf dans le répertoire de configuration supplémentaire /etc/google-fluentd/config.d :

sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
<source>
    @type tail
    <parse>
        # 'json' indicates the log is structured (JSON).
        @type json
    </parse>
    # 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>
  EOF

Pour créer un fichier, vous pouvez également ajouter les informations de configuration à un fichier de configuration existant.

Redémarrez l'agent pour appliquer les modifications de la configuration :
```
sudo service google-fluentd restart
```

Générez un enregistrement de journal dans le fichier journal :

echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log

Consultez l'explorateur de journaux pour afficher l'entrée de journal ingérée :

{
  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"
}

Dans l'explorateur de journaux, filtrez le type de ressource et définissez logName sur structured-log.

Pour accéder à d'autres options permettant de personnaliser le format des entrées de journal pour les applications tierces courantes, consultez la section Formats de journaux courants et comment les analyser.

Diffuser des journaux structurés (JSON) via le plug-in `in_forward`

Vous pouvez également envoyer des journaux via le plug-in fluentd in_forward. fluentd-cat est un outil intégré qui permet d'envoyer facilement des journaux au plug-in in_forward. Consultez la documentation de fluentd pour en savoir plus sur cet outil.

Pour envoyer des journaux via le plug-in fluentd in_forward, suivez les instructions ci-dessous :

Exécutez la commande suivante sur la VM où l'agent Logging est installé :

echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin

Consultez l'explorateur de journaux pour afficher l'entrée de journal ingérée :

{
  insertId:  "1kvvmhsg1ib4689"
  jsonPayload: {
  code:  "send-log-via-fluent-cat"
  message:  "This is a log from in_forward plugin."
  }
  labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
  receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
  resource: {
  labels: {
    instance_id:  "5351724540900470204"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
  }
  timestamp:  "2018-03-21T02:11:22.717692494Z"
}

Diffuser des enregistrements de journal structurés (JSON) à partir du code de l'application

Vous pouvez activer des connecteurs dans différents langages pour envoyer des journaux structurés à partir du code de l'application. Pour plus d'informations, consultez la documentation de fluentd. Ces connecteurs sont basés sur le plug-in in_forward.

Définir des étiquettes d'entrée de journal

Les options de configuration ci-dessous vous permettent de remplacer les étiquettes de LogEntry et de MonitoredResource lors de l'ingestion de journaux dans Cloud Logging. Toutes les entrées de journal sont associées à des ressources surveillées. Pour plus d'informations, consultez la liste des types de ressources surveillées Cloud Logging.

Nom de la configuration	Type	Par défaut	Description
`label_map`	hash	nil	`label_map` (spécifié en tant qu'objet JSON) est un ensemble non ordonné de noms de champs `fluentd` dont les valeurs sont envoyées sous forme d'étiquettes plutôt que comme éléments de la charge utile structurée. Chaque entrée de la table de correspondances est une association {`field_name` : `label_name`}. Lorsque l'occurrence `field_name` (analysée par le plug-in d'entrée) se présente, une étiquette avec le `label_name` correspondant est ajoutée à l'entrée de journal. La valeur du champ est utilisée comme valeur du libellé. La table de correspondances vous offre une flexibilité supplémentaire dans la spécification des noms d'étiquettes, y compris la possibilité d'utiliser des caractères qui ne sont pas autorisés dans les noms de champs `fluentd`. Pour obtenir un exemple, consultez la section Définir des étiquettes dans des entrées de journal structurées.
`labels`	hash	nil	`labels` (spécifié en tant qu'objet JSON) est un ensemble d'étiquettes personnalisées fournies au moment de la configuration. Il vous permet d'injecter des informations environnementales supplémentaires dans chaque message ou de personnaliser automatiquement les étiquettes détectées d'une autre manière. Chaque entrée de la table de correspondances est une association {`label_name` : `label_value`}.

Le plug-in de sortie de l'agent Logging accepte trois méthodes pour définir les étiquettes de LogEntry :

Dynamiquement, en remplaçant des étiquettes spécifiques dans une entrée structurée par des étiquettes différentes. Pour plus d'informations, consultez la section Définir des étiquettes dans des entrées de journal structurées sur cette page.
Statiquement, en associant un libellé à toutes les occurrences d'une valeur. Pour en savoir plus, consultez la section Définition des étiquettes statistiquement sur cette page.

Définir des étiquettes dans des entrées de journal structurées

Supposons que vous ayez écrit une charge utile d'entrée de journal structurée comme ceci :

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

Et supposons que vous souhaitiez traduire le champ de charge utile env en une étiquette de métadonnées environment. Pour cela, ajoutez ce qui suit à la configuration de votre plug-in de sortie dans le fichier de configuration principal (/etc/google-fluentd/google-fluentd.conf sous Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf sous Windows) :

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

Le paramètre label_map remplace ici l'étiquette env par environment dans la charge utile, de sorte que l'entrée de journal résultante aura une étiquette environment avec la valeur production.

Définir des étiquettes statiquement

Si vous ne disposez pas de ces informations dans la charge utile et que vous souhaitez simplement ajouter une étiquette de métadonnées statique appelée environment, ajoutez ce qui suit à la configuration de votre plug-in de sortie dans le fichier de configuration principal (/etc/google-fluentd/google-fluentd.conf sous Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf sous Windows) :

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

Dans ce cas, au lieu d'utiliser une table de correspondances pour remplacer une étiquette par une autre, nous utilisons un paramètre labels pour associer une étiquette avec une valeur littérale donnée à une entrée de journal, que celle-ci comporte déjà une étiquette ou pas. Cette approche peut être utilisée même si vous envoyez des journaux non structurés.

Pour plus d'informations sur la configuration du paramètre labels, du paramètre label_map et des autres paramètres de l'agent Logging, consultez la section Définir des étiquettes d'entrée de journal sur cette page.

Modifier des enregistrements de journal

Fluentd fournit des plug-ins de filtrage intégrés pouvant être utilisés pour modifier les entrées de journal.

Le plug-in de filtrage le plus couramment utilisé est filter_record_transformer. Il vous permet :

d'ajouter de nouveaux champs aux entrées de journal ;
de mettre à jour les champs dans les entrées de journal ;
de supprimer des champs dans les entrées de journal.

Certains plug-ins de sortie permettent également de modifier les entrées de journal. Le plug-in de sortie fluent-plugin-record-reformer fournit des fonctionnalités similaires au plug-in de filtrage filter_record_transformer, et permet en plus de modifier les tags de journaux. Ce plug-in devrait conduire à une utilisation plus importante des ressources : à chaque fois qu'un tag de journal est mis à jour, une nouvelle entrée de journal est générée avec le nouveau tag. Notez que le champ tag est requis dans la configuration. Nous vous recommandons également de modifier ce champ pour éviter d'introduire une boucle morte.

Le plug-in de sortie fluent-plugin-detect-exceptions analyse un flux de journal (enregistrements de journal non structurés (texte) ou au format JSON) afin de rechercher des traces de la pile d'exception multilignes. Si une séquence consécutive d'entrées de journal forme une trace de la pile d'exceptions, les entrées de journal sont transférées sous la forme d'un seul message de journaux combinés. Sinon, l'entrée de journal est transférée telle quelle.

Définitions de configuration avancées (autres que par défaut)

Si vous souhaitez personnaliser la configuration de votre agent Logging au-delà de sa configuration par défaut, consultez les sections suivantes.

Options de configuration liées à la mémoire tampon

Les options de configuration suivantes vous permettent d'ajuster le mécanisme de mise en mémoire tampon interne de l'agent Logging.

Nom de la configuration	Type	Par défaut	Description
`buffer_type`	chaîne	`buf_memory`	Les enregistrements qui ne peuvent pas être écrits suffisamment rapidement dans l'API Logging seront placés dans une mémoire tampon. Le tampon peut se trouver en mémoire ou dans des fichiers réels. Valeur recommandée : `buf_file`. La valeur par défaut de `buf_memory` est rapide, mais pas persistante. Il existe un risque de perte de journaux. Si le paramètre `buffer_type` est défini sur `buf_file`, le paramètre `buffer_path` doit également être spécifié.
`buffer_path`	chaîne	Spécifié par l'utilisateur	Chemin où les fragments de mémoire tampon sont stockés. Ce paramètre est obligatoire si le paramètre `buffer_type` est défini sur `file`. Cette configuration doit être unique pour éviter une condition de concurrence.
`buffer_queue_limit`	Ent	`64`	Spécifie la longueur maximale de la file d'attente. Lorsque la file d'attente de tampon atteint ce nombre de fragments, le comportement de la mémoire tampon est contrôlé par le paramètre `buffer_queue_full_action`. Par défaut, des exceptions sont générées. Cette option associée à `buffer_chunk_limit` détermine l'espace disque maximal autorisé par `fluentd` pour la mise en mémoire tampon.
`buffer_queue_full_action`	chaîne	`exception`	Contrôle le comportement de la mémoire tampon lorsque la file d'attente est pleine. Valeurs possibles : 1. `exception` : renvoie `BufferQueueLimitError` lorsque la file d'attente est pleine. La manière dont `BufferQueueLimitError` est traité dépend des plug-ins d'entrée. Par exemple, le plug-in d'entrée `in_tail` arrête de lire de nouvelles lignes alors que le plug-in d'entrée `in_forward` renvoie une erreur. 2. `block` : ce mode arrête le thread du plug-in d'entrée jusqu'à ce que la mémoire tampon soit vidée. Cette action est utile pour les cas d'utilisation par lot. `fluentd` déconseille d'utiliser une action de blocage afin d'éviter l'erreur `BufferQueueLimitError`. Si `BufferQueueLimitError` est fréquemment renvoyé, cela signifie que votre capacité de destination est insuffisante pour votre trafic. 3. `drop_oldest_chunk` : ce mode supprime les fragments obsolètes.

Options de configuration liées aux projets et aux ressources surveillées

Les options de configuration suivantes vous permettent de spécifier manuellement un projet et certains champs à partir de l'objet MonitoredResource. Ces valeurs sont automatiquement collectées par l'agent Logging ; il est déconseillé de les spécifier manuellement.

Nom de la configuration	Type	Par défaut	Description
`project_id`	chaîne	nil	Si elle est spécifiée, cette valeur remplace la valeur de `project_id` en identifiant le projet Google Cloud ou AWS sous-jacent dans lequel l'agent Logging est exécuté.
`zone`	chaîne	nil	Si elle est spécifiée, cette valeur remplace la zone.
`vm_id`	chaîne	nil	Si elle est spécifiée, cette valeur remplace l'ID de la VM.
`vm_name`	chaîne	nil	Si elle est spécifiée, cette valeur remplace le nom de la VM.

Autres options de configuration du plug-in de sortie

Nom de la configuration	Type	Par défaut	Description
`detect_json`¹	Bool	`false`	Indique s'il faut essayer de détecter si l'enregistrement de journal est une entrée de journal de type texte avec un contenu JSON qui doit être analysé. Si ce paramètre est défini sur `true`, et qu'une entrée de journal non structurée (texte) est détectée comme étant au format JSON, elle est analysée et envoyée en tant que charge utile structurée (JSON).
`coerce_to_utf8`	Bool	`true`	Indique s'il faut autoriser ou non les caractères non UTF-8 dans les journaux d'utilisateurs. Si ce paramètre est défini sur `true`, tout caractère non UTF-8 sera remplacé par la chaîne spécifiée par `non_utf8_replacement_string`. S'il est défini sur `false`, tout caractère non UTF-8 déclenche une erreur du plug-in.
`require_valid_tags`	Bool	`false`	Indique s'il faut rejeter les entrées de journal avec des tags non valides. Si ce paramètre est défini sur `false`, les tags seront validés en convertissant tout tag qui n'est pas de type chaîne en chaîne, et en supprimant tout caractère non UTF-8 et d'autres caractères non valides.
`non_utf8_replacement_string`	chaîne	`""`(espace)	Si le paramètre `coerce_to_utf8` est défini sur `true`, tout caractère non UTF-8 sera remplacé par la chaîne spécifiée ici.

¹Cette fonctionnalité est activée par défaut dans les instances de VM s'exécutant dans un environnement flexible App Engine ou Google Kubernetes Engine.

Appliquer la configuration d'agent personnalisée

La personnalisation de l'agent Logging vous permet d'ajouter vos propres fichiers de configuration fluentd :

Instance Linux

Copiez vos fichiers de configuration dans le répertoire suivant :
```
/etc/google-fluentd/config.d/
```
Le script d'installation de l'agent Logging remplit ce répertoire avec les fichiers de configuration "catch-all" par défaut. Pour en savoir plus, consultez la section Obtenir le code source de l'agent Logging.
Facultatif. Validez votre modification de configuration en exécutant la commande suivante :
```
sudo service google-fluentd configtest
```
Redémarrez l'agent en exécutant la commande suivante :
```
sudo service google-fluentd force-reload
```

Instance Windows

Copiez vos fichiers de configuration dans le sous-répertoire config.d du répertoire d'installation de l'agent. Si vous avez accepté le répertoire d'installation par défaut, ce répertoire est le suivant :
```
C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
```
Redémarrez l'agent en exécutant les commandes suivantes dans une interface système de ligne de commande :
```
net stop  StackdriverLogging
net start StackdriverLogging
```

Pour en savoir plus sur les fichiers de configuration fluentd, consultez la documentation sur la syntaxe des fichiers de configuration de fluentd.

Configurer l'agent Logging

Configuration par défaut

Définitions de configuration par défaut

Emplacement du fichier de configuration racine

Configuration de Syslog

Configuration du plug-in d'entrée in_forward

Configuration des entrées de journal des applications tierces

Configuration du plug-in de sortie Google Cloud fluentd

Configuration de la surveillance

Télémétrie du plug-in de sortie

Prometheus et configuration du plug-in prometheus_monitor

Traiter les charges utiles

Champs spéciaux dans les charges utiles structurées

Champs liés au temps

Personnaliser la configuration de l'agent

Diffuser des journaux à partir d'entrées supplémentaires

Diffuser des journaux non structurés (texte) via des fichiers journaux

Diffuser des journaux structurés (JSON) via des fichiers journaux

Diffuser des journaux structurés (JSON) via le plug-in in_forward

Diffuser des enregistrements de journal structurés (JSON) à partir du code de l'application

Définir des étiquettes d'entrée de journal

Définir des étiquettes dans des entrées de journal structurées

Définir des étiquettes statiquement

Modifier des enregistrements de journal

Définitions de configuration avancées (autres que par défaut)

Options de configuration liées à la mémoire tampon

Options de configuration liées aux projets et aux ressources surveillées

Autres options de configuration du plug-in de sortie

Appliquer la configuration d'agent personnalisée

Instance Linux

Instance Windows

Configuration du plug-in d'entrée `in_forward`

Configuration du plug-in de sortie Google Cloud `fluentd`

Diffuser des journaux structurés (JSON) via le plug-in `in_forward`