Linc'well, inc.Publicationへの投稿
🔔

フロントエンドでのSentry活用

Toshihisa Tomatsu
に公開
監視
Sentry
tech

https://qiita.com/advent-calendar/2025/linc-well

はじめに

普段、Webフロントエンドのエラー/パフォーマンス監視としてSentryをよく使っています。

https://sentry.io/

Sentryは、アプリケーションのエラートラッキングやパフォーマンスモニタリングを行えるサービスです。エラーが発生した際、その詳細に加えて環境情報（ブラウザやOSなど）やエラー発生前の操作履歴なども記録してくれます。
リアルタイムでエラー発生の通知を受け取ることが可能なので、本番運用しているアプリケーションが適切に動作しているか、予期せぬエラーが発生していないかを把握するのに役立ちます。

この記事では、私がSentryをフロントエンドプロジェクトで活用する際のポイントをいくつか紹介します。

セットアップ

Sentryのセットアップは非常に簡単で、Sentry.initを呼び出すだけです。フレームワークごとにガイドが用意されてるので、それを元にセットアップします。
おそらくエントリーポイントでセットアップを行うと思いますが、init処理が行われた以降に発生したエラーしか収集されないため、処理の最初に呼び出すようにします。

main.ts
import "./effect"
Sentry.init() // effect内で発生したエラーは検知できない

エラーの検知

セットアップすると、Unhandledなエラーを自動で送信してくれます。明示的にエラーハンドリングした場合は自動では送信されません。もしハンドリングしたエラーをSentryで見たい場合、Sentry.captureMessage()やSentry.captureException()を使って明示的に送信します。

プロダクト開発していく中で、ここはSentryで検知できた方がいいかという観点を常に意識しています。

Releasesを作成する

アプリケーションのデプロイのたびに、Sentryのプロジェクトに紐づく「Release」を作成しています。

Releaseを作成しておくと、以下のようなメリットがあります。

  • どのreleaseからエラーが発生したのか分かるように
  • リリースごとに、新規で発生したIssueが分かるように

Releaseの命名

releaseプロパティの値は任意ですが、以下のような形式を使うことが多いです。

  • Gitのコミットハッシュ: e0a5797564691a5976a13788b992acbeeebexxxx
  • セマンティックバージョニング: my-app@1.10.0

Gitのコミットハッシュの場合、ビルド時の日付を入れておくとSentryのダッシュボードで分かりやすいため、以下のような形式もおすすめです。

RELEASE_VERSION="$(date +%F)_$(git rev-parse HEAD)"

Releaseの作成手順

デプロイ時に自動でReleaseを作成する方法は公式からさまざまな手段が提供されています。
それらを使わずに自前で行う場合はCIなどでsentry-cliを使ってReleaseを作成します。

sentry-cli releases new "$RELEASE_VERSION"
sentry-cli releases finalize "$RELEASE_VERSION"

あとはアプリケーションコードのSentry.initのreleaseプロパティを設定します。その環境で発生したエラーなどが設定したreleaseに紐づきます。

Sentry.init({
  release: "xxxx",
  // ...
});

SourceMapをアップロードする

Releaseの作成時にSourceMapをアップロードすることが重要です。

これをしないとエラー詳細を見る時に難読化された情報しか見られないので、情報がかなり減ってしまいます。SourceMapをアップロードしておくと、どこで発生したのかが分かりやすくなります。

こちらも公式から簡単にセットアップできるプラグインなどが提供されています。それらを使わずに自前で行う場合は前述のsentry-cliを使います。
upload-sourcemapsを実行することでSourceMapをアップロードできます。

sentry-cli sourcemaps upload /path/to/directory

ダッシュボードのプロジェクト設定でSourceMapページを見て適切にアップロードされたか確認できます。

Sentryのダッシュボードを見る

あとは、チームの運用に合わせて、Sentryのダッシュボードでエラーが発生してないかチェックしていきます。
ここからは自分が普段見るポイントを紹介します。

特定のIssueを見る

特定のIssue(エラー)を詳しく調査する際は、以下のような観点で確認します。

  • Tagsで発生している環境の傾向を見る
    • Issueの詳細画面にTagsエリアがあり、そこでブラウザ/OS、リリース、urlなどどのような環境で発生しているか確認できます
    • 特定Tagごとの分析情報が見れるので、例えば特定のブラウザやOSでのみ発生しているか、どのURLで発生している頻度が多いかなどが分かります
  • StackTraceを見る
    • StackTraceを確認します。情報が少ないものもありますが、エラーの発生箇所や条件を特定するのに役立ちます
  • パンくずを見る
    • パンくず（Breadcrumbs）を見て、エラー発生前のログを確認します。APIリクエストやナビゲーションなど、ユーザーの操作履歴が記録されています
    • SentryのSDKでパンくずに情報を増やすAPI（addBreadcrumb）も用意されているため、必要に応じてカスタム情報を追加できます
  • 発生時間帯とユーザー数を見る
    • いつから発生してたのか、どの時間帯に発生してたのか、発生してるユーザーがどれくらいいるかを確認します。
    • Issue内のグラフだと情報が分かりにくいので、「Discover」画面でグラフの表示や一覧表示するのが個人的に使いやすいです

