sentry-otel-exporter-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sentry OTel Exporter Setup

Sentry OTel Exporter 设置

Terminology: Always capitalize “Sentry Exporter” when referring to the exporter component.

Configure the OpenTelemetry Collector to send traces and logs to Sentry using the Sentry Exporter.

术语：提到 exporter 组件时，始终使用大写的“Sentry Exporter”。

配置 OpenTelemetry Collector，使用 Sentry Exporter 将 traces 和 logs 发送到 Sentry。

Setup Overview

设置概览

Copy this checklist to track your progress:

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)

复制此清单以跟踪进度：

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)

Step 1: Check for Existing Configuration

第 1 步：检查现有配置

Search for existing OpenTelemetry Collector configs by looking for YAML files containing

receivers:

. Also check for files named

otel-collector-config.*

collector-config.*

, or

otelcol.*

If an existing config is found: Ask the user which approach they want:

Modify existing config: Add Sentry Exporter to the existing file (recommended to avoid duplicates)
Create separate config: Keep existing config unchanged and create a new one for testing

Wait for the user’s answer and record their choice before proceeding to Step 2. The rest of the workflow depends on this decision.

If no config exists: Note that you’ll create a new

collector-config.yaml

in Step 4, then proceed to Step 2.

通过查找包含

receivers:

的 YAML 文件，搜索现有的 OpenTelemetry Collector 配置。同时检查名为

otel-collector-config.*

、

collector-config.*

或

otelcol.*

的文件。

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

修改现有配置：将 Sentry Exporter 添加到现有文件中（推荐，可避免重复配置）
创建独立配置：保持现有配置不变，并新建一个配置用于测试

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

如果不存在配置：说明将在第 4 步创建新的

collector-config.yaml

，然后继续第 2 步。

Step 2: Check Collector Version

第 2 步：检查 Collector 版本

The Sentry Exporter requires otelcol-contrib v0.145.0 or later.

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

Check for existing collector

检查现有 Collector

Run
```
which otelcol-contrib
```
to check if it’s on PATH, or check for
```
./otelcol-contrib
```
in the project
If found, run the appropriate version command and parse the version number
Record the collector path (e.g.,
```
otelcol-contrib
```
if on PATH, or
```
./otelcol-contrib
```
if local) for use in later steps

Existing Version	Action
≥ 0.145.0	Skip to Step 3 — existing collector is compatible
< 0.145.0	Proceed with installation below
Not installed	Proceed with installation below

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

现有版本	操作
≥ 0.145.0	跳至第 3 步——现有 Collector 兼容
< 0.145.0	继续执行下面的安装流程
未安装	继续执行下面的安装流程

Installation

安装

Ask the user how they want to run the collector:

Binary: Download from GitHub releases. No Docker required.
Docker: Run as a container. Requires Docker installed.

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

Binary：从 GitHub Releases 下载。无需 Docker。
Docker：以容器方式运行。需要安装 Docker。

Binary Installation

Binary 安装

Fetch the latest release version from GitHub:

bash

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

Important: The GitHub API returns versions with a

prefix (e.g.,

v0.145.0

). The download URL path requires the full tag with

