Collecte de logs à partir des navigateurs
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

Collecte de logs à partir des navigateurs

Cette traduction n'est pas à jour. Pour consulter la dernière version en anglais, cliquez ici

Envoyez des logs à Datadog à partir de navigateurs Web ou d’autres clients Javascript grâce à la bibliothèque de journalisation JavaScript côté client datadog-logs de Datadog.

Utilisez la bibliothèque datadog-logs pour envoyer des logs directement à Datadog depuis les clients JS. Vous pourrez notamment :

  • Utiliser la bibliothèque en tant que logger et transmettre tous les logs à Datadog sous forme de documents JSON
  • Ajouter du contexte et des attributs personnalisés supplémentaires pour chaque log envoyé
  • Incorporer et transmettre automatiquement chaque erreur frontend
  • Transmettre les erreurs frontend
  • Enregistrer l’adresse IP et le user agent réels du client
  • Optimiser l’utilisation du réseau grâce aux envois automatiques en masse

Configuration

  1. Obtenir un token client Datadog : pour des raisons de sécurité, les clés d’API ne peuvent pas être utilisées pour configurer la bibliothèque datadog-logs, car elles seraient exposées côté client dans le code JavaScript. Pour recueillir des logs depuis un navigateur Web, vous devez utiliser un token client. Pour en savoir plus sur la configuration d’un token client, consultez la documentation relative aux tokens client.
  2. Configurez la bibliothèque de collecte de logs à partir des navigateurs de Datadog via NPM ou collez le bundle directement dans la balise head.

Configuration via NPM

Après avoir ajouté @datadog/browser-logs à votre fichier package.json, lancez la bibliothèque avec :

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.init({
  clientToken: '<TOKEN_CLIENT_DATADOG>',
  datacenter: 'us',
  forwardErrorsToLogs: true,
  sampleRate: 100
});

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.init({
  clientToken: '<TOKEN_CLIENT_DATADOG>',
  datacenter: 'eu',
  forwardErrorsToLogs: true,
  sampleRate: 100
});

Configuration via bundle

Afin de ne manquer aucun log ni aucune erreur, assurez-vous de charger et de configurer la bibliothèque au début de la sectionde vos pages.

<html>
  <head>
    <title>Exemple pour envoyer les logs à Datadog</title>
    <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-logs-us.js"></script>
    <script>
      window.DD_LOGS && DD_LOGS.init({
        clientToken: '<TOKEN_CLIENT>',
        forwardErrorsToLogs: true,
        sampleRate: 100
      });
    </script>
  </head>
</html>
<html>
  <head>
    <title>Exemple pour envoyer les logs à Datadog</title>
    <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-logs-eu.js"></script>
    <script>
      window.DD_LOGS && DD_LOGS.init({
        clientToken: '<TOKEN_CLIENT>',
        forwardErrorsToLogs: true,
        sampleRate: 100
      });
    </script>
  </head>
</html>

Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement de la bibliothèque échoue.

Paramètres de lancement

Les paramètres suivants peuvent être utilisés pour configurer l’envoi des logs à Datadog avec la bibliothèque :

ParamètreTypeObligatoireValeur par défautDescription
clientTokenChaîneOui-Un token client Datadog.
datacenterChaîneOuiusLe site Datadog associé à votre organisation. Choisissez us pour le site américain ou eu pour le site européen.
forwardErrorsToLogsBooléennontrueDéfinissez ce paramètre sur false pour désactiver l’envoi des logs console.error, des exceptions non interceptées et des erreurs réseau à Datadog.
sampleRateNuméronon100Le pourcentage de sessions à surveiller. Les logs sont uniquement envoyés pour les sessions surveillées. Choisissez une valeur entre 100 (toutes les sessions) et 0 (aucune session).

Envoyer une entrée de log personnalisée

Une fois la bibliothèque de collecte de logs à partir des navigateurs lancée, envoyez une entrée de log personnalisée avec l’API :

