Collecte de logs à partir des navigateurs

Envoyez des logs à Datadog à partir de navigateurs Web ou d’autres clients Javascript avec le SDK de collecte de logs à partir des navigateurs.

Utilisez le SDK de collecte de logs à partir des navigateurs afin d’envoyer des logs directement à Datadog depuis les clients JS. Vous pourrez notamment :

Utiliser le SDK en tant que logger ; tous les logs sont transmis à 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 groupés automatiques

Configuration

Token client Datadog : pour des raisons de sécurité, les clés d’API ne peuvent pas être utilisées pour configurer la le SDK de collecte de logs à partir des navigateurs, 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. Consultez la documentation relative aux tokens client pour en savoir plus.

SDK Datadog de collecte de logs à partir des navigateurs : configurez le SDK via NPM ou utilisez les extraits de code CDN asynchrone ou CDN synchrone dans le tag head.

Navigateurs pris en charge : le SDK de collecte de logs à partir des navigateurs prend en charge tous les navigateurs modernes pour ordinateurs et appareils mobiles, y compris IE10 et IE11. Consultez le tableau des navigateurs pris en charge.

Choisir la bonne méthode d’installation

Méthode d’installation	Cas d’utilisation
npm (node package manager)	Cette méthode est recommandée pour les applications Web modernes. Le SDK de collecte de logs à partir des navigateurs est inclus dans le package avec le reste de votre code JavaScript frontend. Les performances de chargement des pages ne sont pas affectées. Le SDK peut toutefois omettre les erreurs, les ressources et les actions utilisateur déclenchées avant l’initialisation du SDK. Remarque : si vous avez recours au SDK RUM, il est recommandé d’utiliser une version correspondante.
CDN asynchrone	Cette méthode est recommandée pour les applications Web devant satisfaire des objectifs de performance. Le SDK de collecte de logs à partir des navigateurs est chargé à partir de notre CDN de façon asynchrone : ainsi, le téléchargement du SDK n’affecte pas les performances de chargement des pages. Le SDK peut toutefois omettre les erreurs, les ressources et les actions utilisateur déclenchées avant l’initialisation du SDK.
CDN synchrone	Cette méthode est recommandée pour recueillir tous les événements RUM. Le SDK de collecte de logs à partir des navigateurs est chargé à partir de notre CDN de façon synchrone : ainsi, le SDK est chargé en premier et recueille toutes les erreurs, ressources et actions utilisateur. Cette méthode peut avoir un impact sur les performances de chargement des pages.

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>',
  site: '<SITE_DATADOG>',
  forwardErrorsToLogs: true,
  sampleRate: 100,
})

CDN asynchrone

Chargez et configurez le SDK dans la section head de vos pages.

<html>
  <head>
    <title>Exemple pour envoyer les logs à Datadog</title>
      <script>
      (function(h,o,u,n,d) {
        h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
        d=o.createElement(u);d.async=1;d.src=n
        n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
      })(window,document,'script','https://www.datadoghq-browser-agent.com/datadog-logs.js','DD_LOGS')
      DD_LOGS.onReady(function() {
          DD_LOGS.init({
            clientToken: 'XXX',
            site: 'datadoghq.com',
            forwardErrorsToLogs: true,
            sampleRate: 100,
          })
        })
      </script>
  </head>
</html>

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

Pour recevoir tous les logs et toutes les erreurs, chargez et configurez le SDK au début de la section head de 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.js"></script>
    <script>
      window.DD_LOGS &&
        DD_LOGS.init({
          clientToken: '<TOKEN_CLIENT>',
          site: '<SITE_DATADOG>',
          forwardErrorsToLogs: true,
          sampleRate: 100,
        })
    </script>
  </head>
</html>

Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement du SDK échoue.

TypeScript

Les types sont compatibles avec TypeScript >= 3.0. Pour les versions antérieures, importez les sources JS et utilisez des variables globales pour éviter tout problème de compilation :

