All Skills > SDK Setup > Elixir SDK

Sentry Elixir SDK

Elixir プロジェクトをスキャンして、Sentry の完全なセットアップをガイドする意見付きウィザード。

このスキルを使用する場合

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

注記: 以下の SDK バージョンと API は、本稿作成時点の Sentry ドキュメント（sentry v12.0.2、Elixir ~> 1.13 が必要）を反映しています。 実装前に docs.sentry.io/platforms/elixir/ に対して必ず確認してください。

---

フェーズ 1: 検出

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

# 既存の Sentry 依存関係をチェック
grep -i sentry mix.exs 2>/dev/null

# Elixir バージョンを検出
cat .tool-versions 2>/dev/null | grep elixir
grep "elixir:" mix.exs 2>/dev/null

# Phoenix または Plug を検出
grep -E '"phoenix"|"plug"' mix.exs 2>/dev/null

# Phoenix LiveView を検出
grep "phoenix_live_view" mix.exs 2>/dev/null

# Oban（ジョブキュー / クーロン）を検出
grep "oban" mix.exs 2>/dev/null

# Quantum（クーロン スケジューラー）を検出
grep "quantum" mix.exs 2>/dev/null

# OpenTelemetry の使用状況を検出
grep "opentelemetry" mix.exs 2>/dev/null

# コンパニオン フロントエンドをチェック
ls assets/ frontend/ web/ client/ 2>/dev/null

注意すべきポイント：

シグナル	影響
sentry が mix.exs に既に存在する？	インストールをスキップ。フェーズ 2（機能の設定）に進む
Phoenix が検出された？	Sentry.PlugCapture、Sentry.PlugContext、オプションで Sentry.LiveViewHook を追加
LiveView が検出された？	my_app_web.ex の live_view マクロに Sentry.LiveViewHook を追加
Oban が検出された？	Oban 統合経由のクーロン + エラー キャプチャを推奨
Quantum が検出された？	Quantum 統合経由のクーロンを推奨
OpenTelemetry が既に存在？	トレース セットアップは Sentry.OpenTelemetry.* 設定のみが必要
フロントエンド ディレクトリが見つかった？	フェーズ 4 のクロスリンク提案をトリガー

---

フェーズ 2: 推奨

見つかった内容に基づいて、具体的な推奨事項を提示します。開かれた質問をしないでください。提案を主導してください：

推奨（コア カバレッジ）：

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

オプション（強化された可観測性）：

• ⚡ クーロン — スケジュール済みジョブ内の無音エラーを検出（Oban、Quantum、または手動 GenServer）
• ⚡ Sentry ログ — 構造化ログを Sentry ログ プロトコルに転送（sentry v12.0.0 以降）

推奨ロジック：

機能	推奨する場合
エラー監視	常に — 交渉の余地のないベースライン
ログ	常に — LoggerHandler は明示的な capture_exception 呼び出しではないクラッシュをキャプチャ
トレース	Phoenix、Plug、Ecto、または OpenTelemetry インポートが検出された場合
クーロン	Oban、Quantum、またはペリオディック GenServer/Task パターンが検出された場合
Sentry ログ	sentry v12.0.0 以降が使用中で、構造化ログ検索が必要な場合

提案：「エラー監視 + ログ [+ Phoenix/Ecto が検出された場合はトレース] のセットアップをお勧めします。クーロンまたは Sentry ログも追加しましょうか？」

---

フェーズ 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 を自動で設定します。

終了したら、戻ってきて Verification にスキップしてください。

ユーザーが Igniter インストーラーをスキップした場合は、以下のオプション 2（手動セットアップ）に進みます。

---

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

インストール

mix.exs 依存関係に追加：

# mix.exs
defp deps do
  [
    {:sentry, "~> 12.0"},
    {:finch, "~> 0.21"}
    # Elixir < 1.18 の場合、jason を追加：
    # {: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 と release に推奨）：

# 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 ハンドラー設定 — クラッシュ レポートをキャプチャ
  logger: [
    {:handler, :sentry_handler, Sentry.LoggerHandler, %{
      config: %{
        metadata: [:request_id],
        capture_log_messages: true,
        level: :error
      }
    }}
  ]

Logger ハンドラーを有効化

Application.start/2 で Logger.add_handlers/1 を追加：

# lib/my_app/application.ex
def start(_type, _args) do
  Logger.add_handlers(:my_app)   # 上で設定した :sentry_handler を有効化

  children = [
    MyAppWeb.Endpoint
    # ... その他の子プロセス
  ]

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

Phoenix 統合

lib/my_app_web/endpoint.ex

defmodule MyAppWeb.Endpoint do
  use Sentry.PlugCapture          # use Phoenix.Endpoint の ABOVE に追加（Cowboy アダプターのみ）
  use Phoenix.Endpoint, otp_app: :my_app

  # ...

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

  plug Sentry.PlugContext          # Plug.Parsers の BELOW に追加
  # ...
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   # mount/handle_event/handle_info のエラーをキャプチャ
  end
end

Plain Plug アプリケーション

defmodule MyApp.Router do
  use Plug.Router
  use Sentry.PlugCapture          # Cowboy のみ

  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 ログ セットアップ時
クーロン	${SKILL_ROOT}/references/crons.md	Oban、Quantum、またはペリオディック ジョブが検出された場合

各機能について：${SKILL_ROOT}/references/<機能>.md を読み、手順に正確に従い、動作を検証します。

---

設定リファレンス

主要な設定オプション

オプション	タイプ	デフォルト	目的
:dsn	string | nil	nil	nil の場合 SDK は無効。環境変数：SENTRY_DSN
:environment_name	atom | string	"production"	例：:prod。環境変数：SENTRY_ENVIRONMENT
:release	string | nil	nil	例："my-app@1.0.0"。環境変数：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]	[]	スタック トレースで「in-app」とみなされる 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	プロセスごとの最大パンくずリスト
: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 ログ プロトコルを有効化（v12.0.0 以降）
:test_mode	boolean	false	イベントをメモリ内キャプチャしてテスト

環境変数

変数	マップ先	目的
SENTRY_DSN	:dsn	Data Source Name
SENTRY_RELEASE	:release	アプリ バージョン（例：my-app@1.0.0）
SENTRY_ENVIRONMENT	:environment_name	デプロイ環境

---

Verification

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

# プロジェクトからテスト イベントを送信
MIX_ENV=dev mix sentry.send_test_event

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

# 一時的なテスト — 確認後に削除
def index(conn, _params) do
  Sentry.capture_message("Sentry Elixir SDK test event")
  text(conn, "sent")
end

数秒以内に Sentry ダッシュボードをチェックします。何も表示されない場合：

1. config :sentry, log_level: :debug を設定して詳細な SDK 出力を表示
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"'

設定されていないフロントエンド ディレクトリが存在する場合、一致するスキルを提案：

フロントエンド検出	スキル提案
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 統合がクーロンを報告しない	Oban v2.17.6 以降または Oban Pro が必須。クーロン ジョブは ジョブ メタに "cron" => true が必須
Cowboy クラッシュからの重複イベント	LoggerHandler 設定で excluded_domains: [:cowboy] を設定（これはデフォルト）
finch が起動しない	deps に {:finch, "~> 0.21"} があることを確認。Finch は v12.0.0 以降のデフォルト HTTP クライアント
JSON エンコード エラー	Elixir < 1.18 の場合、{:jason, "~> 1.4"} を追加して json_library: Jason を設定