sentry-otel-exporter-setup

Sentry OTel Exporter 设置

术语：提及导出器组件时，始终将其写作“Sentry Exporter”。

配置 OpenTelemetry Collector，使用 Sentry Exporter 将链路和日志发送到 Sentry。

设置概览

复制此清单以跟踪进度：

OTel Exporter Setup:
- [ ] Step 1: Check for existing configuration
- [ ] Step 2: Check collector version and install if needed
- [ ] Step 3: Configure project creation settings
- [ ] Step 4: Write collector config
- [ ] Step 5: Add environment variable placeholders
- [ ] Step 6: Run the collector
- [ ] Step 7: Verify setup

第 1 步：检查现有配置

查找包含 receivers: 的 YAML 文件，搜索现有的 OpenTelemetry Collector 配置。还要检查是否存在名为 otel-collector-config.*、collector-config.* 或 otelcol.* 的文件。

如果找到现有配置：询问用户希望采用哪种方式：

• 修改现有配置：将 Sentry Exporter 添加到现有文件中（建议采用此方式，以避免重复）
• 创建单独的配置：保留现有配置不变，并创建一个新配置用于测试

等待用户回答，并在继续第 2 步之前记录其选择。 后续工作流取决于此决定。

如果没有配置：说明将在第 4 步创建新的 collector-config.yaml，然后继续第 2 步。

第 2 步：检查 Collector 版本

Sentry Exporter 要求使用 otelcol-contrib v0.145.0 或更高版本。

检查现有 Collector

1. 运行 which otelcol-contrib，检查它是否位于 PATH 中，或检查项目中是否存在 ./otelcol-contrib
2. 如果找到，运行相应的版本命令并解析版本号
3. 记录 Collector 路径（例如，位于 PATH 中时为 otelcol-contrib，本地文件时为 ./otelcol-contrib），以便在后续步骤中使用

现有版本	操作
≥ 0.145.0	跳到第 3 步——现有 Collector 兼容
< 0.145.0	继续执行以下安装步骤
未安装	继续执行以下安装步骤

安装

询问用户希望如何运行 Collector：

• 二进制文件：从 GitHub releases 下载。无需 Docker。
• Docker：作为容器运行。需要安装 Docker。

二进制文件安装

从 GitHub 获取最新的发布版本：

curl -s https://api.github.com/repos/open-telemetry/opentelemetry-collector-releases/releases/latest | grep '"tag_name"' | cut -d'"' -f4

重要：GitHub API 返回的版本带有 v 前缀（例如，v0.145.0）。下载 URL 路径需要包含带 v 前缀的完整标签，但文件名和 Docker 标签使用不带前缀的数字版本（例如，0.145.0）。

检测用户的平台并下载二进制文件：

1. 运行 uname -s 和 uname -m，检测操作系统和架构
2. 映射为发布版本值：
   • Darwin + arm64 → darwin_arm64
   • Darwin + x86_64 → darwin_amd64
   • Linux + x86_64 → linux_amd64
   • Linux + aarch64 → linux_arm64
3. 下载并解压：

curl -LO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v<numeric_version>/otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz
tar -xzf otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz
chmod +x otelcol-contrib

示例：对于版本 v0.145.0，URL 路径中使用 v0.145.0，文件名中使用 0.145.0。

请为用户执行这些步骤，不要只向他们展示命令。

4. 询问用户是否要删除下载的 tarball 以节省磁盘空间（约 50MB）：
   • 是，删除：移除 tarball
   • 否，保留：保留 tarball

等待用户回复。 只有在用户明确选择删除时才执行：

rm otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz

Docker 安装

1. 运行 docker --version，确认已安装 Docker
2. 从 GitHub 获取最新的发布标签（同上）
3. 使用数字版本（不带 v 前缀）拉取镜像：

docker pull otel/opentelemetry-collector-contrib:<numeric_version>

示例：对于 GitHub 标签 v0.145.0，使用 docker pull otel/opentelemetry-collector-contrib:0.145.0。

创建配置后，将在第 6 步介绍 docker run 命令。

步骤 3：配置 Sentry 项目创建

询问用户是否启用自动创建 Sentry 项目。不要推荐任何一个选项：

