/sentry-otel-exporter-setup

name: sentry-otel-exporter-setup
description: 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.
license: Apache-2.0

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.

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)

Step 1: Check for Existing Configuration

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.

Step 2: Check Collector Version

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

Check for existing collector

1. Run `which otelcol-contrib` to check if it’s on PATH, or check for `./otelcol-contrib` in the project 2. If found, run the appropriate version command and parse the version number 3. **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 |

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.

Binary Installation

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:

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

4. **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:

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

Docker Installation

1. Verify Docker is installed by running `docker --version` 2. Fetch the latest release tag from GitHub (same as above) 3. Pull the image using the numeric version (without `v` 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.

Step 3: Configure Sentry Project Creation

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.

Step 4: Write Collector Config

**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.githubuserconte