prefix, but the filename and Docker tags use the numeric version without the prefix (e.g.,

0.145.0

Detect the user’s platform and download the binary:

Run
```
uname -s
```
and
```
uname -m
```
to detect OS and architecture
Map to release values:
- Darwin + arm64 →
```
darwin_arm64
```
- Darwin + x86_64 →
```
darwin_amd64
```
- Linux + x86_64 →
```
linux_amd64
```
- Linux + aarch64 →
```
linux_arm64
```
Download and extract:

bash

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

Example: For version

v0.145.0

, the URL uses

v0.145.0

in the path but

0.145.0

in the filename.

Perform these steps for the user—do not just show them the commands.

Ask the user if they want to delete the downloaded tarball to save disk space (~50MB):
- Yes, delete it: Remove the tarball
- No, keep it: Leave the tarball in place

Wait for the user’s response. Only delete if they explicitly choose to:

bash

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

从 GitHub 获取最新发行版本：

bash

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

重要：GitHub API 返回的版本带有

前缀（例如

v0.145.0

）。下载 URL 路径需要包含完整的

前缀，但文件名和 Docker tag 使用不含此前缀的数字版本（例如

0.145.0

）。

检测用户平台并下载 binary：

运行
```
uname -s
```
和
```
uname -m
```
检测操作系统和架构
映射到发行版参数：
- Darwin + arm64 →
```
darwin_arm64
```
- Darwin + x86_64 →
```
darwin_amd64
```
- Linux + x86_64 →
```
linux_amd64
```
- Linux + aarch64 →
```
linux_arm64
```
下载并解压：

bash

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

。

请替用户执行这些步骤——不要只显示命令。

询问用户是否希望删除下载的 tarball 以节省磁盘空间（约 50MB）：
- 是，删除：删除 tarball
- 不，保留：将 tarball 留在原处

等待用户回复。 仅在用户明确选择“是，删除”时执行：

bash

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

Docker Installation

Docker 安装

Verify Docker is installed by running
```
docker --version
```
Fetch the latest release tag from GitHub (same as above)
Pull the image using the numeric version (without
```
v
```
prefix):

bash

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

Example: For GitHub tag

v0.145.0

, use

docker pull otel/opentelemetry-collector-contrib:0.145.0

The

docker run

command comes later in Step 6 after the config is created.

运行
```
docker --version
```
，验证 Docker 是否已安装
从 GitHub 获取最新 release tag（方式同上）
使用不含
```
v
```
前缀的数字版本拉取镜像：

bash

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

例如，对于 GitHub tag

v0.145.0

，使用

docker pull otel/opentelemetry-collector-contrib:0.145.0

。

docker run

命令将在第 6 步配置创建完成后运行。

Step 3: Configure Sentry Project Creation

第 3 步：配置 Sentry 项目创建

Ask the user whether to enable automatic Sentry project creation. Do not recommend either option:

Yes: Projects created from service.name. Requires at least one team in your Sentry org. All new projects are assigned to the first team found. Initial data may be dropped during creation.
No: Projects must exist in Sentry before telemetry arrives.

Wait for the user’s answer before proceeding to Step 4.

If user chooses Yes: Warn them that the exporter will scan all projects and use the first team it finds. All auto-created projects will be assigned to that team. If they don’t have any teams yet, they should create one in Sentry first.

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

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

等待用户回答，然后再继续第 4 步。

如果用户选择“是”：警告用户 Sentry Exporter 将扫描所有项目，并使用找到的第一个团队。所有自动创建的项目都将分配给该团队。如果用户尚无任何团队，应先在 Sentry 中创建一个团队。

Step 4: Write Collector Config

第 4 步：编写 Collector 配置

Use the decision from Step 1 - if the user chose to modify an existing config, edit that file. If they chose to create a separate config, create a new file. Record the config file path for use in Steps 5 and 6.

Fetch the latest configuration from the Sentry Exporter documentation:

Example config (use as template):

https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/example-config.yaml

Full spec (all available options):

https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/spec.md

Use WebFetch to retrieve the example config as a starting template. Reference the spec if the user needs advanced options not shown in the example.

使用第 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 获取示例配置作为初始模板。如果用户需要示例中未显示的高级选项，请参阅规范。

If editing an existing config (per Step 1 decision)

如果修改现有配置（依据第 1 步的决定）

Add the

sentry

exporter to the

exporters:

section and include it in the appropriate pipelines (

traces

logs

). Do not remove or modify other exporters unless the user requests it.

在

exporters:

部分中添加

sentry

exporter，并将其加入相应的 pipelines（

traces

、

logs

）。除非用户明确要求，否则不要移除或修改其他 exporters。

If creating a new config (per Step 1 decision)

如果创建新配置（依据第 1 步的决定）

Create

collector-config.yaml

based on the fetched example. Ensure credentials use environment variable references (

${env:SENTRY_ORG_SLUG}

${env:SENTRY_AUTH_TOKEN}

If user chose auto-create in Step 3, add

auto_create_projects: true

to the sentry exporter.

根据获取的示例创建

collector-config.yaml

。确保凭据使用环境变量引用（

${env:SENTRY_ORG_SLUG}

、

${env:SENTRY_AUTH_TOKEN}

）。

如果用户在第 3 步选择了自动创建，请在 sentry exporter 中添加

auto_create_projects: true

。

Add Debug Exporter (Recommended)

添加 Debug Exporter（推荐）

For troubleshooting during setup, add a

debug

exporter with

verbosity: detailed

to the pipelines. This logs all telemetry to console. Remove it once setup is verified.

设置过程中如需排查问题，请在 pipelines 中添加带

verbosity: detailed

的

debug

exporter。这会将所有遥测数据记录到控制台。设置验证完成后将其移除。

Step 5: Add Environment Variable Placeholders

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

The Sentry Exporter requires two environment variables. You will add placeholder values that the user fills in themselves—never actual credentials.

Language constraint: NEVER say “add credentials”, “add environment variables”, or “add the token” without explicitly stating these are placeholders. Always clarify the user fills them in later.

DO NOT say:

“Let me add the environment variables”
“I’ll add the credentials to your .env”
“Adding the Sentry auth token”

SAY INSTEAD:

“I’ll add placeholder environment variables for you to fill in”
“Adding placeholder values—you’ll replace these with your actual credentials”
“I’ll set up the env var keys with placeholder values”

Search for existing

.env

files in the project using glob

**/.env

. Always ask the user which file to use—do not infer from context or guess based on open files.

Present the discovered options:

[path to discovered .env file]: Add to existing file (list each discovered path)
Create new at root: Create .env in project root

Wait for the user’s explicit selection. Do not proceed until they choose. Record the env file path for use in Steps 5 (validation) and 6 (running).

Add these placeholder values to the chosen file:

bash

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

After adding the placeholders, tell the user how to get their real values from Sentry:

Sentry org slug: In Sentry, go to Settings → Organization Settings → Organization Slug. This is also your subdomain (e.g.,
```
myorg
```
in
```
https://myorg.sentry.io
```
)
Sentry auth token: Create an Internal Integration in Sentry:
- In Sentry, go to Settings → Developer Settings → Custom Integrations
- Click Create New Integration → Choose Internal Integration
- Set permissions:
  - Organization: Read — required
  - Project: Read — required
  - Project: Write — required only if using
```
auto_create_projects
```
- Save, then click Create New Token and copy it

Ensure the chosen

.env

file is in

.gitignore

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

语言约束：绝不要在未明确说明这些是占位符的情况下说“添加凭据”、“添加环境变量”或“添加 token”。始终说明由用户稍后填写。

不要说：

“让我添加环境变量”
“我会把凭据添加到你的 .env 中”
“正在添加 Sentry auth token”

应改为说：

“我会为你添加占位环境变量，供你自行填写”
“正在添加占位值——你之后会将其替换为实际凭据”
“我会用占位值设置 env var 键”

使用 glob

**/.env

搜索项目中的现有

.env

文件。始终询问用户使用哪个文件——不要根据上下文推断，也不要根据打开的文件猜测。

显示发现的选项：

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

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

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

bash

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

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

Sentry org slug：在 Sentry 中，进入 Settings → Organization Settings → Organization Slug。这也是你的子域名（例如，
```
https://myorg.sentry.io
```
中的
```
myorg
```
）
Sentry auth token：在 Sentry 中创建 Internal Integration：
- 在 Sentry 中，进入 Settings → Developer Settings → Custom Integrations
- 点击 Create New Integration → 选择 Internal Integration
- 设置权限：
  - Organization: Read — 必需
  - Project: Read — 必需
  - Project: Write — 仅在使用
```
auto_create_projects
```
    时必需
- 保存，然后点击 Create New Token 并复制 token

确保选定的

.env

文件已加入

.gitignore

。

Wait for user to set credentials

等待用户设置凭据

After explaining how to get the values, ask the user to confirm when they’ve updated the

.env

file:

Yes, credentials are set: Proceed to validate and run the collector
Not yet: I’ll wait while you update the .env file

If user selects “Not yet”, wait and ask again. Do not proceed to Step 6 until credentials are confirmed.

解释如何获取这些值后，询问用户确认其已更新

.env

文件：

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

如果用户选择“还没有”，则等待并再次询问。在确认凭据之前，不要继续第 6 步。

Validate config

验证配置

Once credentials are set, validate the configuration using the appropriate method based on the installation choice from Step 2.

Use the config file path from Step 1 (either the existing config you modified or the new

collector-config.yaml

凭据设置完成后，根据第 2 步中的安装方式，使用适当的方法验证配置。

使用第 1 步中的配置文件路径（即已修改的现有配置或新的

collector-config.yaml

）。

Binary validation

Binary 验证

Use the collector path recorded in Step 2 (either

otelcol-contrib

if on PATH, or

./otelcol-contrib

if local).

Load environment variables first, then run validation:

bash

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

使用第 2 步中记录的 Collector 路径（位于 PATH 上时为

otelcol-contrib

，位于本地时为

./otelcol-contrib

）。

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

bash

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

Docker validation

Docker 验证

Note: Docker volume mounts require absolute paths. If

<config_file>

<env_file>

are relative paths, prefix them with

$(pwd)/

. If they’re already absolute paths, use them directly.

bash

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

Use the

.env

file path chosen in Step 5.

If validation fails:

Review the error message carefully
Fix the issues in the config file
Run validation again
Repeat until validation passes

Once validation passes, ask the user if they’re ready to run the collector:

Yes, run it now: Proceed to Step 6 and start the collector
Not yet: Wait. The user may want to review the config or prepare their environment first.

Wait for the user’s confirmation before proceeding to Step 6.

注意：Docker 卷挂载要求使用绝对路径。如果

<config_file>

或

<env_file>

是相对路径，则为其加上

$(pwd)/

前缀。如果它们已经是绝对路径，则直接使用。

bash

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

文件路径。

如果验证失败：

仔细检查错误消息
修复配置文件中的问题
再次运行验证
重复操作，直到验证通过

验证通过后，询问用户是否准备运行 Collector：

是，立即运行：继续第 6 步并启动 Collector
暂时不：等待。用户可能希望先检查配置或准备环境。

在继续第 6 步之前，等待用户确认。

Step 6: Run the Collector

第 6 步：运行 Collector

Only reach this step after the user confirms they’re ready to run the collector.

Give the user the run command but do not execute it automatically. The user will run it themselves.

Provide the appropriate command based on the installation method chosen in Step 2.

Use the actual paths chosen earlier:

Config file: From Step 1 (existing config or new
```
collector-config.yaml
```
)
Env file: From Step 5 (the
```
.env
```
file the user selected)
Collector path: From Step 2 (either
```
otelcol-contrib
```
if on PATH, or
```
./otelcol-contrib
```
if local)

只有在用户确认准备运行 Collector 后，才能进入此步骤。

向用户提供运行命令，但不要自动执行。 用户将自行运行。根据第 2 步选择的安装方式，提供适当命令。

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

配置文件：来自第 1 步（现有配置或新的
```
collector-config.yaml
```
）
Env 文件：来自第 5 步（用户选择的
```
.env
```
文件）
Collector 路径：来自第 2 步（位于 PATH 上时为
```
otelcol-contrib
```
，位于本地时为
```
./otelcol-contrib
```
）

Binary

Load environment variables first, then run the collector:

bash

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

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

bash

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

Docker

Note: Docker volume mounts require absolute paths. If

<config_file>

<env_file>

are relative paths, prefix them with

$(pwd)/

. If they’re already absolute paths, use them directly.

If re-running: Stop and remove any existing container first:

bash

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

bash

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>

Use the same numeric version (without

prefix) that was pulled in Step 2.

After providing the command, tell the user to run it when they’re ready, then proceed to Step 7 for verification.

注意：Docker 卷挂载要求使用绝对路径。如果

<config_file>

或

<env_file>

是相对路径，则为其加上

$(pwd)/

前缀。如果它们已经是绝对路径，则直接使用。

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

bash

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

bash

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 步中拉取的相同数字版本（不含

前缀）。

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

Step 7: Verify Setup

第 7 步：验证设置

Check collector logs for successful startup (no errors about invalid config or failed connections)
Look for log messages indicating connection to Sentry
Send test telemetry from an instrumented service and verify it appears in Sentry

Success criteria:

Collector starts without errors
Traces and/or logs appear in Sentry within 60 seconds of sending

If using Docker, check logs with

docker logs otel-collector

检查 Collector 日志，确认启动成功（没有无效配置或连接失败等错误）
查找表明已连接到 Sentry 的日志消息
从已埋点的服务发送测试遥测数据，并确认其出现在 Sentry 中

成功标准：

Collector 启动时无错误
发送后 60 秒内，traces 和/或 logs 出现在 Sentry 中

如果使用 Docker，通过

docker logs otel-collector

检查日志。

Step 8: Enable Trace Connectedness with OTLPIntegration

第 8 步：使用 OTLPIntegration 启用 Trace Connectedness

If the user’s application uses a Sentry SDK (Python, Ruby, or Node.js), recommend enabling the OTLPIntegration. This ensures trace connectedness — linking OTel traces to Sentry errors, logs, crons, and metrics — and sets up distributed tracing propagation automatically.

Without this step, traces sent through the collector appear in Sentry but are not connected to other Sentry events (errors, logs) from the same service.

Ask the user: Does your application use the Sentry Python SDK, Sentry Ruby SDK, or Sentry Node.js SDK?

Python: Follow the Python setup below
Ruby: Follow the Ruby setup below
Node.js: Follow the Node.js setup below
Neither / Other SDK: Skip this step. Trace connectedness via OTLPIntegration is currently available for Python, Ruby, and Node.js.

如果用户的应用使用 Sentry SDK（Python、Ruby 或 Node.js），建议启用 OTLPIntegration。这可确保 trace connectedness——将 OTel traces 与 Sentry errors、logs、crons 和 metrics 关联起来——并自动设置分布式追踪传播。

如果不执行此步骤，通过 Collector 发送的 traces 会出现在 Sentry 中，但不会与同一服务的其他 Sentry events（errors、logs）关联。

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

Python：按照下面的 Python 设置执行
Ruby：按照下面的 Ruby 设置执行
Node.js：按照下面的 Node.js 设置执行
都不使用/其他 SDK：跳过此步骤。目前可通过 OTLPIntegration 为 Python、Ruby 和 Node.js 实现 trace connectedness。

Python OTLPIntegration

Docs: https://docs.sentry.io/platforms/python/integrations/otlp/

Install the extra:

bash

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

Add the
```
OTLPIntegration
```
to the existing
```
sentry_sdk.init()
```
call, setting
```
collector_url
```
to the collector’s OTLP traces endpoint:

python

from sentry_sdk.integrations.otlp import OTLPIntegration

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

Use the collector’s actual OTLP HTTP endpoint. The default is

http://localhost:4318/v1/traces

if running locally.

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

安装附加组件：

bash

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

在现有
```
sentry_sdk.init()
```
调用中添加
```
OTLPIntegration
```
，并将
```
collector_url
```
设置为 Collector 的 OTLP traces endpoint：

python

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 endpoint。本地运行时，默认值为

http://localhost:4318/v1/traces

。

Ruby OTLPIntegration

Docs: https://docs.sentry.io/platforms/ruby/integrations/otlp/

Add gems to the Gemfile:

ruby

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

Run
```
bundle install
```
Configure OpenTelemetry instrumentation:

ruby

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

Enable OTLP in the existing
```
Sentry.init
```
block, setting
```
collector_url
```
to the collector’s OTLP traces endpoint:

ruby

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

Use the collector’s actual OTLP HTTP endpoint. The default is

http://localhost:4318/v1/traces

if running locally.

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

将 gems 添加到 Gemfile：

ruby

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

运行
```
bundle install
```
配置 OpenTelemetry instrumentation：

ruby

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

在现有
```
Sentry.init
```
块中启用 OTLP，并将
```
collector_url
```
设置为 Collector 的 OTLP traces endpoint：

ruby

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 endpoint。本地运行时，默认值为

http://localhost:4318/v1/traces

。

Node.js OTLPIntegration

Docs: https://docs.sentry.io/platforms/javascript/guides/node/

Install the lightweight Sentry SDK and OpenTelemetry dependencies:

bash

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

Create an instrument file (
```
instrument.mjs
```
) that sets up OTel and Sentry together:

javascript

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',
    }),
  ],
});

