receivers:

otel-collector-config.*

collector-config.*

otelcol.*

• 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

collector-config.yaml

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

• Binary: Download from GitHub releases. No Docker required.
• Docker: Run as a container. Requires Docker installed.

curl -s https://api.github.com/repos/open-telemetry/opentelemetry-collector-releases/releases/latest | grep '"tag_name"' | cut -d'"' -f4

v

v0.145.0

v

0.145.0

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

v0.145.0

v0.145.0

0.145.0

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

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

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>

v0.145.0

docker pull otel/opentelemetry-collector-contrib:0.145.0

docker run

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

• 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

• “Let me add the environment variables”
• “I’ll add the credentials to your .env”
• “Adding the Sentry auth token”

• “I’ll add placeholder environment variables for you to fill in”
• “Adding placeholder values—you’ll replace these with your actual credentials”
• “I’ll set up the env var keys with placeholder values”

.env

**/.env

• [path to discovered .env file]: Add to existing file (list each discovered path)
• Create new at root: Create .env in project root

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

1. Sentry org slug: In Sentry, go to Settings → Organization Settings → Organization Slug. This is also your subdomain (e.g.,

   myorg

   in

   https://myorg.sentry.io

   )
2. Sentry auth token: Create an Internal Integration in Sentry:
   • In Sentry, 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 only if using

       auto_create_projects

   • Save, then click Create New Token and copy it

.env

.gitignore

.env

• Yes, credentials are set: Proceed to validate and run the collector
• Not yet: I’ll wait while you update the .env file

<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

.env

1. Review the error message carefully
2. Fix the issues in the config file
3. Run validation again
4. Repeat until validation passes

• Yes, run it now: Proceed to Step 6 and start the collector
• Not yet: Wait. The user may want to review the config or prepare their environment first.

• Config file: From Step 1 (existing config or new

  collector-config.yaml

  )
• Env file: From Step 5 (the

  .env

  file the user selected)
• Collector path: From Step 2 (either

  otelcol-contrib

  if on PATH, or

  ./otelcol-contrib

  if local)

1. Check collector logs for successful startup (no errors about invalid config or failed connections)
2. Look for log messages indicating connection to Sentry
3. Send test telemetry from an instrumented service and verify it appears in Sentry

• Collector starts without errors
• Traces and/or logs appear in Sentry within 60 seconds of sending

docker logs otel-collector

• Python: Follow the Python setup below
• Ruby: Follow the Ruby setup below
• Node.js: Follow the Node.js setup below
• Neither / Other SDK: Skip this step. Trace connectedness via OTLPIntegration is currently available for Python, Ruby, and Node.js.

1. Install the extra:

pip install "sentry-sdk[opentelemetry-otlp]"

1. Add the

   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"),
    ],
)

http://localhost:4318/v1/traces

1. Add gems to the Gemfile:

gem "sentry-opentelemetry"
gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"
gem "opentelemetry-instrumentation-all"

1. Run

   bundle install

2. Configure OpenTelemetry instrumentation:

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

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

http://localhost:4318/v1/traces

1. Install the lightweight Sentry SDK and OpenTelemetry dependencies:

npm install @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

1. Create an instrument file (

   instrument.mjs

   ) that sets up OTel and Sentry together:

import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node-core/light';
import { otlpIntegration } from '@sentry/node-core/light/otlp';

const provider = new NodeTracerProvider();
provider.register();

Sentry.init({
  dsn: '___PUBLIC_DSN___',
  integrations: [
    otlpIntegration({
      collectorUrl: 'http://localhost:4318/v1/traces',
    }),
  ],
});

1. Start your app with the

   --import

   flag:

node --import ./instrument.mjs app.mjs

http://localhost:4318/v1/traces

Do not set

tracesSampleRate

when using

otlpIntegration

— OTel controls sampling. Setting it would conflict with the OTLP path.