sentry-otel-exporter-setup by getsentry/sentry-for-ai
npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-otel-exporter-setup术语说明:在指代导出器组件时,始终将 "Sentry Exporter" 首字母大写。
配置 OpenTelemetry Collector,使用 Sentry Exporter 将追踪和日志发送到 Sentry。
复制此清单以跟踪进度:
OTel 导出器设置:
- [ ] 步骤 1:检查现有配置
- [ ] 步骤 2:检查收集器版本并按需安装
- [ ] 步骤 3:配置项目创建设置
- [ ] 步骤 4:编写收集器配置
- [ ] 步骤 5:添加环境变量占位符
- [ ] 步骤 6:运行收集器
- [ ] 步骤 7:验证设置
- [ ] 步骤 8:使用 OTLPIntegration 启用追踪连通性(Python/Ruby)
通过查找包含 receivers: 的 YAML 文件来搜索现有的 OpenTelemetry Collector 配置。同时检查名为 otel-collector-config.*、collector-config.* 或 otelcol.* 的文件。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
如果找到现有配置:询问用户希望采用哪种方式:
等待用户的回答,并在继续步骤 2 之前记录他们的选择。 后续工作流程取决于此决定。
如果不存在配置:请注意,您将在步骤 4 中创建一个新的 collector-config.yaml,然后继续步骤 2。
Sentry Exporter 需要 otelcol-contrib v0.145.0 或更高版本。
which otelcol-contrib 检查它是否在 PATH 中,或检查项目中是否存在 ./otelcol-contribotelcol-contrib,如果是本地文件则为 ./otelcol-contrib)以供后续步骤使用| 现有版本 | 操作 |
|---|---|
| ≥ 0.145.0 | 跳至步骤 3 — 现有收集器兼容 |
| < 0.145.0 | 继续下面的安装步骤 |
| 未安装 | 继续下面的安装步骤 |
询问用户希望如何运行收集器:
从 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)。
检测用户的平台并下载二进制文件:
uname -s 和 uname -m 来检测操作系统和架构darwin_arm64darwin_amd64linux_amd64linux_arm64curl -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。
为用户执行这些步骤——不要仅仅展示命令。
等待用户的响应。 仅在他们明确选择删除时才删除:
rm otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz
docker --version 验证 Docker 是否已安装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 中创建配置后出现。
询问用户是否启用自动创建 Sentry 项目。不要推荐任何选项:
等待用户的回答,然后再继续步骤 4。
如果用户选择是:警告他们,导出器将扫描所有项目并使用找到的第一个团队。所有自动创建的项目都将分配给该团队。如果他们还没有任何团队,应先在 Sentry 中创建一个。
使用步骤 1 中的决定 - 如果用户选择修改现有配置,则编辑该文件。如果他们选择创建独立配置,则创建一个新文件。记录配置文件路径以供步骤 5 和 6 使用。
从 Sentry Exporter 文档获取最新配置:
https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/example-config.yamlhttps://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/spec.md使用 WebFetch 检索示例配置作为起始模板。如果用户需要示例中未显示的高级选项,请参考规范。
将 sentry 导出器添加到 exporters: 部分,并将其包含在适当的管道(traces、logs)中。除非用户要求,否则不要移除或修改其他导出器。
基于获取的示例创建 collector-config.yaml。确保凭据使用环境变量引用(${env:SENTRY_ORG_SLUG}、${env:SENTRY_AUTH_TOKEN})。
如果用户在步骤 3 中选择了自动创建,请在 sentry 导出器中添加 auto_create_projects: true。
为了在设置过程中进行故障排除,向管道添加一个带有 verbosity: detailed 的 debug 导出器。这会将所有遥测数据记录到控制台。设置验证后将其移除。
Sentry Exporter 需要两个环境变量。您将添加占位符值,由用户自己填写——切勿使用实际凭据。
语言约束:在未明确说明这些是占位符的情况下,切勿说“添加凭据”、“添加环境变量”或“添加令牌”。始终澄清用户稍后会填写它们。
不要说:
请这样说:
使用通配符 **/.env 在项目中搜索现有的 .env 文件。始终询问用户使用哪个文件——不要根据上下文推断或根据打开的文件猜测。
展示发现的选项:
等待用户的明确选择。 在他们选择之前不要继续。记录环境文件路径以供步骤 5(验证)和 6(运行)使用。
将以下占位符值添加到所选文件中:
SENTRY_ORG_SLUG=your-org-slug
SENTRY_AUTH_TOKEN=your-token-here
添加占位符后,告诉用户如何从 Sentry 获取他们的真实值:
https://myorg.sentry.io 中的 myorg)auto_create_projects 时需要确保所选的 .env 文件在 .gitignore 中。
解释如何获取值后,请用户确认他们何时更新了 .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 卷挂载需要绝对路径。如果 <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 文件路径。
如果验证失败:
一旦验证通过,询问用户是否准备好运行收集器:
在继续步骤 6 之前,等待用户的确认。
仅在用户确认准备好运行收集器后,才到达此步骤。
向用户提供运行命令,但不要自动执行。 用户将自行运行它。
根据步骤 2 中选择的安装方法提供适当的命令。
使用之前选择的实际路径:
collector-config.yaml).env 文件)otelcol-contrib,如果是本地文件则为 ./otelcol-contrib)首先加载环境变量,然后运行收集器:
set -a && source "<env_file>" && set +a && "<collector_path>" --config "<config_file>"
注意: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 进行验证。
成功标准:
如果使用 Docker,使用 docker logs otel-collector 检查日志。
如果用户的应用使用 Sentry SDK(Python 或 Ruby),建议启用 OTLPIntegration。这确保了追踪连通性——将 OTel 追踪链接到 Sentry 错误、日志、定时任务和指标——并自动设置分布式追踪传播。
如果没有此步骤,通过收集器发送的追踪会出现在 Sentry 中,但不会连接到来自同一服务的其他 Sentry 事件(错误、日志)。
询问用户:您的应用程序是否使用 Sentry Python SDK 或 Sentry Ruby SDK?
pip install "sentry-sdk[opentelemetry-otlp]"
OTLPIntegration 添加到现有的 sentry_sdk.init() 调用中,将 collector_url 设置为收集器的 OTLP 追踪端点:from sentry_sdk.integrations.otlp import OTLPIntegration
sentry_sdk.init(
dsn="___PUBLIC_DSN___",
integrations=[
OTLPIntegration(collector_url="http://localhost:4318/v1/traces"),
],
)
使用收集器的实际 OTLP HTTP 端点。如果在本地运行,默认为 http://localhost:4318/v1/traces。
gem "sentry-opentelemetry"
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-instrumentation-all"
2. 运行 bundle install
OpenTelemetry::SDK.configure do |c|
c.use_all
end
4. 在现有的 Sentry.init 块中启用 OTLP,将 collector_url 设置为收集器的 OTLP 追踪端点:
Sentry.init do |config|
config.dsn = "___PUBLIC_DSN___"
config.otlp.enabled = true
config.otlp.collector_url = "http://localhost:4318/v1/traces"
end
使用收集器的实际 OTLP HTTP 端点。如果在本地运行,默认为 http://localhost:4318/v1/traces。
| 错误 | 原因 | 修复 |
|---|---|---|
| "failed to create project" | 缺少 Project:Write 权限 | 在 Sentry 中更新内部集成权限 |
| "no team found" | 组织中无团队 | 在启用自动创建前,在 Sentry 中创建一个团队 |
| "invalid auth token" | 错误的令牌类型或已过期 | 使用内部集成令牌,而非用户认证令牌 |
| "connection refused" on 4317/4318 | 收集器未运行或端口冲突 | 检查收集器日志并确保端口可用 |
| Validation fails with env var errors | .env 文件未加载或占位符未替换 | 确保 .env 中有真实凭据且文件已被加载 |
| "container name already in use" | 先前容器存在 | 运行 docker stop otel-collector && docker rm otel-collector |
每周安装次数
177
仓库
GitHub 星标数
82
首次出现
2026年3月1日
安全审计
安装于
github-copilot175
opencode174
gemini-cli174
codex174
cursor174
amp173
All Skills > Feature Setup > 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.
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)
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:
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.
The Sentry Exporter requires otelcol-contrib v0.145.0 or later.
which otelcol-contrib to check if it's on PATH, or check for ./otelcol-contrib in the projectotelcol-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 |
Ask the user how they want to run the collector:
Fetch the latest release version from GitHub:
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 v prefix (e.g., v0.145.0). The download URL path requires the full tag with v 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:
uname -s and uname -m to detect OS and architecturedarwin_arm64darwin_amd64linux_amd64linux_arm64curl -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.
Wait for the user's response. Only delete if they explicitly choose to:
rm otelcol-contrib_<numeric_version>_<os>_<arch>.tar.gz
docker --versionv prefix):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.
Ask the user whether to enable automatic Sentry project creation. Do not recommend either option:
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.
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:
https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/example-config.yamlhttps://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/exporter/sentryexporter/docs/spec.mdUse WebFetch to retrieve the example config as a starting template. Reference the spec if the user needs advanced options not shown in the example.
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.
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.
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.
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:
SAY INSTEAD:
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:
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:
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:
myorg in https://myorg.sentry.io)auto_create_projectsEnsure the chosen .env file is in .gitignore.
After explaining how to get the values, ask the user to confirm when they've updated the .env file:
If user selects "Not yet", wait and ask again. Do not proceed to Step 6 until credentials are confirmed.
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).
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:
set -a && source "<env_file>" && set +a && "<collector_path>" validate --config "<config_file>"
Note : Docker volume mounts require absolute paths. If <config_file> or <env_file> are relative paths, prefix them with $(pwd)/. If they're already absolute paths, use them directly.
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:
Once validation passes , ask the user if they're ready to run the collector:
Wait for the user's confirmation before proceeding to Step 6.
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:
collector-config.yaml).env file the user selected)otelcol-contrib if on PATH, or ./otelcol-contrib if local)Load environment variables first , then run the collector:
set -a && source "<env_file>" && set +a && "<collector_path>" --config "<config_file>"
Note : Docker volume mounts require absolute paths. If <config_file> or <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:
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>
Use the same numeric version (without v 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.
Success criteria:
If using Docker, check logs with docker logs otel-collector.
If the user's application uses a Sentry SDK (Python or Ruby), 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 or Sentry Ruby SDK?
Docs: https://docs.sentry.io/platforms/python/integrations/otlp/
pip install "sentry-sdk[opentelemetry-otlp]"
OTLPIntegration to the existing sentry_sdk.init() call, setting collector_url to the collector's OTLP traces endpoint: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/ruby/integrations/otlp/
gem "sentry-opentelemetry"
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-instrumentation-all"
2. Run bundle install
OpenTelemetry::SDK.configure do |c|
c.use_all
end
4. Enable OTLP in the existing Sentry.init block, setting collector_url to the collector's OTLP traces endpoint:
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.
| 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 |
Weekly Installs
177
Repository
GitHub Stars
82
First Seen
Mar 1, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
github-copilot175
opencode174
gemini-cli174
codex174
cursor174
amp173
Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU
85,700 周安装
Nano Nets自动化指南:通过Rube MCP和Composio实现AI工作流自动化
1 周安装
Angular最佳实践指南:性能优化、变更检测与包大小优化
173 周安装
More Trees自动化工具包 - 通过Rube MCP实现Composio生态自动化操作
1 周安装
Mopinion自动化集成:通过Rube MCP和Composio实现反馈管理自动化
1 周安装
Mapbox自动化工具:通过Rube MCP和Composio实现地理信息系统自动化操作
1 周安装
Listclean自动化工具:通过Rube MCP和Composio实现高效数据清理
1 周安装