用 Sentry Exporter 配置…

当需要把多个服务的 traces/logs 通过 OTel Collector 路由到 Sentry 项目、并可选自动创建项目时使用。

适用场景

解决思路

1. 先搜索现有 OpenTelemetry Collector 配置：查找包含 `receivers:` 的 YAML 文件，以及名为 `otel-collector-config.*`、`collector-config.*`、`otelcol.*` 的文件；若找到，询问用户是「修改现有配置」（推荐，避免重复）还是「新建独立配置」，等待用户回答并记录选择后再继续；若没有，则计划在 Step 4 新建 `collector-config.yaml`。
2. 检查 Collector 版本：Sentry Exporter 要求 otelcol-contrib v0.145.0 或更高。运行 `which otelcol-contrib` 或检查项目内 `./otelcol-contrib`；若找到则运行版本命令解析版本号，并记录 collector 路径供后续步骤使用。版本 ≥ 0.145.0 跳到 Step 3；< 0.145.0 或未安装则进入安装流程。
3. 安装前询问用户运行方式：Binary（从 GitHub releases 下载，无需 Docker）或 Docker（需已安装 Docker）。
4. Binary 安装：用 `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` 的完整 tag，但文件名和 Docker tag 用不带前缀的数字版本（如 `0.145.0`）。运行 `uname -s` 和 `uname -m` 检测平台并映射：Darwin+arm64→`darwin_arm64`，Darwin+x86_64→`darwin_amd64`，Linux+x86_64→`linux_amd64`，Linux+aarch64→`linux_arm64`。然后执行 `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`。替用户执行这些步骤，不要只展示命令。之后询问用户是否删除下载的 tarball（约 50MB）以节省磁盘，等待回复，仅在用户明确选择删除时执行 `rm otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz`。
5. Docker 安装：运行 `docker --version` 验证 Docker 已安装；从 GitHub 获取最新 release tag；用不带 `v` 前缀的数字版本拉取镜像：`docker pull otel/opentelemetry-collector-contrib:<numeric_version>`（例如 GitHub tag `v0.145.0` 对应 `otel/opentelemetry-collector-contrib:0.145.0`）。`docker run` 命令留到 Step 6 配置创建后再执行。
6. 配置 Sentry 项目创建：询问用户是否启用自动创建 Sentry 项目，不要推荐任一选项。选 Yes：项目从 service.name 创建，需要 Sentry org 中至少有一个 team，所有新项目分配给找到的第一个 team，创建期间初始数据可能被丢弃。选 No：项目必须在遥测到达前已存在于 Sentry。等待用户回答后再进入 Step 4。若选 Yes，警告用户 exporter 会扫描所有项目并使用找到的第一个 team，所有自动创建的项目都会分配给该 team；若还没有 team，应先到 Sentry 创建。
7. 编写 Collector 配置：按 Step 1 的决定操作——若选择修改现有配置则编辑该文件，若选择新建则创建新文件，并记录配置文件路径供 Step 5 和 6 使用。用 WebFetch 从 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`；需要示例未展示的高级选项时参考 spec。若编辑现有配置：在 `exporters:` 段添加 `sentry` exporter，并加入相应的 `traces`、`logs` pipeline，除非用户要求否则不要删除或修改其他 exporter。若新建配置：基于获取的示例创建 `collector-config.yaml`，确保凭据使用环境变量引用（`${env:SENTRY_ORG_SLUG}`、`${env:SENTRY_AUTH_TOKEN}`）；若 Step 3 选了自动创建，则在 sentry exporter 中添加 `auto_create_projects: true`。
8. 添加 Debug Exporter（推荐）：为便于排查，在 pipeline 中添加 `debug` exporter 并设 `verbosity: detailed`，将所有遥测输出到控制台；验证完成后移除。
9. 添加环境变量占位符：Sentry Exporter 需要两个环境变量，只添加占位值由用户自行填写，绝不要填真实凭据。语言约束：绝不说「添加凭据」「添加环境变量」「添加 token」而不明确说明这些是占位符；应说「我会添加占位环境变量供你填写」「添加占位值——你稍后用真实凭据替换」「我会设置 env var 键及占位值」。用 glob `**/.env` 搜索项目中现有 `.env` 文件，始终询问用户使用哪个文件，不要根据上下文或打开的文件推断。列出选项：发现的每个 `.env` 文件路径（添加到现有文件）、在项目根目录新建 `.env`。等待用户明确选择，记录 env 文件路径供 Step 5 验证和 Step 6 运行使用。向所选文件添加占位值：`SENTRY_ORG_SLUG=your-org-slug` 和 `SENTRY_AUTH_TOKEN=your-token-here`。
10. 告知用户如何从 Sentry 获取真实值：1) Sentry org slug：在 Sentry 中进入 Settings → Organization Settings → Organization Slug，这也是你的子域名（如 `https://myorg.sentry.io` 中的 `myorg`）。2) Sentry auth token：在 Sentry 中创建 Internal Integration——进入 Settings → Developer Settings → Custom Integrations，点击 Create New Integration → 选择 Internal Integration，设置权限：Organization: Read（必需）、Project: Read（必需）、Project: Write（仅在使用 `auto_create_projects` 时需要），保存后点击 Create New Token 并复制。确保所选 `.env` 文件在 `.gitignore` 中。
11. 等待用户设置凭据：解释完获取方式后，询问用户确认是否已更新 `.env` 文件。选「是，凭据已设置」则继续验证并运行 collector；选「还没」则等待并再次询问，在凭据确认前不要进入 Step 6。
12. 验证配置：凭据设置后，按 Step 2 的安装方式选择验证方法，使用 Step 1 的配置文件路径（修改的现有配置或新建的 `collector-config.yaml`）。Binary 验证：使用 Step 2 记录的 collector 路径（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 "<config_file>":/etc/otelcol-contrib/config.yaml --env-file "<env_file>" otel/opentelemetry-collector-contrib:<numeric_version> validate --config /etc/otelcol-contrib/config.yaml`，使用 Step 5 选择的 `.env` 文件路径。若验证失败：仔细查看错误信息、修复配置文件问题、再次运行验证、重复直到通过。验证通过后询问用户是否准备运行 collector：选「是，现在运行」则进入 Step 6 启动；选「还没」则等待，用户可能想先审查配置或准备环境。等待用户确认后再进入 Step 6。
13. 运行 Collector：仅在用户确认准备运行后进入此步。给出运行命令但不要自动执行，由用户自行运行。按 Step 2 的安装方式提供命令，使用之前选择的实际路径：配置文件来自 Step 1，env 文件来自 Step 5，collector 路径来自 Step 2。Binary：先加载环境变量再运行：`set -a && source "<env_file>" && set +a && "<collector_path>" --config "<config_file>"`。Docker：卷挂载需绝对路径，相对路径加 `$(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>`，使用 Step 2 拉取的相同数字版本（不带 `v` 前缀）。提供命令后告诉用户准备好时运行，然后进入 Step 7 验证。
14. 验证设置：1) 检查 collector 日志确认成功启动（无无效配置或连接失败错误）；2) 查找表示已连接到 Sentry 的日志消息；3) 从已插桩的服务发送测试遥测并确认出现在 Sentry 中。成功标准：collector 无错误启动；发送后 60 秒内 traces 和/或 logs 出现在 Sentry 中。若使用 Docker，用 `docker logs otel-collector` 查看日志。
15. 启用 OTLPIntegration 实现 trace connectedness：若应用使用 Sentry SDK（Python、Ruby 或 Node.js），推荐启用 OTLPIntegration，确保 trace connectedness——将 OTel traces 关联到 Sentry 的 errors、logs、crons 和 metrics，并自动设置分布式追踪传播。没有此步，通过 collector 发送的 traces 会出现在 Sentry 中但不会与同一服务的其他 Sentry 事件（errors、logs）关联。询问用户应用是否使用 Sentry Python SDK、Ruby SDK 或 Node.js SDK，按对应方式设置；其他 SDK 则跳过此步（OTLPIntegration 的 trace connectedness 目前仅支持 Python、Ruby、Node.js）。
16. Python OTLPIntegration（文档 https://docs.sentry.io/platforms/python/integrations/otlp/）：1) 安装 extra：`pip install "sentry-sdk[opentelemetry-otlp]"`。2) 在现有 `sentry_sdk.init()` 调用中添加 `OTLPIntegration`，将 `collector_url` 设为 collector 的 OTLP traces 端点：`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`。
17. Ruby OTLPIntegration（文档 https://docs.sentry.io/platforms/ruby/integrations/otlp/）：1) 在 Gemfile 添加 gems：`gem "sentry-opentelemetry"`、`gem "opentelemetry-sdk"`、`gem "opentelemetry-exporter-otlp"`、`gem "opentelemetry-instrumentation-all"`。2) 运行 `bundle install`。3) 配置 OpenTelemetry instrumentation：`OpenTelemetry::SDK.configure do |c| c.use_all end`。4) 在现有 `Sentry.init` 块中启用 OTLP，将 `collector_url` 设为 collector 的 OTLP traces 端点：`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`。
18. 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) 创建 instrument 文件（`instrument.mjs`）同时设置 OTel 和 Sentry：`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 路径冲突。
19. 故障排查："failed to create project"→缺少 Project:Write 权限，在 Sentry 更新 Internal Integration 权限；"no team found"→org 中没有 team，启用自动创建前先在 Sentry 创建 team；"invalid auth token"→token 类型错误或已过期，使用 Internal Integration token 而非用户 auth token；4317/4318 上 "connection refused"→collector 未运行或端口冲突，检查 collector 日志并确保端口可用；验证因 env var 错误失败→.env 文件未加载或占位符未替换，确保 `.env` 中有真实凭据且文件已 source；"container name already in use"→存在之前的容器，运行 `docker stop otel-collector && docker rm otel-collector`。

适用边界 · 注意事项

• 不使用 Sentry 或不需要把 OTel 遥测路由到 Sentry 时
• 应用不使用 Sentry Python/Ruby/Node.js SDK 时，无法启用 OTLPIntegration 的 trace connectedness（可跳过 Step 8）
• 无法安装 otelcol-contrib v0.145.0 或更高版本时，Sentry Exporter 不可用