getsentry/sentry-elixir - 项目详情

项目介绍快速开始学习路径项目截图 1 贡献者 124 增长趋势代码统计生态关系项目时间线项目竞品依赖分析上榜历史

学习路径指南

难度等级

初级

预计时长

2-3小时

适合人群

已掌握Elixir基础语法，正在开发或维护Elixir应用（尤其是Web应用），希望为应用添加错误监控和性能追踪功能的开发者。

学习目标：学会在Elixir应用中集成Sentry SDK，实现自动捕获运行时异常、手动上报错误与消息，并能在Sentry平台上查看和分析错误报告。

前置知识

Elixir基础熟悉

需要了解Elixir的基本语法、模块、函数以及Mix项目管理工具（mix.exs文件的作用），因为集成SDK需要在Mix项目中添加依赖和配置。

Sentry账户与项目了解

需要一个Sentry.io的账户，并已在其中创建一个项目以获取DSN（数据源名称），这是SDK将错误报告发送到正确目的地的关键配置。

HTTP客户端与JSON库（基础概念）了解 (可选)

Sentry SDK需要通过网络发送数据，并序列化/反序列化JSON。虽然SDK有默认选择（Finch和内置JSON），但了解这些组件的作用有助于理解配置选项。

学习步骤

环境与项目准备

30分钟

创建或定位你的Elixir项目

确保你有一个可以用于测试的Elixir项目（例如一个Phoenix Web应用或一个简单的Mix项目）。如果还没有，可以使用 `mix new my_app` 快速创建一个。

建议在一个非核心的测试项目或开发环境中先进行集成尝试。

获取Sentry DSN

登录Sentry.io，创建一个新项目（选择Elixir作为平台），或在已有项目中找到“设置 -> 客户端密钥(DSN)”。复制你的DSN，它看起来像 `https://xxx@sentry.io/xxx`。

DSN是敏感信息，切勿提交到公共代码仓库。后续我们会将其放入环境变量。

安装与基础配置

45分钟

添加Sentry依赖

在你的项目根目录下的 `mix.exs` 文件的 `deps` 函数中，添加 `{:sentry, "~> 10.0"}`。根据README提示，如果你的Elixir版本低于1.18，还需要额外添加 `{:jason, "~> 1.1"}` 作为JSON库。

添加依赖后，记得在项目根目录运行 `mix deps.get` 来下载安装。

配置Sentry DSN和环境

在 `config/config.exs` 或环境特定的配置文件（如 `config/prod.exs`）中，添加基础配置。至少需要设置 `:dsn` 和 `:environment_name`。强烈建议将DSN存储在环境变量中（如 `System.get_env("SENTRY_DSN")`）。

`:environment_name` 通常设置为 `:dev`, `:test`, `:prod`，这有助于在Sentry平台区分不同环境的错误。

运行配置测试任务

执行 `mix sentry.config_test`。这个Mix任务会模拟发送一个测试事件到Sentry，验证你的DSN和基础配置是否正确。这是确保集成成功的关键一步。

如果测试失败，请仔细检查DSN是否正确、网络是否通畅，以及Sentry项目配置。

核心功能上手

60分钟

启用自动异常捕获（Logger集成）

按照README，在 `config/prod.exs` 中添加 `config :logger, backends: [Sentry.LoggerHandler]`，并在 `application.ex` 的 `start/2` 函数中调用 `Logger.add_handler(Sentry.LoggerHandler, Sentry.LoggerHandler, config)`。这能让SDK自动捕获进程崩溃错误。

在开发环境，你可能不想启用它，以免干扰正常调试。可以仅在生产环境配置中开启。

尝试手动捕获异常

在代码中（例如一个Controller或GenServer中），尝试使用 `Sentry.capture_exception/2`。你可以故意抛出一个错误（如 `raise "Something went wrong"`），然后用 `rescue` 块捕获并调用该函数。

手动捕获适用于你预料到可能出错、但又不想让进程崩溃的关键业务逻辑部分。

尝试记录自定义消息

使用 `Sentry.capture_message/2` 来发送非异常的信息到Sentry，例如记录一个重要的业务状态变更或一个警告。

消息的级别（`:info`, `:warning`, `:error`）可以帮助你在Sentry平台进行分类筛选。

测试与验证

30分钟

在测试中模拟Sentry事件发送

参考README的“Testing with Sentry”部分，学习如何使用Bypass库在你的ExUnit测试中拦截发送到Sentry的HTTP请求，从而验证在特定条件下是否会触发Sentry上报。

测试时务必设置 `config :sentry, send_result: :sync` 以确保事件发送是同步的，避免测试提前结束。使用 `on_exit` 回调来清理测试对全局配置的修改。

在Sentry平台查看结果

触发几次错误（自动或手动），然后回到你的Sentry项目页面。你应该能看到新的事件（Issues）。点击进入查看错误详情、堆栈跟踪、环境、请求信息（如果集成Phoenix/Plug）等。

这是最有成就感的一步！确认你能在Sentry的Web界面看到从你的应用发来的错误报告。

常见错误与避坑指南

将Sentry DSN直接硬编码在配置文件中并提交到Git仓库。

始终通过环境变量（如 `SENTRY_DSN`）来管理DSN。在配置中使用 `System.get_env("SENTRY_DSN")` 读取。

在开发或测试环境配置了DSN，导致本地调试或CI/CD流水线中的测试错误也上报到Sentry，污染生产错误数据。

使用环境变量和Mix环境来区分。通常只在生产环境（`config/prod.exs`）配置真实的DSN。在开发/测试环境，可以将DSN设为nil或使用一个假的端点。

忘记运行 `mix sentry.config_test` 或忽略其错误信息，导致集成后迟迟收不到错误报告。

集成后第一步就是运行此测试任务，并根据其输出修正配置。它是连接你和Sentry服务器的“健康检查”。

在异步测试中修改了Sentry的全局配置（如 `:dsn`, `:environment_name`），导致测试间相互干扰或配置未还原。

遵循README的测试指南：1) 避免在异步测试中修改全局配置。2) 使用 `ExUnit.Callbacks.on_exit/2` 确保测试后配置被还原。

下一步探索

学完基础后可以继续探索的方向：1. 深入阅读官方文档，配置错误采样率、设置发布（Release）跟踪以关联错误与代码版本。2. 集成性能监控（APM）功能，追踪关键事务的耗时。3. 根据你的业务需求，在Sentry.capture_exception/2或capture_message/2调用时添加上下文信息（如用户ID、请求参数），使错误报告更具可读性。4. 探索Sentry的告警（Alerts）和问题分配（Issue Assignment）规则，建立团队的错误响应流程。