Sentry init on AWS Lamba environment

[caiorhian]

Hey guys, does anyone know why we need to load the SDK through NODE_OPTIONS="--import ./instrument.js"?

Previously, I was used to just call Sentry.init on the first line after imports of my handler.

Does that still work, or should I move to this new recommendation?

[MILLERMARRU]

Calling Sentry.init() as the first line after your imports still runs, but by that point it's already too late for what v8 needs it to do. The requirement isn't stylistic, it's a hard constraint from OpenTelemetry: auto-instrumentation works by patching require/import itself so that when a module gets loaded, Sentry's wrapped version is what actually gets returned. That patching has to be in place before the module is loaded at all, once your handler file's own import statements at the top have already executed (which happens before any code in the file body runs, including your Sentry.init() call on "the first line after imports"), those modules are already the real, unpatched versions. Auto-instrumentation for aws-sdk, http, pg, or whatever else your handler pulls in at the top of the file silently doesn't work, even though Sentry.init() technically still runs and captures errors/manual spans fine.

That's exactly why the recommendation moved to a separate instrument.js loaded via NODE_OPTIONS="--import ./instrument.js", that flag guarantees Sentry initializes and patches the module loader before your handler file (and therefore before any of its imports) gets evaluated at all, there's no code path in Node's module resolution that runs earlier.

So: your old pattern still "works" in the sense that manual Sentry.captureException() calls and anything not dependent on auto-instrumentation continues to function. What silently breaks is auto-instrumented spans/breadcrumbs for whatever your handler imports above the Sentry.init() line, database calls, HTTP requests made via instrumented clients, etc. If you're not relying on that automatic instrumentation and only want manual error capture, you can probably get away with the old pattern a while longer, but you're leaving most of what v8's tracing improvements are for on the table, and it's likely to keep drifting further from what the SDK's newer features assume as versions move forward. Moving to the --import pattern is the safer bet if you want tracing to actually reflect what your Lambda is doing.