Start your app with the
```
--import
```
flag:

bash

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

Use the collector’s actual OTLP HTTP endpoint. The default is

http://localhost:4318/v1/traces

if running locally.

Do not set
tracesSampleRate
when using
otlpIntegration
— OTel controls sampling. Setting it would conflict with the OTLP path.

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

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

bash

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

创建一个 instrument 文件（
```
instrument.mjs
```
），在其中同时设置 OTel 和 Sentry：

javascript

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',
    }),
  ],
});

使用
```
--import
```
标志启动应用：

bash

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

使用 Collector 实际的 OTLP HTTP endpoint。本地运行时，默认值为

http://localhost:4318/v1/traces

。

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

Troubleshooting

故障排除

Error	Cause	Fix
“failed to create project”	Missing Project:Write permission	Update Internal Integration permissions in Sentry
“no team found”	No teams in org	Create a team in Sentry before enabling auto-create
“invalid auth token”	Wrong token type or expired	Use Internal Integration token, not user auth token
“connection refused” on 4317/4318	Collector not running or port conflict	Check collector logs and ensure ports are available
Validation fails with env var errors	.env file not loaded or placeholders not replaced	Ensure real credentials are in .env and the file is sourced
“container name already in use”	Previous container exists	Run `docker stop otel-collector && docker rm otel-collector`

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