import '@datadog/browser-logs/bundle/datadog-logs'

window.DD_LOGS.init({
  clientToken: '<TOKEN_CLIENT>',
  site: '<SITE_DATADOG>',
  forwardErrorsToLogs: true,
  sampleRate: 100,
})

Configuration

Paramètres de lancement

Les paramètres suivants peuvent être utilisés pour configurer l’envoi des logs à Datadog avec le SDK Datadog de collecte de logs à partir des navigateurs :

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`clientToken`	Chaîne	Oui		Un token client Datadog.
`site`	Chaîne	Oui	`datadoghq.com`	Le site Datadog associé à votre organisation. Site américain : `datadoghq.com`. Site européen : `datadoghq.eu`.
`service`	Chaîne	Non		Le nom de service pour votre application.
`env`	Chaîne	Non		L’environnement de l’application, par exemple : prod, pre-prod, staging, etc.
`version`	Chaîne	Non		La version de l’application, par exemple : 1.2.3, 6c44da20, 2020.02.13, etc.
`forwardErrorsToLogs`	Booléen	Non	`true`	Dé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.
`sampleRate`	Nombre	Non	`100`	Le pourcentage de sessions à surveiller : `100` (toutes les sessions) et `0` (aucune session). Seules les sessions surveillées envoient des logs.
`silentMultipleInit`	Booléen	Non		Permet d’empêcher le logging des erreurs lorsqu’il y a plusieurs init.

Options qui doivent avoir une configuration correspondante lors de l’utilisation du SDK RUM :

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`trackSessionAcrossSubdomains`	Booléen	Non	`false`	Préserver la session pour tous les sous-domaines d’un même site.
`useSecureSessionCookie`	Booléen	Non	`false`	Utiliser un cookie de session sécurisé. Ce paramètre désactive les logs envoyés sur des connexions non sécurisées (connexions non HTTPS).
`useCrossSiteSessionCookie`	Booléen	Non	`false`	Utilise un cookie de session intersite sécurisé. Cela permet l’exécution du SDK logs lorsque le site est chargé à partir d’un autre site (iframe). Implique l’utilisation de `useSecureSessionCookie`.

Utilisation

Logs personnalisés

Une fois le SDK Datadog de collecte de logs à partir des navigateurs lancé, envoyez une entrée de log personnalisée directement à Datadog avec l’API :

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

NPM

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

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

CDN asynchrone

DD_LOGS.onReady(function() {
  DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })
})

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

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 du SDK échoue.

Résultats

Les résultats sont les mêmes que vous utilisez NPM, CDN asynchrone ou CDN synchrone :

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

Paramètre status

Une fois le SDK Datadog de collecte de logs à partir des navigateurs lancé, envoyez une entrée de log personnalisée directement à Datadog avec l’API en utilisant le statut comme paramètre :

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

NPM

Pour NPM, utilisez :

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

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

CDN asynchrone

Pour CDN asynchrone, utilisez :

DD_LOGS.onReady(function() {
  DD_LOGS.logger.log(<MESSAGE>,<ATTRIBUTS_JSON>,<STATUT>);
})

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

Pour CDN synchrone, utilisez :

window.DD_LOGS && DD_LOGS.logger.log(<MESSAGE>,<ATTRIBUTS_JSON>,<STATUT>);

Placeholders

Les placeholders dans les exemples ci-dessus sont décrits plus bas :

Placeholder	Description
`<MESSAGE>`	Le message de votre log qui est complètement indexé par Datadog.
`<ATTRIBUTS_JSON>`	Un objet JSON valide qui comprend tous les attributs joints au `<MESSAGE>`.
`<STATUT>`	Le statut de votre log. Les valeurs de statut acceptées sont `debug`, `info`, `warn` ou `error`.

Utilisation avancée

Définir plusieurs loggers

