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.

术语说明：提及该导出器组件时，请始终大写“Sentry Exporter”。

配置OpenTelemetry Collector，通过Sentry Exporter将追踪和日志数据发送到Sentry。

Step 1: Choose Installation Method

步骤1：选择安装方式

Ask the user how they want to run the collector:

Question: "How do you want to run the OpenTelemetry Collector?"
Header: "Collector"
Options:
  - label: "Binary"
    description: "Download from GitHub releases. No Docker required."
  - label: "Docker"
    description: "Run as a container. Requires Docker installed."

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

问题：“你希望如何运行OpenTelemetry Collector？”
标题：“Collector运行方式”
选项：
  - 标签：“二进制文件”
    描述：“从GitHub发布版本下载。无需Docker。”
  - 标签：“Docker”
    描述：“以容器形式运行。需要已安装Docker。”

Binary Installation

二进制安装

The Sentry exporter is included in otelcol-contrib v0.145.0+.

Detect the user's platform and download the binary for them:

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/v0.145.0/otelcol-contrib_0.145.0_<os>_<arch>.tar.gz
tar -xzf otelcol-contrib_0.145.0_<os>_<arch>.tar.gz
chmod +x otelcol-contrib

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

Sentry导出器已包含在otelcol-contrib v0.145.0及以上版本中。

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

运行
```
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/v0.145.0/otelcol-contrib_0.145.0_<os>_<arch>.tar.gz
tar -xzf otelcol-contrib_0.145.0_<os>_<arch>.tar.gz
chmod +x otelcol-contrib

为用户执行这些步骤——不要仅展示命令。

Docker Installation

Docker安装

Verify Docker is installed by running
```
docker --version
```
Pull the image for the user:

bash

docker pull otel/opentelemetry-collector-contrib:0.145.0

The

docker run

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

通过运行
```
docker --version
```
验证Docker是否已安装
为用户拉取镜像：

bash

docker pull otel/opentelemetry-collector-contrib:0.145.0

docker run

命令将在步骤5创建配置后提供。

Step 2: Configure Project Creation

步骤2：配置项目自动创建

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

Question: "Do you want Sentry to automatically create projects when telemetry arrives?"
Header: "Auto-create"
Options:
  - label: "Yes"
    description: "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."
  - label: "No"
    description: "Projects must exist in Sentry before telemetry arrives."

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中存在。”

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

Step 3: Write Collector Config

步骤3：编写Collector配置

Create

collector-config.yaml

with the Sentry exporter:

yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  sentry:
    url: https://sentry.io
    org_slug: ${env:SENTRY_ORG_SLUG}
    auth_token: ${env:SENTRY_AUTH_TOKEN}

processors:
  batch:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry]

If user chose auto-create in Step 2, add

auto_create_projects: true

to the sentry exporter.

创建带有Sentry Exporter的

collector-config.yaml

文件：

yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  sentry:
    url: https://sentry.io
    org_slug: ${env:SENTRY_ORG_SLUG}
    auth_token: ${env:SENTRY_AUTH_TOKEN}

processors:
  batch:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry]

如果用户在步骤2中选择了自动创建，请在sentry导出器配置中添加

auto_create_projects: true

。

Add Debug Exporter (Recommended)

添加Debug导出器（推荐）

For troubleshooting during setup, add the debug exporter to see telemetry in collector logs:

yaml

exporters:
  sentry:
    # ... existing config
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry, debug]  # Add debug here
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry, debug]  # Add debug here

This logs all telemetry to console. Remove

debug

from exporters list once setup is verified.

为了在配置过程中排查问题，添加debug导出器以在Collector日志中查看遥测数据：

yaml

exporters:
  sentry:
    # ... 现有配置
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry, debug]  # 在此处添加debug
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [sentry, debug]  # 在此处添加debug

这会将所有遥测数据记录到控制台。配置验证完成后，从导出器列表中移除

debug

。

Routing (Optional)

路由配置（可选）

To map service names to different project slugs, add

routing.attribute_to_project_mapping

to the sentry exporter. Services not in the mapping fall back to

service.name

as project slug.

若要将服务名称映射到不同的项目slug，请在sentry导出器中添加

routing.attribute_to_project_mapping

配置。未在映射中的服务会默认使用

service.name

作为项目slug。

Step 4: Set Up Credentials

步骤4：设置凭证

Create an Internal Integration in Sentry to get an auth token:

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 for
```
auto_create_projects
```
Save, then click Create New Token and copy it

Search for existing

.env

files in the project using glob

**/.env

. If any are found, ask the user which one to add the credentials to:

Question: "Where should I add the Sentry credentials?"
Header: "Env file"
Options:
  - label: "<path/to/.env>"  # One option per discovered .env file
    description: "Add to existing file"
  - label: "Create new at root"
    description: "Create .env in project root"

Add these environment variables (with placeholder values) to the chosen file:

bash

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

Tell the user to replace the placeholder values:

Org slug: Found in URL
```
sentry.io/organizations/{slug}/
```
Auth token: The token from step 4

Ensure the chosen

.env

file is in

.gitignore

在Sentry中创建一个内部集成以获取认证令牌：

前往设置 → 开发者设置 → 自定义集成
点击创建新集成 → 选择内部集成
设置权限：
- 组织：读取 — 必填
- 项目：读取 — 必填
- 项目：写入 — 启用
```
auto_create_projects
```
  时必填
保存，然后点击创建新令牌并复制该令牌

使用通配符

**/.env

搜索项目中现有的.env文件。如果找到任何文件，询问用户要将凭证添加到哪个文件中：

问题：“我应该将Sentry凭证添加到哪里？”
标题：“环境变量文件”
选项：
  - 标签：“<path/to/.env>”  # 每个已发现的.env文件对应一个选项
    描述：“添加到现有文件”
  - 标签：“在根目录创建新文件”
    描述：“在项目根目录创建.env文件”

将这些环境变量（包含占位符值）添加到所选文件中：

bash

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

告知用户替换占位符值：

组织slug：可在URL
```
sentry.io/organizations/{slug}/
```
中找到
认证令牌：步骤4中获取的令牌

确保所选的

.env

文件已添加到

.gitignore

中。

Step 5: Run the Collector

步骤5：运行Collector

Provide run instructions based on the installation method chosen in Step 1.

根据步骤1中选择的安装方式提供运行说明。

Binary

二进制文件

bash

./otelcol-contrib --config collector-config.yaml

bash

./otelcol-contrib --config collector-config.yaml

Docker

bash

docker run -d \
  --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 13133:13133 \
  -v $(pwd)/collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  --env-file .env \
  otel/opentelemetry-collector-contrib:0.145.0

bash

docker run -d \
  --name otel-collector \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 13133:13133 \
  -v $(pwd)/collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  --env-file .env \
  otel/opentelemetry-collector-contrib:0.145.0