sentry-elixir-sdk

所有技能 > SDK 设置 > 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 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 日志 — 将结构化日志转发到 Sentry Logs Protocol（sentry v12.0.0+）

建议逻辑：

功能	建议条件
错误监控	始终启用 — 不可妥协的基础配置
日志记录	始终启用 — LoggerHandler 会捕获未通过显式 capture_exception 调用捕获的崩溃
追踪	检测到 Phoenix、Plug、Ecto 或 OpenTelemetry 导入时
Crons	检测到 Oban、Quantum 或周期性 GenServer/Task 模式时
Sentry 日志	使用 sentry v12.0.0+ 且需要搜索结构化日志时

建议：“我建议设置错误监控 + 日志记录［如果检测到 Phoenix/Ecto，则添加追踪］。还需要我添加 Crons 或 Sentry 日志吗？”

---

阶段 3：引导设置

选项 1：Igniter 安装程序（推荐）

你需要自行运行此命令 — Igniter 安装程序需要交互式终端输入，Agent 无法处理。请复制并粘贴到终端中：

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

针对每项已确认的功能

逐项检查功能。加载每项功能对应的参考文件，按其中步骤操作，并在继续下一项之前进行验证：

功能	参考文件	在以下情况下加载……
错误监控	${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 或周期性任务

对于每项功能：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 Protocol（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 请求数据相同的清理规则，自动清理敏感数据。使用 :scrubber 配置自定义要保留的 Plug.Conn.private 键。

环境变量

变量	映射到	用途
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. 设置 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"'

如果存在尚未配置 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 集成未上报定时任务	需要 Oban v2.17.6+ 或 Oban Pro；定时任务的作业元数据中必须包含 "cron" => true
Cowboy/Bandit 崩溃产生重复事件	在 LoggerHandler 配置中设置 excluded_domains: [:cowboy, :bandit]（从 v13.1.0 起，两者默认均已排除）
finch 未启动	确保依赖中包含 {:finch, "~> 0.21"}；自 v12.0.0 起，Finch 是默认 HTTP 客户端
JSON 编码错误	对于 Elixir < 1.18，添加 {:jason, "~> 1.4"} 并设置 json_library: Jason