あとは「View More Events」で何個か同じエラーのIssueを開いてみます。同じエラーでも発生状況は異なることがあるため、複数の事例を確認すると良いです。

定期的にエラー発生をチェックする

チームや組織で運用を決めて、定期的にエラー発生をチェックします。
自分は定期的にエラー発生をチェックする際、以下のポイントをみます。

  • 特定のタイミングから増えているエラーがないか見る
    • Issuesページで期間を14d、並び替えを「Last Seen」にして、Trendカラムを14dに切り替える(7dにする時もある)
    • 発生推移のグラフをざっと眺めて、増えてるものがないか確認する
  • 特定のリリースから発生してるエラーがないか見る
    • Explore > Releases > 任意のReleaseを選択 > New Issuesで、そのリリースから新規で発生したエラーを確認する

パフォーマンス監視

ドキュメントだとTracingという機能の中で出てきます。
エラー監視でSentryが導入されてると、そのままパフォーマンス監視も気軽に使い始められて便利です。

自動計測

SDKから提供されているインテグレーションを使って自動計測を簡単に有効化できます。URLごとのWeb Vitalsが見られて、環境ごとで絞り込みなどもできて便利です。

カスタムトレース

他にもSDKから提供されているSentry.startSpanというAPIを使えば、任意の処理を計測できます。

パフォーマンスのチェック

ダッシュボードの Insights > Frontend > Web Vitals でWeb Vitalsの値を定期チェックしています。
ここでは、全体やページごとにp75の数値を見ることができます。

他のパーセンタイルや詳細条件で数値を追いたい場合は Explore > Traces から見ます。

Alertの設定

Sentryでは、様々なAlertを設定できるので、特定条件を満たした場合にSlackに通知するAlertを作っています。

例えば

  • 新規でエラーが発生したら通知
  • 1時間の間にエラーがXX件以上発生したら通知
  • 昨日より発生件数が〇〇%増えたら通知
  • 昨日より発生ユーザーが増えたら通知
  • 特定のパフォーマンス指標がXX以下になったら通知

などなど、様々な条件でAlertを設定できます。

その他やると良いこと

ユーザーIDの設定

Sentry.setUser({ id: userId })でuserIdを設定しておくと、どのユーザーでエラーが発生したかを特定できます。設定しないとIPアドレスでの識別になってしまいます。

Sentry.setUser({ id: userId });

タグの設定

Sentry.setTagで任意の情報を入れておくと、調査の時に便利です。設定しておくと、絞り込みにも使えます。ここで設定した情報はIssueページなどにも表示されます。

例えば、特定の機能を使っているかどうかのbooleanなど、後で分析したい情報をタグ付けしておくと良いです。

Sentry.setTag("xxx_feature_enabled", true);

ノイズになるエラーを除外

beforeSendやignoreErrorsを使って、ノイズになるエラーは送らないようにできます。

Sentry.init({
  beforeSend(event, hint) {
    if (event.exception /* 特定のエラーを除外 */) {
      return null;
    }
    return event;
  },
  ignoreErrors: []
});

チームでのトリアージの例

チームでSentryを活用する際のトリアージの例を紹介します。チームに合わせて運用を考えてください。

  • 定期的なチェック
    • DailyやWeeklyなど決まった頻度で、担当者は最近増加してるエラーがないか、新規のエラーをチェック
  • リリース後のチェック
    • リリース後N時間後にreleaseのNew Issuesをチェック
    • 新しいリリースで新規にエラーが発生していないか確認できます
  • Alertベースの対応
    • Alertを設定して、通知が来たら調査する運用も有効です。重要度の高いエラーに素早く対応できます
  • 担当チームのタグを設定して、チームごとに通知を分ける
    • 担当チームが明確にできる場合、チームを分類するタグを設定しておけば、チームごとに通知を分けることが可能です

まとめ

フロントエンドでSentryを活用する際のポイントを紹介しました。

Sentryはアプリケーションに問題が起きていないかを把握できる重要なツールです。デフォルトでも恩恵を受けられますが、一手間加えると調査や監視が非常にスムーズになります。
今日紹介したポイントを押さえつつ、プロダクトやチームにとって使いやすい形にカスタマイズしていく必要があるなと感じます。

Linc'well, inc.
Linc'well, inc.Publication

医療スタートアップ Linc'well のエンジニアの記事を集めています。

Discussion