Skip to content

feat(astro): Auto-wire orchestrion build-time instrumentation #22830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chargome merged 7 commits into from
Jul 30, 2026
Merged

feat(astro): Auto-wire orchestrion build-time instrumentation #22830

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7b65f27
e2e
chargome Jul 29, 2026
f72aa25
sdk
chargome Jul 29, 2026
b172e5e
test(astro): Fix type-check failure in orchestrion deprecation test
chargome Jul 30, 2026
a87c813
Merge remote-tracking branch 'origin/develop' into cg/astro-orchest
chargome Jul 30, 2026
82cdcd2
docs(astro): Restore orchestrion wiring rationale comment lost in merge
chargome Jul 30, 2026
f0e65b4
test(e2e/astro): Run orchestrion e2e in dev mode too
chargome Jul 30, 2026
43b4301
Revert "test(e2e/astro): Run orchestrion e2e in dev mode too"
chargome Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions dev-packages/e2e-tests/test-applications/astro-7-orchestrion/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
import node from '@astrojs/node';
import sentry from '@sentry/astro';
import { sentryOrchestrionPlugin } from '@sentry/server-utils/orchestrion/vite';
// @ts-check
import { defineConfig } from 'astro/config';

Expand All @@ -18,9 +17,4 @@ export default defineConfig({
adapter: node({
mode: 'standalone',
}),
vite: {
// Run the orchestrion code transform on the Vite SSR bundle so instrumented
// DB drivers get `diagnostics_channel` publishers injected at build time.
plugins: [sentryOrchestrionPlugin()],
},
});
1 change: 0 additions & 1 deletion dev-packages/e2e-tests/test-applications/astro-7-orchestrion/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@
"@sentry-internal/test-utils": "link:../../../test-utils",
"@sentry/astro": "file:../../packed/sentry-astro-packed.tgz",
"@sentry/node": "file:../../packed/sentry-node-packed.tgz",
"@sentry/server-utils": "file:../../packed/sentry-server-utils-packed.tgz",
"astro": "^7.0.6",
"ioredis": "5.10.1",
"mysql": "^2.18.1"
Expand Down
2 changes: 1 addition & 1 deletion packages/astro/src/integration/cloudflare.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { builtinModules } from 'module';
// Derived from Astro's own config type rather than imported from `vite` directly: Astro bundles its
// own Vite version, which differs across the Astro majors we support. A plugin typed against any
// single Vite version is not assignable to `updateConfig({ vite: { plugins } })` for the others.
type VitePlugin = Extract<NonNullable<NonNullable<AstroConfig['vite']>['plugins']>[number], { name: string }>;
export type VitePlugin = Extract<NonNullable<NonNullable<AstroConfig['vite']>['plugins']>[number], { name: string }>;

