Help us learn about your current experience with the documentation. Take the survey.

集成错误跟踪

Tier: Free, Premium, Ultimate
Offering: GitLab.com

本指南提供如何为您的项目设置集成错误跟踪的基本信息，并使用不同语言的示例。

GitLab Observability 提供的错误跟踪基于 Sentry SDK。有关如何在应用程序中使用 Sentry SDK 的更多信息和示例，请参阅 Sentry SDK 文档。

为项目启用错误跟踪

无论您使用哪种编程语言，首先都需要为您的 GitLab 项目启用错误跟踪。本指南使用 GitLab.com 实例。

先决条件：

您必须有一个想要启用错误跟踪的项目。请参阅如何创建项目。

使用 GitLab 作为后端启用错误跟踪：

在左侧边栏，选择 搜索或跳转至 并找到您的项目。
转到 设置 > 监控。
展开 错误跟踪。
对于 启用错误跟踪，选择启用。
对于 错误跟踪后端，选择 GitLab。
选择 保存更改。
复制 数据源名称 (DSN) 字符串。您需要它来配置您的 SDK 实现。

配置用户跟踪

要跟踪受错误影响用户数量：

在检测代码中，确保每个用户都有唯一标识。您可以使用用户 ID、姓名、电子邮件地址或 IP 地址来标识用户。

例如，如果您使用 Python，您可以通过电子邮件标识用户：

sentry_sdk.set_user({ email: "[email protected]" });

有关用户标识的更多信息，请参阅 Sentry 文档。

查看跟踪的错误

当您的应用程序通过 Sentry SDK 将错误发送到错误跟踪 API 后，这些错误在 GitLab UI 中可用。要查看它们：

在左侧边栏，选择 搜索或跳转至 并找到您的项目。
转到 监控 > 错误跟踪 以查看打开的错误列表：
选择一个错误以查看 错误详情 视图：

此页面显示异常的更多详细信息，包括：
- 总发生次数。
- 受影响用户总数。
- 首次出现：日期和提交 ( )。
- 最后出现日期，显示为相对日期。要查看时间戳，请将鼠标悬停在日期上。
- 每小时错误频率的条形图。要查看特定小时内的错误总数，请将鼠标悬停在条形上。
- 堆栈跟踪。

从错误创建问题

如果您想跟踪与错误相关的工作，可以直接从错误创建问题：

从 错误详情 视图中，选择 创建问题。

一个问题被创建。问题描述包含错误堆栈跟踪。

分析错误详情

要查看错误的完整时间戳：

在 错误详情 页面上，将鼠标悬停在 最后出现 日期上。

在以下示例中，错误发生在 11:41 CEST：

过去 24 小时 图表测量此错误每小时发生的次数。通过指向 11 am 条形，对话框显示错误出现了 239 次：

由于用于调用的库 import * as timeago from 'timeago.js'， 最后出现 字段不会在整小时完成之前更新。

发送错误

支持的语言 SDK 和 Sentry 类型

GitLab 错误跟踪支持这些事件类型：

语言	测试的 SDK 客户端和版本	端点	支持的项目类型
Go	`sentry-go/0.20.0`	`store`	`exception`, `message`
Java	`sentry.java:6.18.1`	`envelope`	`exception`, `message`
NodeJS	`sentry.javascript.node:7.38.0`	`envelope`	`exception`, `message`
PHP	`sentry.php/3.18.0`	`store`	`exception`, `message`
Python	`sentry.python/1.21.0`	`envelope`	`exception`, `message`, `session`
Ruby	`sentry.ruby:5.9.0`	`envelope`	`exception`, `message`
Rust	`sentry.rust/0.31.0`	`envelope`	`exception`, `message`, `session`

有关此表的详细版本，请参阅 issue 1737。

另请参阅支持的语言 SDK 的工作示例，展示如何使用该 SDK 捕获异常、事件或消息。有关更多信息，请参阅特定语言的 Sentry SDK 文档。

旋转生成的 DSN

根据 Sentry 保持 DSN 公开是安全的，但这会为恶意用户向 Sentry 发送垃圾事件打开可能性。因此，如果可能，您应该保持 DSN 秘密。这不适用于客户端应用程序，因为 DSN 将被加载并因此存储在用户的设备上。

先决条件：

您需要项目的数字项目 ID。

要轮换 Sentry DSN：

创建一个访问令牌，具有 api 范围。复制此值，因为您在后续步骤中需要它。

使用错误跟踪 API 创建新的 Sentry DSN，将 <your_access_token> 和 <your_project_number> 替换为您的值：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys"

获取可用的客户端密钥（Sentry DSN）。确保您新创建的 Sentry DSN 已就位。使用旧客户端密钥的密钥 ID 运行以下命令，将 <your_access_token> 和 <your_project_number> 替换为您的值：
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.com/api/v4/projects/<your_project_number>/error_tracking/client_keys"
```

删除旧的客户端密钥：

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.com/api/v4/projects/<your_project_number>/error_tracking/client_keys/<key_id>"

调试 SDK 问题

Sentry 支持的大多数语言在初始化过程中都暴露了一个 debug 选项。 debug 选项可以帮助您调试发送错误时的问题。还有其他选项可以在将数据发送到 API 之前输出 JSON。

数据保留

GitLab 对所有错误有 90 天的保留限制。

要留下关于错误跟踪错误或功能的反馈，请在反馈问题中评论或打开新问题。