Configurer l'agent

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

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

  • vous souhaitez obtenir des détails techniques approfondis sur la configuration de l'agent Stackdriver Logging ;

  • vous souhaitez modifier la configuration de l'agent Stackdriver 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 Stackdriver 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 les journaux figurant dans la liste des journaux par défaut à Stackdriver Logging. Vous pouvez configurer l'agent pour qu'il diffuse des journaux supplémentaires. Consultez la section Personnaliser la configuration de l'agent Stackdriver Logging ci-dessous pour en savoir plus.

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 de sources externes, tels que des fichiers sur disque, ou pour analyser les enregistrements de journal 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é fluentd de in_tail. Chaque enregistrement de journal est converti en une structure d'entrée de journal pour Stackdriver 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 la gravité. L'agent Stackdriver Logging requiert que chaque enregistrement de journal soit tagué avec un tag au format chaîne. Tous les filtres et 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 Stackdriver 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.

Configuration de Syslog

  • Emplacements des fichiers de configuration :

    • Linux : /etc/google-fluentd/config.d/syslog.conf
    • Windows : C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

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

  • Description : ce fichier inclut la configuration nécessaire pour spécifier syslog en tant qu'entrée de journal.

  • Voir 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 enregistrera la dernière position lue dans ce fichier. Voir 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. Voir 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 :

    • Linux : /etc/google-fluentd/config.d/forward.conf
    • Windows : C:\Program Files (x86)\Stackdriver\LoggingAgent\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.

  • Voir 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 modifiée en 0.0.0.0.

Configuration des entrées de journal des applications tierces

  • Emplacements des fichiers de configuration :

    • Linux : /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
    • Windows : C:\Program Files (x86)\Stackdriver\LoggingAgent\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).

  • Voir 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. Voir 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. Voir 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 enregistrera la dernière position lue dans ce fichier. Voir 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. Voir 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.

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 1-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.

  • Voir le dépôt de configuration.

