rfc(feature): Capture SDK options [WIP]

[mydea]

WIP — draft RFC, still in progress.

Proposes a mechanism for SDKs to report the configuration they were initialized with (the arguments passed to Sentry.init(), plus relevant derived/effective values) to Sentry, so it can be stored, surfaced, and acted upon.

Linear project: https://linear.app/getsentry/project/capture-sdk-options-js-08e8a89c71c9/overview

Rendered RFC

🤖 Generated with Claude Code

[stephanie-anderson]

Reads repetitive to the content above

[stephanie-anderson]

Should these not be objects, so we can also track who/what set the respective options? (default value vs. user defined but potentially matching with the default etc).

So a config like

Sentry.init({
  dsn: "foo",
  tracesSampleRate: 0.2
});

would lead to something like

    # implied config
    "sampleRate": {
        "value": 1.0,
        "default": 1.0,
        "init": false
    },
    # explicit config
    "tracesSampleRate": {
        "value": 0.2,
        "default": 1.0,
        "init": true
    }

naming tbd

[stephanie-anderson]

Or would the idea be to have the defaults in integration_options?

[stephanie-anderson]

On second thought

"init": false

should probably be

"source": "init"    # or "default", "env-var"

[mydea]

this should all only be user-defined stuff. defaults should not be reflected here - but this should likely be actually explained in the text :D

[dingsdax]

defaults should not be reflected here

I'm torn about this. Do we want to answer “what did the user explicitly configure?” or “what configuration is this SDK running with?” user overrides are enough for the former. For debugging/setup audits, resolved defaults matter too, and reconstructing them server-side requires SDK/version-specific resolution logic: Ruby and Python already merge defaults with user configuration for instance.

[mydea]

From my POV, most things I can think about that we'd want to do could be solved via user-provided options only IMHO. And it would likely drastically reduce complexity (and likely payload size) - way easier to send the user provided options than to have a good hook that ensures all defaults are properly set etc, while also maintaining a way to know which are defaults and which are not. I would consider implementation complexity as a relevant factor here - IMHO we should have a good case for why we want to capture defaults. If we decide we want to capture defaults as well, I think I'd rather opt to capture them separately (e.g, default_options) instead of requiring us to merge this somehow into a specific object shape at runtime.

To show the challenge, this is how this is most of the time handled today:

export function init(options: BrowserOptions): Client | undefined {
  const opts = {
   // add defaults, transform stuff, etc.
    ...options,
  };

  applySdkMetadata(opts, 'react');
  const client = browserInit(opts);

  return client;
}

If we capture only user provided options, it is basically captureSdkOptions(options). If we need to consider defaults, we need to somehow pass it both the final options, and have some logic that reliably diffs the passed in options from the final options, which is possible of course but considerably more complicated likely. Not saying that blocks this, but just as additional context :)

[dingsdax]

> I think I'd rather opt to capture them separately (e.g, default_options)

yes that was my point, if we do that, let's separate, but I can see that being valuable and easier than somehow reconstructing on the server side what could have been the default at that point of time

[stephanie-anderson]

I disagree, I don't think every SDK should send their own config option names, but we should instead focus on a protocol that each SDK implements against. Even if it means they need to map tracesSampleRate to traces_sample_rate or the other way around.

This is especially important since not all SDKs even have the same configuration structure, e.g. where and how integrations get enabled. So at one point we need to align, and I'd rather have that on the protocol level than forcing the server to know about all constellations.

[mydea]

but a lot of options will not exist in other sdks. so you'll have to maintain a map of fields to map in each sdk, which is complexity and bundle size in SDK. imho it would be nicer to handle this on the sentry side. Also, you'll get a mix-and-match of unified and non-unified fields. (I would guess a good amount of options are non-standard between sdks).

[mydea]

some additional thoughts on this: standardizing this sdk-side is both considerable overhead (both in complexity and in size), and also has the problem that it is not really understandable for users later. e.g. let's say we show a user what sample rate they configured, would we show a js user "you configured trace_sample_rate: 0.1"? this is much easier if we send this in the way that the user also set it.

If we need this, I'd rather have us do this in relay. We could define the options that are relevant for us and e.g. populate a standardized_options object in relay based on the options into a format that we want. This way, we'd have access to both the values as the user set it, as well as to a standardized format where we need it.

In regard to where and how config is set - this should not be relevant for the format, no matter where exactly this is set, it should all fold into this option. So e.g. if a user does:

Sentry.init({
  dsn: 'x'
});
Sentry.addIntegration(Sentry.customIntegration());

it should result in the same object being sent as:

Sentry.init({
  dsn: 'x',
  integrations: [Sentry.customIntegration()]
})

for simplicity and consistency sake.

[stephanie-anderson]

