sentry-otel-exporter-setup

Original：🇺🇸 English
Translated

Configure the OpenTelemetry Collector with Sentry Exporter for multi-project routing and automatic project creation. Use when setting up OTel with Sentry, configuring collector pipelines for traces and logs, or routing telemetry from multiple services to Sentry projects.

2installs
Sourcejaffrepaul/agent-skills
Added on

NPX Install

npx skill4agent add jaffrepaul/agent-skills sentry-otel-exporter-setup

Tags

Translated version includes tags in frontmatter
opentelemetry-collectorsentry-exportertelemetry-routingauto-project-creationdevops-monitoring

SKILL.md Content

View Translation Comparison →

Sentry OTel Exporter Setup

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.

Step 1: Choose Installation Method

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."

Binary Installation

The Sentry exporter is included in otelcol-contrib v0.145.0+.
Detect the user's platform and download the binary for them:
  1. Run 
    uname -s
    and 
    uname -m
    to detect OS and architecture
  2. Map to release values:
    • Darwin + arm64 → 
      darwin_arm64
    • Darwin + x86_64 → 
      darwin_amd64
    • Linux + x86_64 → 
      linux_amd64
    • Linux + aarch64 → 
      linux_arm64
  3. 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.

Docker Installation

  1. Verify Docker is installed by running 
    docker --version
  2. 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.

Step 2: Configure Project Creation

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.

Step 3: Write Collector Config

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.

Add Debug Exporter (Recommended)

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.

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.

Step 4: Set Up Credentials

Create an Internal Integration in Sentry to get an auth token:
  1. Go to Settings → Developer Settings → Custom Integrations
  2. Click Create New Integration → Choose Internal Integration
  3. Set permissions:
    • Organization: Read — required
    • Project: Read — required
    • Project: Write — required for 
      auto_create_projects
  4. 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
.

Step 5: Run the Collector

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

Binary

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