Nom de la configuration Type Par défaut Description
buffer_chunk_limit Chaîne 1M 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 seront 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. Un fragment de mémoire tampon est vidé si l'une des deux conditions est remplie :
1. flush_interval est impliqué.
2. La taille du tampon atteint 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 seront 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 du tampon atteint 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 de 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 (fonctionnement 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 (fonctionnement 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 sera 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 (fonctionnement par défaut). L'intervalle d'attente sera doublé à 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 sera généralement moindre.
partial_success Bool true Indique la compatibilité avec l'ingestion partielle des journaux. Si la valeur est 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. Si la valeur est false, l'ensemble complet est supprimé s'il contient des entrées de journal non valides.
enable_monitoring Bool true Lorsque ce paramètre est défini sur true, l'agent Logging affiche deux métriques : une métrique de comptage de requêtes qui garde la trace du nombre d'entrées de journal à envoyer à Stackdriver Logging et un nombre d'entrées ingérées qui garde la trace du nombre réel d'entrées de journal ingérées correctement par Stackdriver Logging. Lorsqu'il est défini sur false, ces métriques ne sont pas affichées.
monitoring_type chaîne prometheus Type de surveillance. La seule option aujourd'hui est prometheus, mais il est possible que d'autres options soient compatibles à l'avenir. Si enable_monitoring est défini sur true et que monitoring_type est prometheus, l'agent Logging affiche certaines métriques locales au format Prometheus sur localhost:24231/metrics. Afficher les détails
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 ResourceTrace traceId. Les détails concernant le formatage automatique sont disponibles dans la section Champs spéciaux dans les charges utiles structurées.

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. Consultez la section Diffuser des enregistrements de journal structurés (JSON) via le plug-in in_forward pour plus d'informations sur ce plug-in.

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 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.

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 Stackdriver 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 applique un traitement spécial aux champs suivants, ce qui permet de définir des champs spécifiques dans l'objet LogEntry, qui sont ensuite écrits dans l'API Logging.

Tous les champs du tableau ci-dessous, s'ils existent, sont supprimés de la charge utile.

Champ de journal JSON Champ de LogEntry Fonction de l'agent Logging
severity severity L'agent Logging tente de faire correspondre différentes chaînes de gravité courantes. Cela inclut la liste des chaînes LogSeverity reconnues par l'API Logging.
message textPayload (ou partie de jsonPayload) Si, après avoir supprimé des champs spéciaux, il ne reste plus qu'un champ message, ce champ message est enregistré en tant que textPayload. Si votre entrée de journal contient une trace de la pile d'exception, elle doit être réglée sur ce champ message de journal JSON, de sorte qu'elle puisse être analysée et enregistrée dans Stackdriver Error Reporting.
log textPayload (ou partie de jsonPayload) Ne s'applique qu'à Cloud Functions et à Google Kubernetes Engine : si, après suppression des champs spéciaux, il ne reste qu'un champ log, ce champ log est enregistré en tant que textPayload.
httpRequest httpRequest Ce champ est supprimé de jsonPayload et attribué au champ HttpRequest de l'objet LogEntry.
champs liés au temps timestamp Pour en savoir plus, consultez la section Champs liés au temps.
logging.googleapis.com/trace trace logging.googleapis.com/trace est supprimé de jsonPayload et attribué au champ LogEntry de trace. Par exemple, supposons que la valeur de logging.googleapis.com/trace soit [V]. [V] doit être formaté en tant que projects/[PROJECT-ID]/traces/[TRACE-ID], afin de pouvoir être utilisé par la visionneuse de journaux et le lecteur de traces pour regrouper les entrées de journal et les afficher en parallèle avec les traces. Si la valeur de autoformat_stackdriver_trace est true et que [V] correspond au format traceId de ResourceTrace, le champ trace de LogEntry aura comme valeur projects/[PROJECT-ID]/traces/[V].
logging.googleapis.com/spanId spanId Ce champ est supprimé de jsonPayload et attribué au champ spanId de LogEntry.
logging.googleapis.com/operation operation Ce champ est supprimé de jsonPayload et attribué à LogEntryOperation. Ce champ est également utilisé par la visionneuse de journaux pour regrouper les entrées de journal associées.
logging.googleapis.com/sourceLocation sourceLocation Ce champ est supprimé de jsonPayload et attribué à LogEntrySourceLocation.

Tout champ d'enregistrement structuré restant fait partie de jsonPayload. S'il ne reste qu'un champ message, la valeur de ce champ est stockée sous le nom textPayload dans l'entrée de journal.

Champs liés au temps

L'agent Logging peut recevoir et traiter des champs liés au temps dans plusieurs formats JSON. Si l'une des représentations d'horodatage JSON suivantes est présente dans un enregistrement structuré, l'agent Logging supprime les champs de jsonPayload et les réduit à une seule représentation dans le champ timestamp de l'objet LogEntry :

  • jsonPayload contient un champ timestamp qui inclut les champs seconds et nanos, qui représentent un nombre signé de secondes de la période UTC et un nombre non négatif de secondes fractionnaires :

    {
      "timestamp": {
        "seconds": CURRENT_SECONDS,
        "nanos": CURRENT_NANOS
      }
    }
    
  • jsonPayload contient à la fois les champs timestampSeconds et timestampNanos :

    {
       "timestampSeconds": CURRENT_SECONDS,
       "timestampNanos": CURRENT_NANOS
    }
    
  • jsonPayload contient un champ time comprenant les mêmes informations de secondes et nanosecondes sous forme de chaîne : "[-]sssssssss.nnnnnnnnn".

    {
        "time": CURRENT_TIME
    }
    

Une fois que l'agent Logging a détecté une représentation d'horodatage, aucune autre suppression liée à l'horodatage ne se produit, même si des représentations supplémentaires de format acceptable sont présentes dans l'enregistrement structuré.

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 Stackdriver 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 1-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.

  • Voir 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

  1. Créez un fichier journal à l'aide de la commande suivante :

    $ touch /tmp/test-unstructured-log.log
    
  2. Créez un fichier de configuration dans le répertoire de configuration tiers (/etc/google-fluentd/config.d sous Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d sous Windows) avec la configuration ci-dessous. Vous pouvez également ajouter la configuration à un fichier existant dans le fichier de configuration principal :

    $ sudo vim /etc/google-fluentd/config.d/test-unstructured-log.conf
    $ cat /etc/google-fluentd/config.d/test-unstructured-log.conf
    <source>
        @type tail
        # Format 'none' indicates the log is unstructured (text).
        format none
        # 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>
    
  3. Redémarrez l'agent pour appliquer les modifications de la configuration :

    $ sudo service google-fluentd restart
    
  4. 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
    
  5. Consultez la visionneuse de journaux pour voir 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 activer la journalisation structurée pour certaines entrées de journal lors de l'installation de l'agent Logging. Pour plus d'informations, consultez la section Journalisation structurée.

Vous pouvez également personnaliser l'agent Logging pour ajouter une entrée de journal JSON. En créant cette configuration, l'agent s'attend à ce que chaque enregistrement de journal soit un objet JSON :

  1. Créez un fichier journal :

    $ touch /tmp/test-structured-log.log
    
  2. Créez un fichier de configuration dans le répertoire de configuration tiers (/etc/google-fluentd/config.d sous Linux ou C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d sous Windows) avec la configuration ci-dessous. Vous pouvez également ajouter la configuration à un fichier existant dans le fichier de configuration principal :

    $ 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 'JSON' indicates the log is structured (JSON).
        format json
        # 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>
    
  3. Redémarrez l'agent pour appliquer les modifications de la configuration :

    $ sudo service google-fluentd restart
    
  4. 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
    
  5. Consultez la visionneuse de journaux pour voir 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"
    }
    

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 :

  1. 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
    
  2. Consultez la visionneuse de journaux pour voir 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 libellés de LogEntry et de MonitoredResource lors de l'ingestion de journaux dans Stackdriver Logging. Toutes les entrées de journal sont associées aux ressources surveillées. Pour plus d'informations, consultez la liste des types de ressources surveillées Stackdriver 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ément 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 des exemples, 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 :

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 ci-dessus dans une étiquette de métadonnées environment. Pour cela, ajoutez les éléments suivants à 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 Stackdriver 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 de façon statique

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 les éléments suivants à 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 Stackdriver Logging, type google_cloud labels {"environment": "production"} ...

Dans ce cas, au lieu d'utiliser une table de correspondance 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 de labels, label_map et des autres paramètres de l'agent Logging, consultez la section Définir des étiquettes d'entrée de journal.

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 de saisir une boucle morte.

Le plug-in de sortie fluent-plugin-detect-exceptions analyse un flux de journaux composé d'enregistrements de journal non structurés (texte) ou JSON, afin de rechercher des traces de la pile d'exceptions 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.

Les options de configuration ci-dessous vous permettent d'ajuster le mécanisme de 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 buffer_type est défini sur buf_file, 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 la valeur de buffer_type est 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 du tampon atteint ce nombre de fragments, le comportement de la mémoire tampon est contrôlé par buffer_queue_full_action. Par défaut, des exceptions sont lancées.
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 : Lancez BufferQueueLimitError lorsque la file d'attente est pleine. La manière dont BufferQueueLimitError est traitée 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 condition de la mémoire tampon soit résolue. Cette action est utile pour les cas d'utilisation de type batch (par lots). fluentd déconseille d'utiliser une action de blocage afin d'éviter l'erreur BufferQueueLimitError. Si vous atteignez fréquemment la valeur BufferQueueLimitError, cela signifie que votre capacité de destination est insuffisante pour votre trafic.
3. drop_oldest_chunk : ce mode supprime les fragments les plus anciens.

Les options de configuration ci-dessous 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 cette valeur est spécifiée, elle remplace project_id en identifiant le projet GCP 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_json1 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 cette configuration est définie sur true, et qu'une entrée de journal non structurée (texte) est détectée comme étant au format JSON, elle sera 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 la valeur est définie sur true, tout caractère non UTF-8 sera remplacé par la chaîne spécifiée par non_utf8_replacement_string. Si la valeur est définie 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 cette option est définie sur false, les tags seront validés en convertissant tout tag n'étant 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 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

  1. Copiez vos fichiers de configuration dans le répertoire suivant :

    /etc/google-fluentd/config.d/
    
  2. Redémarrez l'agent en exécutant la commande suivante :

    sudo service google-fluentd force-reload
    

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.

Instance Windows

  1. 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\
    
  2. 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 relative à la syntaxe de fichier de configuration de fluentd.

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

Envoyer des commentaires concernant…

Stackdriver Logging
Besoin d'aide ? Consultez notre page d'assistance.