If we go for release we could still end up with many different init constellations because of options passed in by ENV vars

[dingsdax]

this

[stephanie-anderson]

a hash of the normalized options

I like this one the most. We could even attach this hash with to other payloads we send out (e.g. events, transaction, so we can ultimately achieve the connect that Dave was envisioning).

[mydea]

I think we could do this, it also comes down a bit to product stuff as well - if we dedupe it by release (or similar), we can also leverage this restriction in product much easier. e.g. "This config was introduced in release X". If we dedupe it by options hash, and there can be multiple per release, this becomes much harder to handle in UI too (e.g. This config was introduced in some instance of release X??").

My POV is that I would imagine that a per-release or similar (maybe a combination of keys, e.g. release+env or similar) deduping is probably good enough for 98% of cases of so and allows us to make some easier to handle assumptions in product etc. Also likely it is less overhead at ingest, but this is probably not too important I imagine. We can then also easily attach each event to some config based on the release.

So my concern is, doing this on a hash basis is technically correct and covers all cases, but also leads us to have to handle the most-complicated edge cases everywhere all the time then. Not sure if this is worth it 🤔

[dingsdax]

why only server-side?

[mydea]

simplicity? I'd like to keep this as low-overhead in sdks as possible. There should not be too much really sensitive in there IMHO (can't think of many sensitive things in sdk config from the top of my head?), if we know of things that are always sensitive we can of course omit them sdk side, but could not come up with anything so far.

[dingsdax]

yeah, would need to look at each SDK separately, but I could images we might do some weird merging shit in some SDKs, where sensitive information shows up in the config all of a sudden at the point of export 🙂

[dingsdax]

Could SDK/framework lifecycle hooks be preferred where available, with debounce as a fallback?
For instance Rails modifies configuration and activates instrumentation in after_initialize, after Sentry.init; a fixed delay can fire before that finishes.
How about "Let each SDK choose an appropriate readiness point and include pending reports in existing flush/shutdown handling"?

[mydea]

yes, def. I can reword this to be more explicit on this! debounce is the most primitive form. the key should be that we consider stuff that happens right after init too and not just send this inside of the init() function or whatever.

[dingsdax]

just mentioning it here:

a new item type might need: rate-limit category, payload limits, and compatibility behavior or decisions for older Relay/self-hosted versions? e.g. Ruby and Python currently classify unknown item types as default, so these semantics need an explicit decision. Would add something like "Capturing SDK options should honor SDK sending restrictions, use existing transport/flush mechanisms, and fail without affecting application behavior." for completeness

[mydea]

good point, we need to consider how this works/degrades on self-hosted versions that do not support this too.

[dingsdax]

I get "enableLogs" PTSD here :).

Could we separate successful instrumentation from observed usage rather than call both “active”? We could derive usage server-side where telemetry identifies the integration, recording last_seen and evaluating it over a defined window. Maybe I'm oversimplifying here if that is possible at all. Absence would mean “not observed,” not inactive. That would leave SDK reporting focused on registration and, optionally, whether instrumentation was successfully installed.

[mydea]

hmmm not 100% sure what you mean? If there is a signal already captured to infer usage, we can already solve this today. The problem we have is that we don't necessarily have such a signal today in JS. We do know if a certain package was instrumented at all, and I'd like to include this information somehow. IMHO "this library was instrumented" should be safe to rely on as a data point.

maybe "active" is not a good wording here 🤔 we can call it "is_instrumenting" or something along these lines too?

I would prefer to keep this atomic in "this is sent and never updated" vs. having some background tasks that have to update the config as things come in, that defeats the idea of this being simple and low-overhead 😅

[dingsdax]

I see, read it again and look at the snippet, I somehow mixed that up with a top-level option, all good, I understand what you mean here.

[dingsdax]

this feels like a non-option to me:
missing data must mean “not observed,” not “disabled” or “unused,” particularly if we want to inform setup audits or deprecation decisions for instance.

intuition is that configuration is essentially constant per release
I don't think this is true. Configuration can change independently of releases: the same release may run as web and background-worker processes with different settings, or be restarted with updated ENV vars. variables.

[mydea]

yeah, release alone is likely not good enough. I wonder/hope we could come up with a combination of keys that we can agree on define a unified config. Then there may obviously be some edge cases that still don't follow this but if we get to a 99% case of coverage, I think it would help us streamline assumptions, UI, etc. around this.

E.g.

• release + environment

What are common cases we can think of where init option would vary above that? 🤔 When would you restart the same process with different env vars (that are relevant for sentry?) Commonly you look at environment, of course. (And not saying it can never happen, but does it happen often enough and even if it happens, how problematic is it if we miss that here or there)

[dingsdax]

but then again, this is probably an edge case anyway