logger.debug | info | warn | error (message: string, messageContext = Context)

    import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.info('Button clicked', { name: 'buttonName', id: 123 });

    window.DD_LOGS && DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 });

    Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement de la bibliothèque échoue.

    On obtient le résultat suivant :

    {
  "status": "info",
  "session_id": "1234",
  "name": "buttonName",
  "id": 123,
  "message": "Button clicked",
  "http": {
    "url": "...",
    "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.130 Safari/537.36"
  },
  "network": {"client": {"ip": "109.30.xx.xxx"}}
}

    Le logger ajoute les informations suivantes par défaut :

    • view.url
    • session_id
    • http.useragent
    • network.client.ip

    Utiliser le statut comme paramètre

    Une fois la bibliothèque de collecte de logs à partir des navigateurs lancée, utilisez l’API pour envoyer une entrée de log personnalisée directement à Datadog avec son statut comme paramètre :

    log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error')

      import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.log(<MESSAGE>,<ATTRIBUTS_JSON>,<STATUT>);

      window.DD_LOGS && DD_LOGS.logger.log(<MESSAGE>,<ATTRIBUTS_JSON>,<STATUT>);
      Paramètre fictifDescription
      <MESSAGE>Le message de votre log entièrement indexé par Datadog.
      <ATTRIBUTS_JSON>Un objet JSON valide qui comprend tous les attributs joints au <MESSAGE>.
      <STATUT>Statut de votre log. Les valeurs de statut acceptées sont debug, info, warn ou error.

      Utilisation avancée

      Définir plusieurs loggers

      La bibliothèque de collecte de logs à partir des navigateurs contient un logger par défaut, mais vous pouvez également définir d’autres loggers. Cette option est très utile lorsque plusieurs équipes travaillent sur un même projet.

      Créer un logger

      Une fois la bibliothèque de collecte de logs à partir des navigateurs lancée, utilisez l’API createLogger pour définir un nouveau logger :

      createLogger (name: string, conf?: {
    level?: 'debug' | 'info' | 'warn' | 'error'
    handler?: 'http' | 'console' | 'silent'
    context?: Context
})

      Remarque : ces paramètres peuvent également être définis avec les API setLevel, setHandler et setContext.

      Accéder à un logger personnalisé

      Une fois votre logger créé, vous pouvez y accéder dans n’importe quelle partie de votre code JavaScript avec l’API :

      getLogger (name: chaîne)

      Exemple

      Imaginons que vous disposez d’un logger signupLogger, défini avec tous les autres loggers :

        import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.createLogger('signupLogger', 'info', 'http', {'env', 'staging'})

        Vous pouvez à présent l’utiliser dans une autre partie du code avec :

        import { datadogLogs } from '@datadog/browser-logs';

const signupLogger = datadogLogs.getLogger('signupLogger')
signupLogger.info('Test sign up completed')

        if (window.DD_LOGS) {
    const signupLogger = DD_LOGS.createLogger('signupLogger', 'info', 'http', {'env', 'staging'})
}

        Vous pouvez à présent l’utiliser dans une autre partie du code avec :

        if (window.DD_LOGS) {
    const signupLogger = DD_LOGS.getLogger('signupLogger')
    signupLogger.info('Test sign up completed')
}

        Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement de la bibliothèque échoue.

        Remplacer le contexte

        Contexte global

        Une fois la bibliothèque de collecte de logs à partir des navigateurs lancée, vous pouvez :

        • Définir l’intégralité du contexte pour tous vos loggers avec l’API setLoggerGlobalContext (context: Context).
        • Ajouter un contexte à l’ensemble de vos loggers avec l’API addLoggerGlobalContext (key: string, value: any).
          import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.setLoggerGlobalContext("{'env', 'staging'}");

datadogLogs.addLoggerGlobalContext('referrer', document.referrer);

          window.DD_LOGS && DD_LOGS.setLoggerGlobalContext({env: 'staging'});

window.DD_LOGS && DD_LOGS.addLoggerGlobalContext('referrer', document.referrer);

          Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement de la bibliothèque échoue.

          Contexte d’un logger

          Une fois votre logger créé, vous pouvez :

          • Définir l’intégralité du contexte pour votre logger avec l’API setContext (context: Context).
          • Ajouter un contexte à votre logger avec l’API addContext (key: string, value: any) :
            import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.setContext("{'env', 'staging'}");

datadogLogs.addContext('referrer', document.referrer);

            window.DD_LOGS && DD_LOGS.setContext("{'env', 'staging'}");

window.DD_LOGS && DD_LOGS.addContext('referrer', document.referrer);

            Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement de la bibliothèque échoue.

            Filtrer par statut

            Une fois la bibliothèque de collecte de logs à partir des navigateurs lancée, vous pouvez définir le niveau de log minimum pour votre logger avec l’API :

            setLevel (level?: 'debug' | 'info' | 'warn' | 'error')

            Seuls les logs avec un statut égal ou supérieur au niveau indiqué sont envoyés.

              import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.setLevel('<NIVEAU>');

              window.DD_LOGS && DD_LOGS.logger.setLevel('<NIVEAU>');

              Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement de la bibliothèque échoue.

              Modifier la destination

              Par défaut, les loggers créés par la bibliothèque de collecte de logs à partir des navigateurs envoient les logs à Datadog. Une fois la bibliothèque lancée, il est possible de configurer le logger de façon à ce que les logs soient envoyés à la console ou qu’ils ne soient pas envoyés du tout (silent) avec l’API :

              setHandler (handler?: 'http' | 'console' | 'silent')

                import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.setHandler('<GESTIONNAIRE>');

                window.DD_LOGS && DD_LOGS.logger.setHandler('<GESTIONNAIRE>');

                Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement de la bibliothèque échoue.

                La bibliothèque datadog-logs prend en charge tous les navigateurs modernes pour ordinateurs et appareils mobiles. IE10 et IE11 sont également pris en charge.

                Pour aller plus loin

                Documentation, liens et articles supplémentaires utiles:

                Paquet NPM @datadog/browser-logsNPM more more Apprendre à traiter vos logsDOCUMENTATION more more Apprendre à explorer vos logsDOCUMENTATION more more
                edit Modifier cette page

                Sur cette page