sentry-elixir-sdk

すべてのスキル > SDK のセットアップ > Elixir SDK

Sentry Elixir SDK

Elixir プロジェクトをスキャンし、Sentry の完全なセットアップを案内する、推奨構成を備えたウィザードです。

このスキルを使う場面

• ユーザーが Elixir または Phoenix アプリへの「Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが Elixir または Phoenix でのエラー監視、トレース、ロギング、または cron を希望する場合
• ユーザーが sentry hex パッケージ、getsentry/sentry-elixir、または Elixir Sentry SDK に言及した場合
• ユーザーが例外、Plug エラー、LiveView エラー、またはスケジュール済みジョブを監視したい場合

注： 以下の SDK バージョンと API は、執筆時点の Sentry ドキュメント（sentry v13.2.0、Elixir ~> 1.13 が必要）に基づいています。 実装前に必ず docs.sentry.io/platforms/elixir/ で確認してください。

---

フェーズ 1：検出

推奨事項を提示する前に、以下のコマンドを実行してプロジェクトを確認してください。

# Check existing Sentry dependency
grep -i sentry mix.exs 2>/dev/null

# Detect Elixir version
cat .tool-versions 2>/dev/null | grep elixir
grep "elixir:" mix.exs 2>/dev/null

# Detect Phoenix or Plug
grep -E '"phoenix"|"plug"' mix.exs 2>/dev/null

# Detect Phoenix LiveView
grep "phoenix_live_view" mix.exs 2>/dev/null

# Detect Oban (job queue / crons)
grep "oban" mix.exs 2>/dev/null

# Detect Quantum (cron scheduler)
grep "quantum" mix.exs 2>/dev/null

# Detect OpenTelemetry usage
grep "opentelemetry" mix.exs 2>/dev/null

# Check for companion frontend
ls assets/ frontend/ web/ client/ 2>/dev/null

確認する項目：

シグナル	影響
mix.exs に sentry がすでにありますか？	インストールを省略し、フェーズ 2（機能の設定）に進みます
Phoenix が検出されましたか？	Sentry.PlugCapture、Sentry.PlugContext、必要に応じて Sentry.LiveViewHook を追加します
LiveView が検出されましたか？	my_app_web.ex の live_view マクロに Sentry.LiveViewHook を追加します
Oban が検出されましたか？	Oban 統合による Crons とエラー取得を推奨します
Quantum が検出されましたか？	Quantum 統合による Crons を推奨します
OpenTelemetry がすでに存在しますか？	トレースのセットアップには Sentry.OpenTelemetry.* の設定だけが必要です
フロントエンドのディレクトリが見つかりましたか？	フェーズ 4 で相互リンクの提案を行います

---

フェーズ 2：推奨

確認結果に基づいて、具体的な推奨事項を提示してください。自由回答形式の質問はせず、まず提案してください。

推奨（基本的なカバレッジ）：

• ✅ エラー監視 — 常に推奨します。例外とクラッシュレポートを取得します
• ✅ ロギング — Sentry.LoggerHandler がクラッシュレポートとエラーログを Sentry に転送します
• ✅ トレース — Phoenix、Plug、または Ecto が検出された場合に推奨します（OpenTelemetry 経由）

任意（オブザーバビリティの強化）：

• ⚡ Crons — スケジュール済みジョブでのサイレント障害を検出します（Oban、Quantum、または手動の GenServer）
• ⚡ Sentry Logs — 構造化ログを Sentry Logs Protocol に転送します（sentry v12.0.0 以降）

推奨ロジック：

機能	推奨する条件...
エラー監視	常に — 必須の基本機能です
ロギング	常に — LoggerHandler は、明示的な capture_exception 呼び出しがないクラッシュも取得します
トレース	Phoenix、Plug、Ecto、または OpenTelemetry のインポートが検出された場合
Crons	Oban、Quantum、または定期的な GenServer／Task のパターンが検出された場合
Sentry Logs	sentry v12.0.0 以降を使用していて、構造化ログの検索が必要な場合

次のように提案します。「エラー監視とロギング［Phoenix／Ecto が検出された場合はトレースも］のセットアップをおすすめします。Crons または Sentry Logs も追加しましょうか？」

---

フェーズ 3：案内

オプション 1：Igniter インストーラー（推奨）

これはご自身で実行する必要があります — Igniter インストーラーは、エージェントでは対応できない対話型ターミナル入力を必要とします。以下をコピーしてターミナルに貼り付けてください。

mix igniter.install sentry

sentry v11.0.0 以降で利用できます。config/config.exs、config/prod.exs、config/runtime.exs、および lib/my_app/application.ex を自動的に設定します。

完了したら、戻って検証に進んでください。

ユーザーが Igniter インストーラーをスキップする場合は、以下のオプション 2（手動セットアップ）に進んでください。

---

オプション 2：手動セットアップ

インストール

mix.exs の依存関係に追加します。

# mix.exs
defp deps do
  [
    {:sentry, "~> 13.0"},
    {:finch, "~> 0.21"}
    # Add jason if using Elixir < 1.18:
    # {:jason, "~> 1.4"},
  ]
end

mix deps.get

設定

# config/config.exs
config :sentry,
  dsn: System.get_env("SENTRY_DSN"),
  environment_name: config_env(),
  enable_source_code_context: true,
  root_source_code_paths: [File.cwd!()],
  in_app_otp_apps: [:my_app]

実行時設定の場合（DSN とリリースで推奨）：

# config/runtime.exs
import Config

config :sentry,
  dsn: System.fetch_env!("SENTRY_DSN"),
  release: System.get_env("SENTRY_RELEASE", "my-app@#{Application.spec(:my_app, :vsn)}")

クイックスタート — 推奨する初期化設定

この設定では、適切なデフォルト値で最も多くの機能を有効にします。

# config/config.exs
config :sentry,
  dsn: System.get_env("SENTRY_DSN"),
  environment_name: config_env(),
  enable_source_code_context: true,
  root_source_code_paths: [File.cwd!()],
  in_app_otp_apps: [:my_app],
  # Logger handler config — captures crash reports
  logger: [
    {:handler, :sentry_handler, Sentry.LoggerHandler, %{
      config: %{
        metadata: [:request_id],
        capture_log_messages: true,
        level: :error
      }
    }}
  ]

ロガーハンドラーを有効化

Application.start/2 に Logger.add_handlers/1 を追加します。