• 是：根据 service.name 创建项目。Sentry 组织中至少需要有一个团队。所有新项目都会分配给找到的第一个团队。创建期间可能会丢弃初始数据。
• 否：遥测数据到达之前，项目必须已存在于 Sentry 中。

等待用户回答后再继续步骤 4。

如果用户选择“是”：提醒他们，导出器会扫描所有项目，并使用找到的第一个团队。所有自动创建的项目都会分配给该团队。如果他们还没有任何团队，应先在 Sentry 中创建一个。

步骤 4：编写 Collector 配置

使用步骤 1 中的决定——如果用户选择修改现有配置，就编辑该文件；如果他们选择创建单独的配置，就创建一个新文件。记录配置文件路径，以便在步骤 5 和 6 中使用。

从 Sentry Exporter 文档获取最新配置：

• 示例配置（用作模板）：https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/example-config.yaml
• 完整规范（所有可用选项）：https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/spec.md

使用 WebFetch 获取示例配置作为起始模板。如果用户需要示例中未显示的高级选项，请参考规范。

如果编辑现有配置（根据步骤 1 的决定）

将 sentry 导出器添加到 exporters: 部分，并将其包含在相应的管道（traces、logs）中。除非用户提出要求，否则不要移除或修改其他导出器。

如果创建新配置（根据步骤 1 的决定）

根据获取的示例创建 collector-config.yaml。确保凭据使用环境变量引用（${env:SENTRY_ORG_SLUG}、${env:SENTRY_AUTH_TOKEN}）。

如果用户在步骤 3 中选择自动创建，请将 auto_create_projects: true 添加到 sentry 导出器中。

添加 Debug 导出器（推荐）

为便于设置期间排查问题，将 verbosity: detailed 的 debug 导出器添加到管道中。它会将所有遥测数据记录到控制台。设置验证完成后将其移除。

步骤 5：添加环境变量占位符

Sentry Exporter 需要两个环境变量。你将添加占位值，由用户自行填写实际值——绝不要填写真实凭据。

语言限制：绝不要只说“添加凭据”“添加环境变量”或“添加令牌”，必须明确说明这些是占位符。始终说明用户之后会自行填写。

不要这样说：

• “让我添加环境变量”
• “我会把凭据添加到你的 .env 文件中”
• “正在添加 Sentry 身份验证令牌”

应这样说：

• “我会添加环境变量占位符，供你之后填写”
• “正在添加占位值——你需要用实际凭据替换这些值”
• “我会设置环境变量键，并填入占位值”

使用 glob **/.env 搜索项目中现有的 .env 文件。始终询问用户要使用哪个文件——不要根据上下文推断，也不要根据已打开的文件猜测。

列出找到的选项：

• [找到的 .env 文件路径]：添加到现有文件（逐一列出找到的路径）
• 在根目录新建：在项目根目录创建 .env

等待用户明确选择。 在用户选择之前不要继续。记录环境文件路径，以便在步骤 5（验证）和步骤 6（运行）中使用。

将以下占位值添加到所选文件中：

SENTRY_ORG_SLUG=your-org-slug
SENTRY_AUTH_TOKEN=your-token-here

添加占位符后，告诉用户如何从 Sentry 获取实际值：

1. Sentry 组织标识：在 Sentry 中，前往 Settings → Organization Settings → Organization Slug。这也是你的子域名（例如，https://myorg.sentry.io 中的 myorg）
2. Sentry 身份验证令牌：在 Sentry 中创建一个内部集成：
   • 在 Sentry 中，前往 Settings → Developer Settings → Custom Integrations
   • 点击 Create New Integration → 选择 Internal Integration
   • 设置权限：
     • Organization: Read — 必需
     • Project: Read — 必需
     • Project: Write — 仅在使用 auto_create_projects 时需要
   • 保存，然后点击 Create New Token 并复制令牌

确保所选的 .env 文件已添加到 .gitignore。

等待用户设置凭据

说明如何获取这些值后，询问用户在更新 .env 文件后进行确认：

• 是，凭据已设置：继续验证并运行收集器
• 还没有：我会等待你更新 .env 文件

如果用户选择“还没有”，请等待并再次询问。确认凭据已设置之前，不要继续执行步骤 6。

