SentryにSourceMapを連携してエラー画面で元のコードを見れるようにした時の方法、理解しておくべき内容やはまった点などをメモします。
話の流れとして、まずは全体の仕組みに関わるような話をして、具体的な設定方法は後半に記載します。
SourceMapとは
Webpackなどを利用してTypeScriptなどのコードをbuildする(transpile、bundle、minifyと呼んだりもする。)と、build対象のコードをまとめたjsファイルが作成される。
このbuild後のファイルの中身は元のコードと全く異なり、
エラーが発生した際に調査がしずらい(というか無理)。
Sentryへ送信されるコードの情報も基本的にはbuild後のコードの内容なので、調査の役に立たない。
そこでSourceMap
を利用する。
SourceMap
とは、buildしたファイルと組み合わせて元のコードを再現できる情報である。
buildしたファイルの中に書かれることもあるし、.map
といった拡張子のファイルが別途作成されその中に格納されることもある。
後者の方が一般的な気もする。
つまりSentryへSourceMap
を連携しておけば、Sentryのエラー画面で元のソースコードの情報も表示させられる。
こうすることでエラーの原因特定や調査が捗る。
※ちなみにSourceMapはSentryに固有のものではないです。
Releaseについて
SentryでSourceMapを利用するにあたって理解しておかなければならないのが、SentryのRelease
という機能だ。
SourceMapはReleaseの利用を前提としている。
(後述するが、積極的にRelease管理を行う必要はない。設定しなくてもSourcrMapを利用すると勝手にRelease管理が始まる)
Releaseの役割は、端的にいうとバージョン管理だ。
例えば開発中のシステムを1.1.0、1.1.1、1.1.2...というようにリリースごとにバージョンを管理しているとする。
リリースのタイミングに合わせて、ソースコード内のSentry.initに持たせるRelease情報を更新していく。
Sentry.init({
dsn: 'https://xxxxxxxx',
environment: 'production',
release: '1.1.0', // ここをリリースに合わせて更新していく
});
こうすることで、Sentryへ送付されるエラー情報のrelease'1.1.0'という情報が付与される。
また、エラーがどのバージョンから発生していたかといった情報も表示してくれる。
Releaseの名前は一意であればなんでもよく、'2023-05-01'とかでもOK。
Releaseの管理についてはもっと色々あるのだが、本筋ではないのでここまでとする。
興味がある方は調べてみてください。
SourceMapとRelease
Sentryでは、SourceMapをRelease単位で管理する。
このSourceMapは'1.1.0'、このSourceMapは'1.1.1'、といった感じ。
Sentryへ送付されるエラー情報に含まれるReleaseが'1.1.0'なら、
'1.1.0'のSourceMapを元にbuild前のコード情報を取得してエラー画面に表示する。
Releaseの自動付与
上記のようにReleaseを手動で指定してももちろん良いのだが、
実は指定しなくても 、build時の環境に合わせてSentryが自動でReleaseを付与してくれる。
特にReleaseにこだわりがなければ指定しないことをお勧めする。
SourceMapの連携方法
SourceMapを連携する方法はいくつかあり、ここではwebpack(SentryWebpackPlugin
)を利用した方法について紹介する。
※他の方法についてはこちらを参照ください。
1: pluginのinstall
npm install --save-dev @sentry/webpack-plugin
yarn add --dev @sentry/webpack-plugin
2: webpack.config.jsへの追記
const SentryWebpackPlugin = require("@sentry/webpack-plugin");
module.exports = {
// ... other config above ...
devtool: "hidden-source-map",
plugins: [
new SentryWebpackPlugin({
org: "アカウント名",
project: "プロジェクト名",
include: "./dist",
authToken: "auth token",
release: "release-version",
}),
],
};
- devtool
- この設定をすることによってSourceMapが作成される
- 設定値は色々種類があるが、production環境でのエラー収集用として推奨されているのは
hidden-source-map
。詳しくはこちら
- org
- アカウント名、組織名
- project
- プロジェクト名
- include
- build後のファイルが配置されているディレクトリを指定
- authToken
- こちらのページで発行する
- release
- Sentry.initで指定したReleaseのバージョンと同じものを指定する。Sentry.initで指定していなければ不要。
ここまで設定してbuildを走らせると、SourceMapがSentryへ連携される。
連携されたかどうかはSourceMap管理ページで確認可能。
管理ページへは、Sentryプロジェクトのトップ画面右上の歯車アイコン > PROCESSING > SourceMapからたどり着ける。
ちなみにこちらのページからReleaseが作成されていることも確認できる。
補足: Releaseではまったこと
SourceMapがうまく反映されないので原因を調べてほしいという依頼を受けて色々調べたのだが、
Releaseの指定の仕方に問題があった。
依頼を受けた時の状況ではReleaseが固定値になっており、
既にその値でのRelease、SourceMapが作成されていた。
ReleaseもSourceMapも上書きされないので、最新のコードが反映されていなかった、という状況だった。
SourceMapは上書きされないという仕様に気付くのに結構時間がかかったので皆さんご注意ください。