Importer des source maps JavaScript
Aperçu
Si votre code source JavaScript côté client est minifié, téléchargez vos cartes sources sur Datadog pour déobfusquer vos différentes traces de pile. Pour chaque erreur donnée, vous pouvez accéder au chemin du fichier, au numéro de ligne et à l’extrait de code pour chaque cadre de la trace de pile associée. Datadog peut également lier les cadres de pile à votre code source dans votre dépôt.
Instrumentez votre code
Configurez votre JavaScript bundler de manière à ce que lors de la minification de votre code source, il génère des cartes sources qui incluent directement le code source associé dans l’attribut sourcesContent.
Assurez-vous que la taille de chaque carte source augmentée de la taille du fichier minifié associé ne dépasse pas la limite de 500 MB.
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.
Voir la configuration d’exemple 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 TypeScript, définissez compilerOptions.sourceMap sur true dans votre fichier tsconfig.json.
Parcel génère des cartes sources par défaut lorsque vous exécutez la commande de construction : parcel build <entry file>.
Vous pouvez générer des cartes sources en configurant l’option build.sourcemap dans votre fichier vite.config.js.
Voir la configuration d’exemple :
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
sourcemap: true, // generates .js.map files
minify: 'terser', // or 'esbuild'
}
})
Remarque : Si vous utilisez TypeScript, assurez-vous que compilerOptions.sourceMap est défini sur true dans votre fichier tsconfig.json.
Après avoir construit votre application, les bundlers génèrent un répertoire (généralement nommé dist) avec des fichiers JavaScript minifiés co-localisés avec leurs cartes sources 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 taille totale des fichiers pour
javascript.364758.min.js et
javascript.364758.js.map dépasse la limite de
500 MB, réduisez-la en configurant votre bundler pour diviser le code source en plusieurs morceaux plus petits. Pour plus d'informations, voir
Code Splitting avec WebpackJS.
Téléchargez vos cartes sources
La meilleure façon de télécharger des cartes sources est d’ajouter une étape supplémentaire dans votre pipeline CI et d’exécuter la commande dédiée depuis le Datadog CLI. Il scanne le répertoire dist et les sous-répertoires pour télécharger automatiquement les cartes sources avec les fichiers minifiés pertinents.
Ajoutez @datadog/datadog-ci à votre fichier package.json (assurez-vous d’utiliser la dernière version).
Créez une clé API Datadog dédiée et exportez-la en tant que variable d’environnement nommée DATADOG_API_KEY.
Exécutez la commande suivante une fois par service dans votre application :
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é API Datadog dédiée et exportez-la en tant que variable d’environnement nommée
DATADOG_API_KEY. - Configurez l’outil CLI pour téléverser des fichiers vers le site en exportant deux variables d’environnement :
export DATADOG_SITE=export DATADOG_API_HOST=api. - Exécutez la commande suivante une fois par service dans votre application :
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).
Remarque : Le téléchargement d’une carte source ne remplace pas l’existante si la version n’a pas changé.
Les paramètres --service et --release-version doivent correspondre aux balises service et version sur vos événements de suivi d’erreurs, événements RUM et journaux de navigateur. Pour plus d’informations sur la façon de configurer ces balises, consultez la documentation d’initialisation du SDK de navigateur ou la documentation de collecte des journaux de navigateur.
Si vous avez défini plusieurs services dans votre application, exécutez la commande CI autant de fois qu'il y a de services, même si vous avez un ensemble de cartes sources pour l'ensemble de l'application.
En exécutant la commande contre le répertoire exemple dist, Datadog s’attend à ce que votre serveur ou CDN livre les fichiers JavaScript à https://hostname.com/static/js/javascript.364758.min.js et https://hostname.com/static/js/subdirectory/javascript.464388.min.js.
Seules les cartes sources avec l’extension .js.map fonctionnent pour déminifier correctement les traces de pile. Les cartes sources avec d’autres extensions telles que .mjs.map sont acceptées mais ne déminifient pas les traces de pile.
Si vous servez les mêmes fichiers sources JavaScript à partir de différents sous-domaines, téléchargez la carte source associée une fois et faites-la fonctionner pour plusieurs sous-domaines en utilisant le chemin d'accès absolu au lieu de l'URL complète. Par exemple, spécifiez /static/js au lieu de https://hostname.com/static/js.
Voir tous les symboles téléchargés et gérer vos cartes sources sur la page Explorer les symboles de débogage RUM.
Liez les cadres de pile à votre code source
Si vous exécutez datadog-ci sourcemaps upload dans un répertoire de travail Git, Datadog collecte les métadonnées du dépôt. La commande datadog-ci collecte l’URL du dépôt, le hachage du commit actuel et la liste des chemins de fichiers dans le dépôt qui se rapportent à vos cartes sources. Pour plus de détails sur la collecte des métadonnées Git, consultez la documentation datadog-ci.
Datadog affiche des liens vers votre code source dans des stack frames non minifiés.
Résolvez les erreurs facilement
Sans accès au chemin de fichier et au numéro de ligne, une trace de pile minifiée n’est pas utile pour le dépannage de votre base de code. De plus, l’extrait de code est minifié (ce qui signifie qu’il y a une longue ligne de code transformé), rendant le processus de dépannage plus difficile.
L’exemple suivant représente une stack trace minifiée :
En revanche, une trace de pile non minifiée vous fournit tout le contexte nécessaire pour un dépannage rapide et sans heurts. Pour les cadres de pile qui se rapportent à votre code source, Datadog génère également un lien direct vers votre dépôt :
Lectures complémentaires
Documentation, liens et articles supplémentaires utiles:
