Importer des source maps JavaScript

Docs > RUM et Session Replay > Guides pour les solutions Real User Monitoring et Session Replay > Importer des source maps JavaScript

Présentation

Si votre code source JavaScript frontend est minifié, importez vos source maps dans Datadog pour désobfusquer vos différentes stack traces. Pour une erreur donnée, vous avez accès au chemin du fichier, au numéro de ligne ainsi qu’à un extrait de code pour chaque frame de la stack trace associée. Datadog peut également associer des stack frames à votre code source dans votre référentiel.

Seules les erreurs recueillies par la solution Real User Monitoring (RUM) peuvent être déminifiées.

Instrumenter votre code

Configurez votre bundler JavaScript de façon à ce qu’il génère des source maps lorsque vous minifiez votre code source. Ces source maps incluent directement le code source associé dans l’attribut sourcesContent. Veillez également à ce que la taille de chaque source map combinée à la taille du fichier minifié associé ne dépasse pas la limite de 50 Mo.

Consultez les configurations suivantes qui reposent sur des bundlers JavaScript populaires.

Vous pouvez générer des source maps à l’aide du plug-in webpack intégré SourceMapDevToolPlugin.

Consultez l’exemple de configuration ci-dessous dans votre fichier webpack.config.js :

// ...
const webpack = require('webpack');

module.exports = {
  mode: 'production',
  devtool: false,
  plugins: [
    new webpack.SourceMapDevToolPlugin({
      noSources: false,
      filename: '[file].map'
    }),
    // ...
  ],
  optimization: {
    minimize: true,
    // ...
  },
  // ...
};

Remarque : si vous utilisez le langage TypeScript, définissez compilerOptions.sourceMap sur true dans votre fichier tsconfig.json.

Parcel génère des source maps par défaut lorsque vous exécutez la commande build parcel build <fichier d'entrée>

Une fois le build de votre application créé, les bundlers génèrent un répertoire (généralement intitulé dist) contenant les fichiers JavaScript minifiés avec leurs source maps correspondantes.

Vous trouverez un exemple ci-dessous :

./dist
    javascript.364758.min.js
    javascript.364758.js.map
    ./subdirectory
        javascript.464388.min.js
        javascript.464388.js.map

Si la somme de la taille des fichiers javascript.364758.min.js et javascript.364758.js.map dépasse la limite de 50 Mo, réduisez cette taille en configurant votre bundler de façon à diviser le code source en plusieurs sections plus petites. Pour en savoir plus, consultez la section Division de code avec WebpackJS (en anglais).

Importer vos source maps

Le meilleur moyen d’importer des source maps est d’ajouter une étape supplémentaire dans votre pipeline de CI et d’exécuter la commande dédiée depuis l’interface de ligne de commande Datadog. Cette commande analyse le répertoire dist et ses sous-répertoires pour importer automatiquement les source maps avec leurs fichiers minifiés associés.

Ajoutez @datadog/datadog-ci à votre fichier package.json (assurez-vous d’utiliser la dernière version).
Créez une clé d’API Datadog dédiée et exportez-la en tant que variable d’environnement DATADOG_API_KEY.

Exécutez la commande suivante :

datadog-ci sourcemaps upload /path/to/dist \
  --service=my-service \
  --release-version=v35.2395005 \
  --minified-path-prefix=https://hostname.com/static/js

Ajoutez @datadog/datadog-ci à votre fichier package.json (assurez-vous d’utiliser la dernière version).
Créez une clé d’API Datadog dédiée et exportez-la en tant que variable d’environnement DATADOG_API_KEY.
Configurez l’interface de ligne de commande de façon à importer les fichiers sur le site européen en exportant deux variables d’environnement : export DATADOG_SITE="datadoghq.eu" et export DATADOG_API_HOST="api.datadoghq.eu".

Exécutez la commande suivante :

datadog-ci sourcemaps upload /path/to/dist \
  --service=my-service \
  --release-version=v35.2395005 \
  --minified-path-prefix=https://hostname.com/static/js

Pour minimiser l’impact sur les performances de votre intégration continue, l’interface de ligne de commande est optimisée pour permettre l’importation d’autant de source maps que nécessaires en peu de temps (généralement quelques secondes).

Les paramètres --service et --release-version doivent correspondre aux tags service et version de vos événements RUM. Pour en savoir plus sur la configuration de ces tags, consultez la documentation relative à l’initialisation du SDK Browser. Les source maps qui ont été importées seront alors utilisées pour désobfusquer les erreurs recueillies par le SDK RUM.

Lorsque vous exécutez la commande sur l’exemple de répertoire dist, Datadog s’attend à ce que votre serveur ou CDN fournissent les fichiers JavaScript sur https://hostname.com/static/js/javascript.364758.min.js et https://hostname.com/static/js/subdirectory/javascript.464388.min.js.

Remarque : seules les source maps avec l’extension .js.map peuvent déminifier des stack traces dans la solution de suivi des erreurs. Les sources maps ayant une autre extension (comme .mjs.map) sont acceptées, mais ne peuvent pas déminifier de stack traces.

Si vous distribuez les mêmes fichiers source JavaScript depuis différents sous-domaines, importez la source map associée une seule fois, et utilisez-la pour les différents sous-domaines en spécifiant le chemin du préfixe absolu plutôt que l'URL complète. Par exemple, indiquez /static/js plutôt que https://hostname.com/static/js).

Associer des stack frames à votre code source

Si vous exécutez la commande datadog-ci sourcemaps upload dans un répertoire Git fonctionnel, Datadog recueille des métadonnées sur ce répertoire. La commande datadog-ci recueille l’URL du répertoire, le hash du commit actuel ainsi que la liste des chemins de fichier du répertoire qui sont associés à vos source maps. Pour en savoir plus sur la collecte de métadonnées Git, consultez la documentation datadog-ci.

Datadog affiche des liens vers votre code source dans des stack frames non minifiés.

Dépanner les erreurs plus facilement

Sans chemin de fichier ni numéro de ligne, une stack trace minifiée ne permet pas de résoudre les problèmes concernant votre codebase. De plus, l’extrait de code est également minifié (il s’agit donc d’une longue ligne de code transformé), ce qui complexifie encore plus le processus de dépannage.

L’exemple suivant représente une stack trace minifiée :

Stack trace minifiée pour le suivi des erreurs

À l’inverse, une stack trace non minifiée fournit tout le contexte dont vous avez besoin pour corriger rapidement et aisément votre problème. Pour les stack frames associés à votre code source, Datadog génère également un lien direct vers votre référentiel :