Configuration

Core options that all SDKs MUST or SHOULD support:

Sentry SDKs SHOULD support a set of common environment variables that allow users to configure SDK behavior without modifying their code. This is particularly useful for containerized deployments, serverless environments, or when users need to adjust settings without redeploying their application.

The following environment variables SHOULD be supported across Sentry server-side SDKs:

SDKs MAY support additional SDK-specific environment variables beyond this common set. Any additional environment variables SHOULD be documented in the SDK's user-facing documentation.

Precedence

When both environment variables and code-based configuration are present, code-based configuration MUST take precedence. If the user explicitly passes a value to the SDK's init function, the environment variable MUST be ignored.

To use environment variables, users omit the option from their init call and the SDK reads from the environment automatically:

// SDK will read from SENTRY_DSN automatically
Sentry.init({
  // dsn omitted, will use SENTRY_DSN
});

Client-Side Considerations

Environment variables work differently in client-side environments like web browsers, where the concept of environment variables doesn't exist at runtime. For frontend SDKs, values MUST be injected by users at build time or configured directly in code.

For server-side SDKs (Node.js, Python, Ruby, Java, .NET, Go, PHP, etc.), environment variables are read at runtime when the SDK initializes.

Every SDK must implement a debug mode, which is disabled by default. Users can enable it by setting the option debug to true. If the debug mode is enabled, the SDK prints out useful debugging information for two main purposes:

1. It helps users identify and fix SDK problems, such as misconfigurations or something going wrong with sending data to Sentry.
2. It can help Sentry SDK engineers investigate issues in Sentry SDKs, which can be done while developing or by asking a user to enable the debug mode and share the debug logs.

As the log output can add unnecessary overhead, we advise users to refrain from enabling the debug mode in production. Still, SDKs may log fatal error messages even when the debug mode is disabled. When using debug mode extensively for the second use case, we recommend adding the diagnostic level because users could easily miss error or fatal log messages.

Diagnostic Level

SDKs may offer an optional diagnostic level, which controls the verbosity of the debug mode. There are five different levels:

• debug: The most verbose mode
• info: Informational messages
• warning: Warning that something might not be right
• error: Only SDK internal errors are printed
• fatal: Only critical errors are printed

The default level can be debug or error depending on the SDK's usage of log messages. When the volume of log message is low, the default can be debug. When it is high, users might easily miss errors or fatal messages. In that case, the SDK should set the default level to error. This choice must be clearly documented in the user-facing docs.

Auto Debug Mode

So users can easily spot errors during development, the SDK can automatically enable debug mode when it reliably detects it's running in a debug build. When doing so, the SDK must communicate this in the docs and with a log message when initializing the SDK. When the user explicitly sets the debug option to false, the SDK must disable the debug mode.

SDKs should allow the user to configure what percentage of events are actually sent to the server (the rest should be silently ignored). For example:

sample_rate = options.get('sample_rate', 1.0)

# assuming random() returns a value between 0.0 (inclusive) and 1.0 (exclusive)
if random() < sample_rate:
    transport.capture_event(event)

To further simplify ignoring certain events from being sent to sentry, it is also suggested to provide ignoreTransactions and ignoreErrors (or exception, choose terminology which is best for the platform). The array for ignoreTransactions specifically should contain an array of transaction names, as is stored in the transaction event schema (ie GET /info). These options should provide a simple way to allow users to discard events (ignore) from before they are sent to sentry. Prevents sending data which is undesired and may consume quota or resources on the Sentry server.

ignore_transactions = ['GET /api/health','/api/v1/*']

Server SDKs SHOULD support attaching the incoming HTTP request body to events. The max_request_body_size option controls the maximum body size the SDK will attach. The SDK defines the actual byte thresholds for each setting:

Some logging frameworks provide an option to set logging context. In Java this is called MDC (Mapped Diagnostic Context).

SDKs that integrate with platform logging frameworks SHOULD support a context_tags configuration option. This option accepts a list of logging context keys whose values the SDK converts to Sentry tags on captured events.

sentry_sdk.init(
    context_tags=["request_id", "tenant"],
)