sentry-otel-exporter-setup

Sentry OTel 导出器设置

术语：提及导出器组件时，始终将其写作“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
- [ ] Step 8: Enable trace connectedness with OTLPIntegration (Python/Ruby/Node.js)

步骤 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。

docker run 命令将在步骤 6 中配置创建后运行。

步骤 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 中选择自动创建，则向 sentry 导出器添加 auto_create_projects: true。

添加 Debug Exporter（推荐）

为便于排查设置问题，向管道中添加一个 debug 导出器，并设置 verbosity: detailed。 这会将所有遥测数据记录到控制台。 确认设置无误后将其移除。

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

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

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

不要说：

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

应改为：

• “我会为你添加环境变量占位符，供你之后填写”
• “正在添加占位值——你之后会将其替换为实际凭据”
• “我会设置带有占位值的环境变量键”

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

列出找到的选项：

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

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

将以下占位值添加到用户选择的文件中：

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

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

1. Sentry 组织 slug：在 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 中记录的采集器路径（如果 otelcol-contrib 在 PATH 中，则使用它；如果是本地文件，则使用 ./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 "<config_file>":/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 "<config_file>":/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 检查日志。

步骤 8：使用 OTLPIntegration 启用跟踪关联

如果用户的应用使用 Sentry SDK（Python、Ruby 或 Node.js），建议启用 OTLPIntegration。 这能确保跟踪关联——将 OTel 跟踪与 Sentry 错误、日志、定时任务和指标关联起来——并自动设置分布式跟踪传播。

如果不执行此步骤，通过 Collector 发送的跟踪会显示在 Sentry 中，但不会与同一服务的其他 Sentry 事件（错误、日志）关联。

询问用户：您的应用是否使用 Sentry Python SDK、Sentry Ruby SDK 或 Sentry Node.js SDK？

• Python：按照下面的 Python 设置说明操作
• Ruby：按照下面的 Ruby 设置说明操作
• Node.js：按照下面的 Node.js 设置说明操作
• 都不是／其他 SDK：跳过此步骤。 目前，OTLPIntegration 的跟踪关联功能仅适用于 Python、Ruby 和 Node.js。

Python OTLPIntegration

文档：https://docs.sentry.io/platforms/python/integrations/otlp/

1. 安装附加组件：

pip install "sentry-sdk[opentelemetry-otlp]"

2. 将 OTLPIntegration 添加到现有的 sentry_sdk.init() 调用中，并将 collector_url 设置为 Collector 的 OTLP 跟踪端点：

from sentry_sdk.integrations.otlp import OTLPIntegration

sentry_sdk.init(
    dsn="___PUBLIC_DSN___",
    integrations=[
        OTLPIntegration(collector_url="http://localhost:4318/v1/traces"),
    ],
)

使用 Collector 实际的 OTLP HTTP 端点。 如果在本地运行，默认值为 http://localhost:4318/v1/traces。

Ruby OTLPIntegration

文档：https://docs.sentry.io/platforms/ruby/integrations/otlp/

1. 将 gem 添加到 Gemfile：

gem "sentry-opentelemetry"
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-instrumentation-all"

2. 运行 bundle install

3. 配置 OpenTelemetry 插桩：

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

4. 在现有的 Sentry.init 块中启用 OTLP，并将 collector_url 设置为 Collector 的 OTLP 跟踪端点：

Sentry.init do |config|
  config.dsn = "___PUBLIC_DSN___"
  config.otlp.enabled = true
  config.otlp.collector_url = "http://localhost:4318/v1/traces"
end

使用 Collector 实际的 OTLP HTTP 端点。 如果在本地运行，默认值为 http://localhost:4318/v1/traces。

Node.js OTLPIntegration

文档：https://docs.sentry.io/platforms/javascript/guides/node/

1. 安装轻量级 Sentry SDK 和 OpenTelemetry 依赖项：

npm install @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

2. 创建一个用于初始化 OTel 和 Sentry 的插桩文件（instrument.mjs）：

import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node-core/light';
import { otlpIntegration } from '@sentry/node-core/light/otlp';

const provider = new NodeTracerProvider();
provider.register();

Sentry.init({
  dsn: '___PUBLIC_DSN___',
  integrations: [
    otlpIntegration({
      collectorUrl: 'http://localhost:4318/v1/traces',
    }),
  ],
});

3. 使用 --import 标志启动应用：

node --import ./instrument.mjs app.mjs

使用 Collector 实际的 OTLP HTTP 端点。 如果在本地运行，默认值为 http://localhost:4318/v1/traces。

使用 otlpIntegration 时不要设置 tracesSampleRate——采样由 OTel 控制。设置该值会与 OTLP 路径冲突。

故障排查

错误	原因	解决方法
“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