验证配置

凭据设置完成后，根据步骤 2 中选择的安装方式，使用相应方法验证配置。

使用步骤 1 中的配置文件路径（可以是已修改的现有配置文件，也可以是新的 collector-config.yaml）。

二进制文件验证

使用步骤 2 中记录的收集器路径（如果在 PATH 中，则为 otelcol-contrib；如果是本地文件，则为 ./otelcol-contrib）。

先加载环境变量，然后运行验证：

set -a && source "<env_file>" && set +a && "<collector_path>" validate --config "<config_file>"

Docker 验证

注意：Docker 卷挂载需要绝对路径。如果 <config_file> 或 <env_file> 是相对路径，请在前面加上 $(pwd)/。如果它们已经是绝对路径，则直接使用。

docker run --rm \
  -v "<absolute_config_path>":/etc/otelcol-contrib/config.yaml \
  --env-file "<env_file>" \
  otel/opentelemetry-collector-contrib:<numeric_version> \
  validate --config /etc/otelcol-contrib/config.yaml

使用步骤 5 中选择的 .env 文件路径。

如果验证失败：

1. 仔细检查错误消息
2. 修复配置文件中的问题
3. 再次运行验证
4. 重复上述步骤，直到验证通过

验证通过后，询问用户是否准备好运行收集器：

• 是，现在运行：继续执行步骤 6 并启动收集器
• 还没有：等待。用户可能想先检查配置或准备环境。

等待用户确认后再继续执行步骤 6。

步骤 6：运行 Collector

只有在用户确认已准备好运行 collector 后，才进行此步骤。

向用户提供运行命令，但不要自动执行。 用户会自行运行。

根据步骤 2 中选择的安装方式，提供相应的命令。

使用之前选择的实际路径：

• 配置文件：来自步骤 1（现有配置或新建的 collector-config.yaml）
• 环境文件：来自步骤 5（用户选择的 .env 文件）
• Collector 路径：来自步骤 2（如果在 PATH 中，则为 otelcol-contrib；如果是本地文件，则为 ./otelcol-contrib）

二进制文件

先加载环境变量，然后运行 collector：

set -a && source "<env_file>" && set +a && "<collector_path>" --config "<config_file>"

Docker

注意：Docker 卷挂载需要使用绝对路径。如果 <config_file> 或 <env_file> 是相对路径，请在其前面加上 $(pwd)/。如果它们已经是绝对路径，则直接使用。

如果要重新运行：请先停止并移除任何现有容器：

docker stop otel-collector 2>/dev/null; docker rm otel-collector 2>/dev/null

docker run -d \
  --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 13133:13133 \
  -v "<absolute_config_path>":/etc/otelcol-contrib/config.yaml \
  --env-file "<env_file>" \
  otel/opentelemetry-collector-contrib:<numeric_version>

使用步骤 2 中拉取的相同数字版本（不带 v 前缀）。

提供命令后，告知用户准备好时运行命令，然后继续步骤 7 进行验证。

步骤 7：验证设置

1. 检查 collector 日志，确认已成功启动（没有关于配置无效或连接失败的错误）
2. 查找表示已连接到 Sentry 的日志消息
3. 从已进行检测的服务发送测试遥测数据，并确认其显示在 Sentry 中

成功标准：

• Collector 启动时没有错误
• 发送数据后 60 秒内，Sentry 中出现跟踪和/或日志

如果使用 Docker，请使用 docker logs otel-collector 查看日志。

故障排除

错误	原因	解决方法
"failed to create project"	缺少 Project:Write 权限	在 Sentry 中更新 Internal Integration 权限
"no team found"	组织中没有团队	启用自动创建之前，先在 Sentry 中创建团队
"invalid auth token"	令牌类型错误或已过期	使用 Internal Integration 令牌，而非用户身份验证令牌
4317/4318 端口上出现 "connection refused"	Collector 未运行或端口冲突	检查 collector 日志并确保端口可用
验证失败并出现环境变量错误	未加载 .env 文件或占位符未替换	确保 .env 中包含真实凭据，并已加载该文件
"container name already in use"	存在之前创建的容器	运行 docker stop otel-collector && docker rm otel-collector