diff --git a/docs/platforms/javascript/common/install/index.mdx b/docs/platforms/javascript/common/install/index.mdx index bdf4d7e8bb89a..77f725f7f98cc 100644 --- a/docs/platforms/javascript/common/install/index.mdx +++ b/docs/platforms/javascript/common/install/index.mdx @@ -27,6 +27,7 @@ notSupported: - javascript.azure-functions - javascript.gcp-functions - javascript.cloudflare + - javascript.elysia - javascript.react-router - javascript.tanstackstart-react --- diff --git a/docs/platforms/javascript/common/install/loader.mdx b/docs/platforms/javascript/common/install/loader.mdx index 38826dafe93d9..c309a26b23e13 100644 --- a/docs/platforms/javascript/common/install/loader.mdx +++ b/docs/platforms/javascript/common/install/loader.mdx @@ -26,6 +26,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/install/npm.mdx b/docs/platforms/javascript/common/install/npm.mdx index e1992f885ff1c..689dbd590b328 100644 --- a/docs/platforms/javascript/common/install/npm.mdx +++ b/docs/platforms/javascript/common/install/npm.mdx @@ -27,6 +27,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/session-replay/configuration.mdx b/docs/platforms/javascript/common/session-replay/configuration.mdx index 94f6a6a445cdd..87aa55f0ca9eb 100644 --- a/docs/platforms/javascript/common/session-replay/configuration.mdx +++ b/docs/platforms/javascript/common/session-replay/configuration.mdx @@ -10,6 +10,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/session-replay/index.mdx b/docs/platforms/javascript/common/session-replay/index.mdx index 28f958dc6d550..649bb1279153e 100644 --- a/docs/platforms/javascript/common/session-replay/index.mdx +++ b/docs/platforms/javascript/common/session-replay/index.mdx @@ -12,6 +12,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/session-replay/issue-types.mdx b/docs/platforms/javascript/common/session-replay/issue-types.mdx index 0c36be8e4b7f2..ce80325ddf490 100644 --- a/docs/platforms/javascript/common/session-replay/issue-types.mdx +++ b/docs/platforms/javascript/common/session-replay/issue-types.mdx @@ -10,6 +10,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/session-replay/privacy.mdx b/docs/platforms/javascript/common/session-replay/privacy.mdx index 92932b2ed3de6..4c304d3bd480a 100644 --- a/docs/platforms/javascript/common/session-replay/privacy.mdx +++ b/docs/platforms/javascript/common/session-replay/privacy.mdx @@ -10,6 +10,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/session-replay/troubleshooting.mdx b/docs/platforms/javascript/common/session-replay/troubleshooting.mdx index 1a70d484e3825..0f06eb52c24f7 100644 --- a/docs/platforms/javascript/common/session-replay/troubleshooting.mdx +++ b/docs/platforms/javascript/common/session-replay/troubleshooting.mdx @@ -10,6 +10,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx b/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx index 0fd59f0a7cb4c..b0a50068181fa 100644 --- a/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx +++ b/docs/platforms/javascript/common/session-replay/understanding-sessions.mdx @@ -10,6 +10,7 @@ notSupported: - javascript.aws-lambda - javascript.azure-functions - javascript.connect + - javascript.elysia - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/guides/elysia/index.mdx b/docs/platforms/javascript/guides/elysia/index.mdx new file mode 100644 index 0000000000000..db3c6243f6fb7 --- /dev/null +++ b/docs/platforms/javascript/guides/elysia/index.mdx @@ -0,0 +1,235 @@ +--- +title: Elysia +description: Learn how to set up Sentry in your Elysia app to capture errors and monitor performance. +sdk: sentry.javascript.elysia +fallbackGuide: javascript.bun +categories: + - javascript + - server + - server-node +--- + + + +This SDK is currently in **ALPHA**. Alpha features are still in progress, may have bugs, and might include breaking changes. +Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback or concerns. + + + +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- An Elysia application (v1.4.0+) +- Bun or Node.js 18+ (with [@elysiajs/node](https://elysiajs.com/integrations/node) adapter) + +## Step 1: Install + +Choose the features you want to configure, and this guide will show you how: + + + + + +### Install the Sentry SDK + +Run the command for your preferred package manager to add the Sentry SDK to your application: + +```bash {tabTitle:Bun} +bun add @sentry/elysia +``` + +```bash {tabTitle:Node.js} +npm install @sentry/elysia @elysiajs/node +# or +yarn add @sentry/elysia @elysiajs/node +# or +pnpm add @sentry/elysia @elysiajs/node +``` + + + You do **not** need `@elysiajs/opentelemetry`. The `@sentry/elysia` SDK handles all instrumentation natively. + + +## Step 2: Configure + +Call `Sentry.init()` before creating your Elysia app, then wrap the app with `Sentry.withElysia()` before defining routes. + +```javascript {tabTitle:Bun} {filename: index.ts} +import * as Sentry from "@sentry/elysia"; +import { Elysia } from "elysia"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Adds request headers and IP for users, for more info visit: + // https://docs.sentry.io/platforms/javascript/guides/elysia/configuration/options/#sendDefaultPii + sendDefaultPii: true, + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/guides/elysia/configuration/options/#tracesSampleRate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + // ___PRODUCT_OPTION_START___ logs + + // Enable logs to be sent to Sentry + enableLogs: true, + // ___PRODUCT_OPTION_END___ logs +}); + +// withElysia returns the app instance, so you can chain routes directly +const app = Sentry.withElysia(new Elysia()) + .get("/", () => "Hello World") + .listen(3000); +``` + +```javascript {tabTitle:Node.js} {filename: index.ts} +import * as Sentry from "@sentry/elysia"; +import { Elysia } from "elysia"; +import { node } from "@elysiajs/node"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Adds request headers and IP for users, for more info visit: + // https://docs.sentry.io/platforms/javascript/guides/elysia/configuration/options/#sendDefaultPii + sendDefaultPii: true, + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/guides/elysia/configuration/options/#tracesSampleRate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + // ___PRODUCT_OPTION_START___ logs + + // Enable logs to be sent to Sentry + enableLogs: true, + // ___PRODUCT_OPTION_END___ logs +}); + +// withElysia returns the app instance, so you can chain routes directly +const app = Sentry.withElysia(new Elysia({ adapter: node() })) + .get("/", () => "Hello World") + .listen(3000); +``` + +## Step 3: Add Readable Stack Traces With Source Maps (Optional) + + + +## Step 4: Verify Your Setup + +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + +### Issues + +First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following route to your app, which triggers an error that Sentry will capture: + +```javascript +app.get("/debug-sentry", () => { + throw new Error("My first Sentry error!"); +}); +``` + + + +### Tracing + +To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code: + +```javascript +app.get("/debug-sentry", async () => { + await Sentry.startSpan( + { + op: "test", + name: "My First Test Transaction", + }, + async () => { + await new Promise((resolve) => setTimeout(resolve, 100)); + throw new Error("My first Sentry error!"); + } + ); +}); +``` + + + + + + + + + +### View Captured Data in Sentry + +Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). + + + +## Features + +### Automatic Error Capturing + +The SDK captures 5xx errors automatically via a global `onError` hook. Client errors (3xx/4xx) are not captured by default. + +You can customize which errors are captured using the `shouldHandleError` option: + +```javascript +const app = Sentry.withElysia(new Elysia(), { + shouldHandleError: (context) => { + const status = context.set.status; + return status === 500 || status === 503; + }, +}); +``` + +### Automatic Tracing + +The SDK creates spans for every Elysia lifecycle phase: Request, Parse, Transform, BeforeHandle, Handle, AfterHandle, MapResponse, AfterResponse, and Error. + +- The Handle span uses `op: 'request_handler.elysia'`; all other lifecycle spans use `op: 'middleware.elysia'` +- Transactions use parameterized route names (e.g., `GET /users/:id`) +- Named function handlers show their function name in spans; arrow functions show as `anonymous` + +### Distributed Tracing + +The SDK automatically propagates incoming `sentry-trace` and `baggage` headers and injects trace headers into outgoing responses. No additional configuration needed. + +### Manual Spans + +You can create manual spans within your route handlers: + +```javascript +app.get("/checkout", () => { + return Sentry.startSpan({ name: "process-payment" }, () => { + // ... your code + }); +}); +``` + +## Runtime Behavior + +- **Bun**: The SDK creates root server spans via Elysia's `.wrap()` API with `continueTrace` for trace propagation. No additional runtime instrumentation needed. +- **Node.js**: The SDK uses Node's HTTP instrumentation for root spans and updates the transaction name with the parameterized route from Elysia. + +## Next Steps + +- Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to manually capture errors +- Continue to customize your configuration +- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts + + + +- Find various topics in Troubleshooting +- [Get support](https://sentry.zendesk.com/hc/en-us/) + + diff --git a/includes/quick-start-features-expandable.mdx b/includes/quick-start-features-expandable.mdx index ee4cb0e428303..b784216aed993 100644 --- a/includes/quick-start-features-expandable.mdx +++ b/includes/quick-start-features-expandable.mdx @@ -35,7 +35,7 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; - + diff --git a/includes/quick-start-locate-data-expandable.mdx b/includes/quick-start-locate-data-expandable.mdx index 27aa535a5ec85..f50d35cc12fe0 100644 --- a/includes/quick-start-locate-data-expandable.mdx +++ b/includes/quick-start-locate-data-expandable.mdx @@ -35,7 +35,7 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; - + diff --git a/package.json b/package.json index 203d43dd2a49f..0f88442483bca 100644 --- a/package.json +++ b/package.json @@ -91,7 +91,7 @@ "next-themes": "^0.3.0", "nextjs-toploader": "^1.6.6", "p-limit": "^6.2.0", - "platformicons": "^9.2.1", + "platformicons": "^9.3.0", "prism-sentry": "^1.0.2", "react": "^19.2.4", "react-dom": "^19.2.4", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4666974e71eb6..a330eb99347de 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -187,8 +187,8 @@ importers: specifier: ^6.2.0 version: 6.2.0 platformicons: - specifier: ^9.2.1 - version: 9.2.1(react@19.2.4) + specifier: ^9.3.0 + version: 9.3.0(react@19.2.4) prism-sentry: specifier: ^1.0.2 version: 1.0.2 @@ -6733,8 +6733,8 @@ packages: pkg-types@1.3.1: resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==} - platformicons@9.2.1: - resolution: {integrity: sha512-xY+epkdZKpvditx0IyeCBV7DNbHJVQDfg4DGIQN+DqwuBaeHe9UxA7sFaiKfoL+d12958QeyIaeVWXJ85IEG9g==} + platformicons@9.3.0: + resolution: {integrity: sha512-2Absdsu3dKB7y+hH4Yr6oAmdSdhxnnEpdxafnWZ07l537imkOOh2g9eFR0wQ1pvByIVq1+AwGzwGTFVNPCOPAw==} peerDependencies: react: '*' @@ -7525,8 +7525,8 @@ packages: engines: {node: '>=14.0.0'} hasBin: true - tapable@2.3.0: - resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==} + tapable@2.3.2: + resolution: {integrity: sha512-1MOpMXuhGzGL5TTCZFItxCc0AARf1EZFQkGqMm7ERKj8+Hgr5oLvJOVFcC+lRmR8hCe2S3jC4T5D7Vg/d7/fhA==} engines: {node: '>=6'} teeny-request@9.0.0: @@ -13610,7 +13610,7 @@ snapshots: enhanced-resolve@5.20.1: dependencies: graceful-fs: 4.2.11 - tapable: 2.3.0 + tapable: 2.3.2 entities@2.2.0: {} @@ -16206,7 +16206,7 @@ snapshots: mlly: 1.8.0 pathe: 2.0.3 - platformicons@9.2.1(react@19.2.4): + platformicons@9.3.0(react@19.2.4): dependencies: '@types/node': 22.19.11 '@types/react': 18.3.12 @@ -17383,7 +17383,7 @@ snapshots: - tsx - yaml - tapable@2.3.0: {} + tapable@2.3.2: {} teeny-request@9.0.0: dependencies: @@ -17954,7 +17954,7 @@ snapshots: mime-types: 2.1.35 neo-async: 2.6.2 schema-utils: 4.3.3 - tapable: 2.3.0 + tapable: 2.3.2 terser-webpack-plugin: 5.4.0(esbuild@0.25.12)(webpack@5.105.2(esbuild@0.25.12)) watchpack: 2.5.1 webpack-sources: 3.3.4 diff --git a/src/components/platformIcon.tsx b/src/components/platformIcon.tsx index ba1969d7b5ef5..326b38161aa12 100644 --- a/src/components/platformIcon.tsx +++ b/src/components/platformIcon.tsx @@ -43,6 +43,7 @@ import EchoSVG from 'platformicons/svg/echo.svg'; import EffectSVG from 'platformicons/svg/effect.svg'; import ElectronSVG from 'platformicons/svg/electron.svg'; import ElixirSVG from 'platformicons/svg/elixir.svg'; +import ElysiaSVG from 'platformicons/svg/elysia.svg'; import EmberSVG from 'platformicons/svg/ember.svg'; import ExpressSVG from 'platformicons/svg/express.svg'; import FalconSVG from 'platformicons/svg/falcon.svg'; @@ -194,6 +195,7 @@ import EchoSVGLarge from 'platformicons/svg_80x80/echo.svg'; import EffectSVGLarge from 'platformicons/svg_80x80/effect.svg'; import ElectronSVGLarge from 'platformicons/svg_80x80/electron.svg'; import ElixirSVGLarge from 'platformicons/svg_80x80/elixir.svg'; +import ElysiaSVGLarge from 'platformicons/svg_80x80/elysia.svg'; import EmberSVGLarge from 'platformicons/svg_80x80/ember.svg'; import ExpressSVGLarge from 'platformicons/svg_80x80/express.svg'; import FalconSVGLarge from 'platformicons/svg_80x80/falcon.svg'; @@ -492,6 +494,10 @@ const formatToSVG = { sm: ElixirSVG, lg: ElixirSVGLarge, }, + elysia: { + sm: ElysiaSVG, + lg: ElysiaSVGLarge, + }, ember: { sm: EmberSVG, lg: EmberSVGLarge, @@ -993,6 +999,7 @@ export const PLATFORM_TO_ICON = { 'javascript-deno': 'deno', 'javascript-effect': 'effect', 'javascript-electron': 'electron', + 'javascript-elysia': 'elysia', 'javascript-ember': 'ember', 'javascript-express': 'express', 'javascript-gatsby': 'gatsby',