Le SDK Datadog de collecte de logs à partir des navigateurs contient un logger par défaut, mais vous pouvez également définir d’autres loggers.

Créer un logger

Une fois le SDK Datadog de collecte de logs à partir des navigateurs lancé, 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éé, accédez-y dans n’importe quelle partie de votre code JavaScript avec l’API :

getLogger (name: chaîne)

NPM

Par exemple, imaginons que vous disposez d’un 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')

CDN asynchrone

Par exemple, imaginons que vous disposez d’un signupLogger, défini avec tous les autres loggers :

DD_LOGS.onReady(function() {
  const signupLogger = DD_LOGS.createLogger('signupLogger', 'info', 'http', { env: 'staging' })
})

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

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

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

Par exemple, imaginons que vous disposez d’un signupLogger, défini avec tous les autres loggers :

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 du SDK échoue.

Remplacer le contexte

Contexte global

Une fois le SDK Datadog de collecte de logs à partir des navigateurs lancé, 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)
Récupérer tout le contexte global, avec l’API getLoggerGlobalContext ()

NPM

Pour NPM, utilisez :

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

datadogLogs.setLoggerGlobalContext("{'env': 'staging'}")

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

const context = datadogLogs.getLoggerGlobalContext() // => {env: 'staging', referrer: ...}

CDN asynchrone

Pour CDN asynchrone, utilisez :

DD_LOGS.onReady(function() {
  DD_LOGS.setLoggerGlobalContext({ env: 'staging' })
})

DD_LOGS.onReady(function() {
  window.DD_LOGS && DD_LOGS.addLoggerGlobalContext('referrer', document.referrer)
})

DD_LOGS.onReady(function() {
  var context = window.DD_LOGS && DD_LOGS.getLoggerGlobalContext() // => {env: 'staging', referrer: ...}
})

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

Pour CDN synchrone, utilisez :

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

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

var context = window.DD_LOGS && DD_LOGS.getLoggerGlobalContext() // => {env: 'staging', referrer: ...}

Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement du SDK échoue.

Contexte du 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: chaîne, value: quelconque) :

NPM

Pour NPM, utilisez :

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

datadogLogs.setContext("{'env': 'staging'}")

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

CDN asynchrone

Pour CDN asynchrone, utilisez :

DD_LOGS.onReady(function() {
  DD_LOGS.setContext("{'env': 'staging'}")
})

DD_LOGS.onReady(function() {
  DD_LOGS.addContext('referrer', document.referrer)
})

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

Pour CDN synchrone, utilisez :

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 du SDK échoue.

Filtrer par statut

Une fois le SDK Datadog de collecte de logs à partir des navigateurs lancé, définissez 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.

NPM

Pour NPM, utilisez :

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

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

CDN asynchrone

Pour CDN asynchrone, utilisez :

DD_LOGS.onReady(function() {
  DD_LOGS.logger.setLevel('<NIVEAU>')
})

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

Pour CDN synchrone, utilisez :

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

Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement du SDK échoue.

Modifier la destination

Par défaut, les loggers créés par le SDK Datadog de collecte de logs à partir des navigateurs envoient les logs à Datadog. Une fois le SDK lancé, 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')

NPM

Pour NPM, utilisez :

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

datadogLogs.logger.setHandler('<HANDLER>')

CDN asynchrone

Pour CDN asynchrone, utilisez :

DD_LOGS.onReady(function() {
  DD_LOGS.logger.setHandler('<HANDLER>')
})

Remarque : les premiers appels d’API doivent être wrappés dans le callback DD_LOGS.onReady(). De cette façon, le code est uniquement exécuté une fois le SDK entièrement chargé.

CDN synchrone

Pour CDN synchrone, utilisez :

window.DD_LOGS && DD_LOGS.logger.setHandler('<HANDLER>')

Remarque : le check window.DD_LOGS est utilisé pour éviter tout problème si le chargement du SDK échoue.