Article by: Sigrid Huemer（読了時間：6分）
本記事とコード例はJavaScript SDKを対象としています。別のプラットフォームをお使いの場合でも、今回の変更の背景や今後の展開を理解するために、ぜひご一読ください。
Sentry では、真偽値（boolean）の sendDefaultPii を、dataCollection という新しいオプションに置き換えます。従来のスイッチはオンにすればすべて取得、オフにすればごく一部しか取得できない、オールオアナッシングの仕組みでした。cookie は除いて request header だけがほしい、あるいはユーザーのメールアドレスまで送らずに GenAI の入力だけがほしい。そんな場面に出くわしたことがあれば、この仕組みの物足りなさはおわかりでしょう。dataCollection はこの1つのスイッチをいわばコントロールパネルに近いものへと変えます。データのカテゴリごとに、上げる・下げる・絞り込むといった調整ができるダイヤルになるのです。
変わる内容とその時期
dataCollection はすべての Sentry SDK に導入されます。JavaScript SDK では 10.57.0 から利用できるため、すでにこのオプションを見かけた方もいるかもしれません。dataCollection が新しいデフォルトのオプションとなり、sendDefaultPii が完全に廃止されるのは、バージョン11のリリースです。考え方はどのプラットフォームでも共通ですが、具体的なデフォルト値や移行手順は異なる場合があり、SDK ごとの詳細はそれぞれのリリースノートで説明されます。
v11 の JavaScript SDK にとって、これは単なる名称変更ではなく、挙動の変更です。新しいデフォルトは、従来よりも多くのデータを収集します。sendDefaultPii はすでに非推奨となっており、v11 で削除されます。他の Sentry SDK もそれぞれのタイミングで廃止していく予定であり、最終的な行き先はいずれも dataCollection です。
PII とセンシティブデータ
SDK は2種類のデータをそれぞれ異なる方法で扱います。PII（個人を特定できる情報、Personally Identifiable Information）とは、ユーザー ID、メールアドレス、ユーザー名、氏名など、個人に結びつくあらゆる情報を指します。センシティブデータとは、パスワード、トークン、API キーといった認証情報や秘密情報のことです。
dataCollection では、PII はデフォルトで収集されます。 ユーザーの識別情報は、原因のわかりにくいエラーを一目瞭然にしてくれることが少なくありません。特定のカテゴリを収集したくない場合は、userInfo: false のように1行加えるだけでオプトアウトできます。
dataCollection が制御するのは、SDK が自動的に収集するデータだけです。手動で付与したデータは、これまで通り送信されます。Sentry.setUser(...) を呼び出したうえで dataCollection: { userInfo: false } を設定した場合でも、そのユーザーデータは送信されます。明示的に設定したものだからです。
センシティブデータが自動的に収集されることは決してありません。 これは従来から変わりません。たとえば、SDK がデフォルトで収集する HTTP header を考えてみましょう。header 名はすべて送られますが、キーが組み込みの denylist（auth、token、password、secret など）に一致する値は、イベントがアプリを離れる前に [Filtered] に置き換えられます。認証情報の値は伏せられたまま、header 名だけを取得できるわけです。
デフォルト値の変更点（JavaScript SDK v11）
v11 のデフォルトは、v10 よりも許容範囲が広くなっています。これを本番環境で気づくのではなく、この場で知っておいていただきたいのです。従来は sendDefaultPii を未設定にすると制限的なベースラインが適用されていましたが、v11 では dataCollection を未設定にすると、いくつかのカテゴリがデフォルトで収集されます。手動で設定しなくても問題の把握に役立つカテゴリです。
| カテゴリ | v10 デフォルト（sendDefaultPii オフ） |
v11 デフォルト |
|---|---|---|
userInfo |
false |
true |
cookies |
収集しない | true |
httpHeaders |
request + response（PII をスクラブ） | request + response |
httpBodies |
収集しない（サイズのみ） | request/response すべて（切り詰めあり） |
urlQueryParams |
true |
true |
genAI |
入力・出力とも収集しない | 入力・出力 |
databaseQueryData |
false |
true |
stackFrameVariables |
true |
true |
frameContextLines |
7 |
5（他の SDK と同じデフォルト） |
HTTPのリクエストデータ、データベースクエリ、GenAIの入力・出力を収集したくない場合は、アップグレードする前にこの表をよく確認してください。特に注意すべきなのは、リクエストボディとレスポンスボディです。センシティブな値が含まれやすいのが、この部分だからです。
dataCollection の設定、2つのパターン
v11 へアップグレードする方の多くは、次の2つのいずれかに当てはまります。ご自身の移行パターンを確認してください。
1. これまで sendDefaultPii: true だった場合
すでに sendDefaultPii: true で運用していた場合、v11 のデフォルトはこれまでと同じ挙動になります。そのため移行作業は、このオプションを削除するだけです。
2. これまで sendDefaultPii: false（または未設定）だった場合
v10 の「ゼロコンフィグ」は、sendDefaultPii: false と同じ挙動でした。v11 では収集する範囲が広がります。
v10 の制限的な挙動を維持したい場合は、対応が必要なのがこのケースです。dataCollection を未設定のままにすると、より広い範囲の収集が有効になります。そのため、従来の sendDefaultPii: false と同じ挙動にするには、オプションを明示的に設定してください。
必要なものだけを細やかに
dataCollection のデフォルト設定は手軽ですが、細かく設定できるため、ニーズに合わせて調整できます。cookies、urlQueryParams、httpHeaders.request、 httpHeaders.response のキーと値のフィールドは、単純なオン・オフだけを受け付けるわけではありません。true、false、allow リスト、deny リストを指定できます。
実際にデバッグで使う header は残し、保存したくない値を含む header は deny します。必要な query param だけを allow し、残りは除外します。役立つものは収集し、リスクのあるものは除き、アプリに合わせて自由に線引きしてください。
dataCollection がカバーしないデータをフィルタリングする
dataCollection が扱うのは、SDK が自動的に収集するカテゴリです。（手動で付与したデータは常に送信されます。前述の「PII とセンシティブデータ」を参照してください。）これらのカテゴリの外にある特定のデータを伏せたり除外したりする必要がある場合は、これまで通りイベントと span のフックが使えます。
エラーイベントについては、beforeSend が送信前に実行されます。そのためPII を手動で取り除いたり、null を返してイベントごと破棄したりする処理は、引き続きここで行えます。この点は v11 でも変わりません。
バージョン11では、span のストリーミングモードもデフォルトで有効になります。最後に span を1つの transaction にまとめるのではなく、SDK は span が完了するたびにバッチで送信します。span のデータを変更したり伏せたりするには、beforeSendSpan を使用します。
beforeSendSpan は span を変更できるだけで、破棄はできません。v11 のストリームモードで span を破棄するには、従来の beforeSendTransaction や ignoreTransactions ではなく、ignoreSpans を使用します。ストリーミングを始めると、前者の2つはどちらも利用できなくなります。
大まかなカテゴリは dataCollection で制御し、細かな部分は beforeSend などのフックで対応する。こうして、データがアプリを離れる前に、送信する内容を思いどおりに整えられます。
アップグレードの前に
デフォルト値の表を読み、新しいベースラインが自分に合っているか、それとも何かを控えめにしたいかを判断してください。データスクラビングの設定も確認しましょう。リクエストボディとレスポンスボディが最優先です。v11 ではストリームモードがデフォルトで有効になるため、span のフィルターもあわせて確認してください。beforeSendTransaction で span を破棄している場合は、ignoreSpans に移してください。v10 の設定から Sentry.withStreamedSpan() のラッパーが残っている場合は、外してください。それ以外は、あとからダイヤルを1つずつ調整していけば大丈夫です。
JavaScript SDK 以外をお使いの場合は、ご自身の SDK のリリースノートに注目しておいてください。dataCollection はそちらにも、プラットフォーム向けの移行ガイドとともに近く届きます。JavaScript SDK のオプションの全一覧は dataCollection のドキュメントに、その設計思想は SDK data-collection スペックにまとめられています。このコントロールパネルは、これまでのスイッチよりもずっと使い心地がよいはずです。
Original Page: From one switch to a control panel: meet `dataCollection`
IchizokuはSentryと提携し、日本でSentry製品の導入支援、テクニカルサポート、ベストプラクティスの共有を行なっています。Ichizokuが提供するSentryの日本語サイトについてはこちらをご覧ください。またご導入についての相談は「お問い合わせ」からお気軽にお問い合わせください。
