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:
After explaining how to get the values, ask the user to confirm when they've updated the
.env
file:
Yes, credentials are set
Proceed to validate and run the collector
Not yet
I'll wait while you update the .env file
If user selects "Not yet", wait and ask again. Do not proceed to Step 6 until credentials are confirmed.
Validate config
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
).
Binary validation
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
""
&&
set
+a
&&
""
validate
--config
""
Docker validation
Note
Docker volume mounts require absolute paths. If
or
are relative paths, prefix them with
$(pwd)/
. If they're already absolute paths, use them directly.
docker
run
--rm
\
-v
""
:/etc/otelcol-contrib/config.yaml
\
--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:
Review the error message carefully
Fix the issues in the config file
Run validation again
Repeat until validation passes
Once validation passes
, ask the user if they're ready to run the collector:
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.
Wait for the user's confirmation before proceeding to Step 6.
Step 6: Run the Collector
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:
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)
Binary
Load environment variables first
, then run the collector:
set
-a
&&
source
""
&&
set
+a
&&
""
--config
""
Docker
Note
Docker volume mounts require absolute paths. If
or
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
""
:/etc/otelcol-contrib/config.yaml
\
--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.
Step 7: Verify Setup
Check collector logs for successful startup (no errors about invalid config or failed connections)
Look for log messages indicating connection to Sentry
Send test telemetry from an instrumented service and verify it appears in Sentry
Success criteria:
Collector starts without errors
Traces and/or logs appear in Sentry within 60 seconds of sending
If using Docker, check logs with
docker logs otel-collector
.
Step 8: Enable Trace Connectedness with OTLPIntegration
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?
Python
Follow the Python setup below
Ruby
Follow the Ruby setup below
Neither / Other SDK
Skip this step. Trace connectedness via OTLPIntegration is currently available for Python and Ruby.
Python OTLPIntegration
Docs:
https://docs.sentry.io/platforms/python/integrations/otlp/
Install the extra:
pip
install
"sentry-sdk[opentelemetry-otlp]"
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
=
"PUBLICDSN"
,
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.
Ruby OTLPIntegration
Docs:
https://docs.sentry.io/platforms/ruby/integrations/otlp/
Add gems to the Gemfile:
gem
"sentry-opentelemetry"
gem
"opentelemetry-sdk"
gem
"opentelemetry-exporter-otlp"
gem
"opentelemetry-instrumentation-all"
Run
bundle install
Configure OpenTelemetry instrumentation:
OpenTelemetry
::
SDK
.
configure
do
|
c
|
c
.
use_all
end
Enable OTLP in the existing
Sentry.init
block, setting
collector_url
to the collector's OTLP traces endpoint:
Sentry
.
init
do
|
config
|
config
.
dsn
=
"PUBLICDSN"
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.
Troubleshooting
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