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: Check for Existing Configuration

Before creating anything, search for existing OpenTelemetry Collector configs:

# Search for common collector config file patterns
find . -name "*.yaml" -o -name "*.yml" | xargs grep -l "receivers:" 2>/dev/null

Also check for files named otel-collector-config.*, collector-config.*, or otelcol.*.

If an existing config is found: Ask the user if they want to modify it to add the Sentry exporter, or create a separate config file. Prefer editing the existing file to avoid duplicates.

If no config exists: Proceed to create a new collector-config.yaml.

Step 2: 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:

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:

docker pull otel/opentelemetry-collector-contrib:0.145.0

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

Step 3: 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 4: Write Collector Config

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.

If editing an existing config

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.

If creating a new config

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.

Add Debug Exporter (Recommended)

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.

Step 5: 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:

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 created above

Ensure the chosen .env file is in .gitignore.

Step 6: Run the Collector

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

Binary

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

Docker

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