// Build a set of all Node.js built-in module names, including both
// bare names (e.g. "fs") and "node:" prefixed names (e.g. "node:fs").
Expand Down
16 changes: 16 additions & 0 deletions packages/astro/src/integration/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
import { sentryVitePlugin } from '@sentry/bundler-plugins/vite';
import { sentryOrchestrionPlugin } from '@sentry/server-utils/orchestrion/vite';
import type { AstroConfig, AstroIntegration, AstroIntegrationLogger } from 'astro';
import * as fs from 'fs';
import { createRequire } from 'module';
import * as path from 'path';
import type { VitePlugin } from './cloudflare';
import { sentryCloudflareNodeWarningPlugin, sentryCloudflareVitePlugin } from './cloudflare';
import { buildClientSnippet, buildSdkInitFileImportSnippet, buildServerSnippet } from './snippets';
import type { SentryOptions } from './types';
Expand Down Expand Up @@ -34,6 +36,7 @@ export const sentryAstro = (options: SentryOptions = {}): AstroIntegration => {
sourcemaps,
// todo(v11): Extract `release` build time option here - cannot be done currently, because it conflicts with the `DeprecatedRuntimeOptions` type
// release,
buildTimeInstrumentation,
bundleSizeOptimizations,
applicationKey,
unstable_sentryVitePluginOptions,
Expand Down Expand Up @@ -167,6 +170,19 @@ export const sentryAstro = (options: SentryOptions = {}): AstroIntegration => {
const isCloudflare = config?.adapter?.name?.startsWith('@astrojs/cloudflare');
const isCloudflareWorkers = isCloudflare && !isCloudflarePages();

// Wire up the orchestrion code transform so instrumented server-side dependencies (e.g.
// `mysql`, `ioredis`) get `diagnostics_channel` publishers injected into the SSR bundle at
// build time, with no manual plugin setup. The plugin opts out internally when
// `buildTimeInstrumentation` is `false`.
// TODO: Cloudflare/workerd needs different wiring — skipped for now.
if (sdkEnabled.server && !isCloudflare) {
updateConfig({
vite: {
plugins: [sentryOrchestrionPlugin({ buildTimeInstrumentation }) as VitePlugin],
},
});
}
Comment on lines +178 to +184

@sentry sentry Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The orchestrion plugin is unconditionally injected in dev mode, causing its config() hook to add ssr.noExternal settings, which unnecessarily bundles packages and degrades performance.
Severity: MEDIUM

Suggested Fix

Wrap the updateConfig call for the orchestrion plugin in a condition that checks if the Astro command is not 'dev', similar to how the sourcemaps plugin is handled. This will prevent the plugin from being injected and its config() hook from running during development.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: packages/astro/src/integration/index.ts#L178-L184

Potential issue: The Sentry orchestrion plugin is injected unconditionally when
`sdkEnabled.server` is true, without checking if the Astro command is `dev`. While the
plugin's `applyToEnvironment` hook prevents code transformations, its `config()` hook
still executes. This hook injects `ssr.noExternal` configurations into the Vite config
during development. As a result, Vite is forced to bundle server-side packages (e.g.,
`mysql`, `ioredis`) that are not needed for the dev server, leading to degraded
performance. This affects all users running the Astro dev server with the default Sentry
integration settings.

Did we get this right? 👍 / 👎 to inform future reviews.

@chargome chargome Jul 30, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why would they not be needed for dev?

@chargome chargome Jul 30, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

adding a test


if (isCloudflare) {
try {
const _require = createRequire(`${process.cwd()}/`);
Expand Down
127 changes: 119 additions & 8 deletions packages/astro/test/integration/index.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,26 @@ vi.mock('@sentry/bundler-plugins/vite', () => ({
sentryVitePlugin: vi.fn(args => sentryVitePluginSpy(args)),
}));

// Stub the orchestrion plugin so these stay pure wiring tests (no apm code transformer pulled in).
// Mirror the real plugin's contract: `buildTimeInstrumentation: false` yields the inert variant.
const orchestrionVite = vi.fn((options?: { buildTimeInstrumentation?: boolean }) => ({
name: options?.buildTimeInstrumentation === false ? 'sentry-orchestrion-disabled' : 'sentry-orchestrion-vite',
}));
vi.mock('@sentry/server-utils/orchestrion/vite', () => ({
sentryOrchestrionPlugin: (options?: { buildTimeInstrumentation?: boolean }) => orchestrionVite(options),
}));

// The cloudflare adapter path resolves `@sentry/cloudflare` via `createRequire` and calls
// `process.exit(1)` when it's missing. Stub the resolver so it always "finds" the package,
// keeping these tests hermetic regardless of what's installed in `node_modules`.
vi.mock('module', async requireActual => {
const actual = await requireActual<any>();
return {
...actual,
createRequire: () => ({ resolve: () => '@sentry/cloudflare' }),
};
});

process.env = {
...process.env,
SENTRY_AUTH_TOKEN: 'my-token',
Expand All @@ -23,7 +43,7 @@ const config = {
} as AstroConfig;

const baseConfigHookObject = {
logger: { warn: vi.fn(), info: vi.fn() },
logger: { warn: vi.fn(), info: vi.fn(), error: vi.fn() },
addMiddleware: vi.fn(),
};

Expand All @@ -46,7 +66,8 @@ describe('sentryAstro integration', () => {
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ ...baseConfigHookObject, updateConfig, injectScript, config });

expect(updateConfig).toHaveBeenCalledTimes(1);
// one call for the sourcemaps vite plugin, one for the orchestrion plugin
expect(updateConfig).toHaveBeenCalledTimes(2);
expect(updateConfig).toHaveBeenCalledWith({
vite: {
build: {
Expand All @@ -55,6 +76,11 @@ describe('sentryAstro integration', () => {
plugins: ['sentryVitePlugin'],
},
});
expect(updateConfig).toHaveBeenCalledWith({
vite: {
plugins: [{ name: 'sentry-orchestrion-vite' }],
},
});

expect(sentryVitePluginSpy).toHaveBeenCalledTimes(1);
expect(sentryVitePluginSpy).toHaveBeenCalledWith(
Expand Down Expand Up @@ -294,7 +320,13 @@ describe('sentryAstro integration', () => {
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ ...baseConfigHookObject, updateConfig, injectScript, config });

expect(updateConfig).toHaveBeenCalledTimes(0);
// only the orchestrion plugin is wired, no sourcemaps plugin
expect(updateConfig).toHaveBeenCalledTimes(1);
expect(updateConfig).toHaveBeenCalledWith({
vite: {
plugins: [{ name: 'sentry-orchestrion-vite' }],
},
});
expect(sentryVitePluginSpy).toHaveBeenCalledTimes(0);
});

Expand All @@ -307,7 +339,13 @@ describe('sentryAstro integration', () => {
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ ...baseConfigHookObject, updateConfig, injectScript, config });

expect(updateConfig).toHaveBeenCalledTimes(0);
// only the orchestrion plugin is wired, no sourcemaps plugin
expect(updateConfig).toHaveBeenCalledTimes(1);
expect(updateConfig).toHaveBeenCalledWith({
vite: {
plugins: [{ name: 'sentry-orchestrion-vite' }],
},
});
expect(sentryVitePluginSpy).toHaveBeenCalledTimes(0);
});

Expand All @@ -318,11 +356,12 @@ describe('sentryAstro integration', () => {
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ ...baseConfigHookObject, updateConfig, injectScript, config });

expect(updateConfig).toHaveBeenCalledTimes(1);
// one call for the sourcemaps vite plugin, one for the orchestrion plugin
expect(updateConfig).toHaveBeenCalledTimes(2);
expect(sentryVitePluginSpy).toHaveBeenCalledTimes(1);
});

it("doesn't add the Vite plugin in dev mode", async () => {
it("doesn't add the sourcemaps Vite plugin in dev mode", async () => {
const integration = sentryAstro({
sourceMapsUploadOptions: { enabled: true },
});
Expand All @@ -337,7 +376,13 @@ describe('sentryAstro integration', () => {
command: 'dev',
});

expect(updateConfig).toHaveBeenCalledTimes(0);
// the sourcemaps plugin is skipped in dev, but the orchestrion plugin is still wired
expect(updateConfig).toHaveBeenCalledTimes(1);
expect(updateConfig).toHaveBeenCalledWith({
vite: {
plugins: [{ name: 'sentry-orchestrion-vite' }],
},
});
expect(sentryVitePluginSpy).toHaveBeenCalledTimes(0);
});

Expand All @@ -348,12 +393,78 @@ describe('sentryAstro integration', () => {

expect(integration.hooks['astro:config:setup']).toBeDefined();
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ updateConfig, injectScript, config });
await integration.hooks['astro:config:setup']({ ...baseConfigHookObject, updateConfig, injectScript, config });

// neither the sourcemaps nor the orchestrion plugin should be wired
expect(updateConfig).toHaveBeenCalledTimes(0);
expect(orchestrionVite).not.toHaveBeenCalled();
expect(sentryVitePluginSpy).toHaveBeenCalledTimes(0);
});

it('adds the orchestrion plugin by default', async () => {
const integration = sentryAstro({});

expect(integration.hooks['astro:config:setup']).toBeDefined();
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ ...baseConfigHookObject, updateConfig, injectScript, config });

expect(orchestrionVite).toHaveBeenCalledWith({ buildTimeInstrumentation: undefined });
expect(updateConfig).toHaveBeenCalledWith({
vite: {
plugins: [{ name: 'sentry-orchestrion-vite' }],
},
});
});

it('adds an inert orchestrion plugin when `buildTimeInstrumentation` is `false`', async () => {
const integration = sentryAstro({ buildTimeInstrumentation: false });

expect(integration.hooks['astro:config:setup']).toBeDefined();
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ ...baseConfigHookObject, updateConfig, injectScript, config });

expect(orchestrionVite).toHaveBeenCalledWith({ buildTimeInstrumentation: false });
expect(updateConfig).toHaveBeenCalledWith({
vite: {
plugins: [{ name: 'sentry-orchestrion-disabled' }],
},
});
});

it("doesn't add the orchestrion plugin for the cloudflare adapter", async () => {
const integration = sentryAstro({});

const cloudflareConfig = { ...config, adapter: { name: '@astrojs/cloudflare' } } as AstroConfig;

expect(integration.hooks['astro:config:setup']).toBeDefined();
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({
...baseConfigHookObject,
updateConfig,
injectScript,
config: cloudflareConfig,
});

expect(orchestrionVite).not.toHaveBeenCalled();
expect(updateConfig).not.toHaveBeenCalledWith({
vite: {
plugins: [{ name: 'sentry-orchestrion-vite' }],
},
});
});

it("doesn't warn about deprecated options when `buildTimeInstrumentation` is set", async () => {
const integration = sentryAstro({ buildTimeInstrumentation: false });

const logger = { warn: vi.fn(), info: vi.fn() };

expect(integration.hooks['astro:config:setup']).toBeDefined();
// @ts-expect-error - the hook exists and we only need to pass what we actually use
await integration.hooks['astro:config:setup']({ updateConfig, injectScript, config, logger });

expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('buildTimeInstrumentation'));
});

it.each([{}, { enabled: true }])('injects client and server init scripts', async options => {
const integration = sentryAstro(options);

Expand Down
Loading