# lib/my_app/application.ex
def start(_type, _args) do
  Logger.add_handlers(:my_app)   # activates the :sentry_handler configured above

  children = [
    MyAppWeb.Endpoint
    # ... other children
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

Phoenix との統合

lib/my_app_web/endpoint.ex

defmodule MyAppWeb.Endpoint do
  use Sentry.PlugCapture          # Add ABOVE use Phoenix.Endpoint (Cowboy adapter only)
  use Phoenix.Endpoint, otp_app: :my_app

  # ...

  plug Plug.Parsers,
    parsers: [:urlencoded, :multipart, :json],
    pass: ["*/*"],
    json_decoder: Phoenix.json_library()

  plug Sentry.PlugContext          # Add BELOW Plug.Parsers
  # ...
end

注記： Sentry.PlugCapture が必要なのは Cowboy アダプターの場合のみです。Phoenix 1.7 以降ではデフォルトが Bandit であり、この場合 PlugCapture は無害ですが不要です。Sentry.PlugContext は常に推奨されます。HTTP リクエストデータでイベントを拡充できます。

LiveView のエラー — lib/my_app_web.ex

def live_view do
  quote do
    use Phoenix.LiveView

    on_mount Sentry.LiveViewHook   # captures errors in mount/handle_event/handle_info
  end
end

通常の Plug アプリケーション

defmodule MyApp.Router do
  use Plug.Router
  use Sentry.PlugCapture          # Cowboy only

  plug Plug.Parsers, parsers: [:urlencoded, :multipart]
  plug Sentry.PlugContext
  # ...
end

合意した各機能について

機能を1つずつ確認します。それぞれのリファレンスファイルを読み込み、手順に従い、次の機能に進む前に検証してください。

機能	リファレンスファイル	読み込むタイミング
エラー監視	${SKILL_ROOT}/references/error-monitoring.md	常に（基本）
トレース	${SKILL_ROOT}/references/tracing.md	Phoenix／Ecto／OpenTelemetry が検出された場合
ロギング	${SKILL_ROOT}/references/logging.md	LoggerHandler または Sentry Logs のセットアップ時
Cron	${SKILL_ROOT}/references/crons.md	Oban、Quantum、または定期ジョブが検出された場合

機能ごとに、Read ${SKILL_ROOT}/references/<feature>.md を実行し、手順に正確に従って、動作を検証してください。

---

設定リファレンス

主な設定オプション

オプション	型	デフォルト	用途
:dsn	string | nil	nil	nil の場合、SDK は無効になります。環境変数：SENTRY_DSN
:environment_name	atom | string	"production"	例：:prod。環境変数：SENTRY_ENVIRONMENT
:release	string | nil	nil	例："[email protected]"。環境変数：SENTRY_RELEASE
:sample_rate	float	1.0	エラーイベントのサンプルレート（0.0～1.0）
:enable_source_code_context	boolean	false	エラー箇所の前後のソースコード行を含めます
:root_source_code_paths	[path]	[]	ソースコンテキストを有効にする場合に必要です
:in_app_otp_apps	[atom]	[]	スタックトレースでモジュールを「アプリ内」として扱う OTP アプリ
:before_send	(event -> event | nil) | {m, f}	nil	エラーイベントを変更または破棄するフック
:after_send_event	(event, result -> any) | {m, f}	nil	イベント送信後に呼び出されるフック
:filter	module	Sentry.DefaultEventFilter	Sentry.EventFilter を実装するモジュール
:max_breadcrumbs	integer	100	プロセスあたりのパンくずリストの最大数
:max_stacktrace_arg_length	integer	10000	スタックトレース変数内の各関数引数について、検査する文字数の最大値（v13.2.0 以降）
:dedup_events	boolean	true	約30秒以内に発生した同一イベントを重複排除します
:tags	map	%{}	すべてのイベントとともに送信されるグローバルタグ
:traces_sample_rate	float | nil	nil	nil 以外にするとトレースが有効になります（OTel のセットアップが必要）
:traces_sampler	fn | {m, f} | nil	nil	トランザクションごとのカスタムサンプリング
:enable_logs	boolean	false	Sentry Logs プロトコルを有効にします（v12.0.0 以降）
:scrubber	keyword	[]	スクラバーの設定（v13.1.1 以降）。キー：:conn_private_allow_list（Plug.Conn.private から保持するアトムのリスト）
:test_mode	boolean	false	テスト用にイベントをメモリ内でキャプチャします

デフォルトの PII に関するガイダンス

ほとんどの Sentry SDK には、デフォルトで PII を送信するオプションがあります。sentry v12 の時点では、Elixir SDK は、ドキュメントに記載されたオプション一覧にも現在の設定スキーマにも send_default_pii 設定オプションを公開していないため、存在しないオプションを追加しないでください。ユーザーコンテキストを拡充するには、Sentry.PlugContext を使用して Sentry.Context.set_user_context/1 で許可するフィールドを明示的に設定し、必要に応じて :before_send でスクラブしてください。将来の Elixir SDK リリースで send_default_pii が追加された場合は、その設定を推奨してください。

PII の自動スクラブ： v13.1.0 の時点では、スタックトレースのフレーム変数と FunctionClauseError／Phoenix.ActionClauseError の引数は、HTTP リクエストデータと同じスクラブルールを使用して、機密データが自動的にスクラブされます。保持する Plug.Conn.private キーをカスタマイズするには、:scrubber 設定を使用してください。

環境変数

変数	マッピング先	用途
SENTRY_DSN	:dsn	データソース名
SENTRY_RELEASE	:release	アプリのバージョン（例：[email protected]）
SENTRY_ENVIRONMENT	:environment_name	デプロイ環境

---

検証

Sentry がイベントを受信していることをテストします：

# Send a test event from your project
MIX_ENV=dev mix sentry.send_test_event

または、コントローラーのアクションに一時的な呼び出しを追加します：

# Temporary test — remove after confirming
def index(conn, _params) do
  Sentry.capture_message("Sentry Elixir SDK test event")
  text(conn, "sent")
end

数秒以内に Sentry ダッシュボードを確認してください。何も表示されない場合：

1. 詳細な SDK 出力を有効にするため、config :sentry, log_level: :debug を設定します
2. SENTRY_DSN が設定されており、プロジェクトが存在することを確認します
3. :environment_name が、Sentry のアラートルールでフィルターされる値に設定されていないことを確認します

---

フェーズ 4：相互リンク

Elixir のセットアップが完了したら、Sentry の適用範囲が不足している関連フロントエンドがないか確認します：

ls assets/ frontend/ web/ client/ ui/ 2>/dev/null
cat assets/package.json frontend/package.json 2>/dev/null | grep -E '"react"|"svelte"|"vue"|"next"'

Sentry が設定されていないフロントエンドのディレクトリがある場合は、対応するスキルを提案します：

検出されたフロントエンド	提案するスキル
React / Next.js	sentry-react-sdk または sentry-nextjs-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue	docs.sentry.io/platforms/javascript/guides/vue/ を参照
その他の JS/TS	sentry-browser-sdk

Phoenix バックエンドと JavaScript フロントエンドを、リンクされた Sentry プロジェクトで接続すると、分散トレーシングが可能になります。これにより、ブラウザー、Phoenix HTTP サーバー、下流サービスにまたがるスタックトレースを、単一のトレースビューで確認できます。

---

トラブルシューティング

問題	解決策
イベントが表示されない	SENTRY_DSN が設定されていることを確認します。mix sentry.send_test_event を実行し、log_level: :debug を設定します
キャプチャされた例外にスタックトレースがない	rescue ブロックで stacktrace: __STACKTRACE__ を渡します：Sentry.capture_exception(e, stacktrace: __STACKTRACE__)
PlugCapture が Bandit で動作しない	Sentry.PlugCapture は Cowboy 専用です。Bandit では、エラーは LoggerHandler 経由で表面化します
本番環境でソースコードのコンテキストがない	OTP リリースをビルドする前に mix sentry.package_source_code を実行します
非同期イベントにコンテキストが表示されない	Sentry.Context.* はプロセス単位です。値を明示的に渡すか、Logger のメタデータをプロセス間で伝播させます
Oban 統合で cron が報告されない	Oban v2.17.6+ または Oban Pro が必要です。cron ジョブでは、ジョブのメタデータに "cron" => true を設定する必要があります
Cowboy/Bandit のクラッシュによる重複イベント	LoggerHandler の設定で excluded_domains: [:cowboy, :bandit] を設定します（v13.1.0 以降、どちらもデフォルトで除外されています）
finch が起動しない	deps に {:finch, "~> 0.21"} が含まれていることを確認します。v12.0.0 以降、Finch がデフォルトの HTTP クライアントです
JSON エンコードエラー	{:jason, "~> 1.4"} を追加し、Elixir < 1.18 では json_library: Jason を設定します