Skip to content

Commit 1c78f69

Browse files
logaretmclaude
logaretm
and
claude
committed
docs(elysia): Add @sentry/elysia SDK documentation and icon
Add getting started guide for the new @sentry/elysia package covering Bun and Node.js runtimes, error capturing, automatic tracing, and distributed trace propagation. Wire up the Elysia platform icon. Refs getsentry/sentry-javascript#19509 Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 8c34b2d commit 1c78f69

2 files changed

Lines changed: 160 additions & 0 deletions

File tree

‎docs/platforms/javascript/guides/elysia/index.mdx‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: Elysia
3+
description: Learn how to set up Sentry in your Elysia app to capture errors and monitor performance.
4+
sdk: sentry.javascript.bun
5+
fallbackGuide: javascript.bun
6+
categories:
7+
- javascript
8+
- server
9+
- server-node
10+
---
11+
12+
<Alert>
13+
14+
This SDK is currently in **ALPHA**. Alpha features are still in progress, may have bugs, and might include breaking changes.
15+
Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback or concerns.
16+
17+
</Alert>
18+
19+
## Prerequisites
20+
21+
You need:
22+
23+
- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
24+
- An Elysia application (v1.4.0+)
25+
- Bun or Node.js 18+ (with [@elysiajs/node](https://elysiajs.com/plugins/node) adapter)
26+
27+
## Step 1: Install
28+
29+
```bash {tabTitle:Bun}
30+
bun add @sentry/elysia
31+
```
32+
33+
```bash {tabTitle:npm}
34+
npm install @sentry/elysia @elysiajs/node
35+
```
36+
37+
<Alert>
38+
You do **not** need `@elysiajs/opentelemetry`. The `@sentry/elysia` SDK handles all instrumentation natively.
39+
</Alert>
40+
41+
## Step 2: Configure
42+
43+
Call `Sentry.init()` before creating your Elysia app, then wrap the app with `Sentry.withElysia()` before defining routes.
44+
45+
```javascript {tabTitle:Bun} {filename: index.ts}
46+
import * as Sentry from "@sentry/elysia";
47+
import { Elysia } from "elysia";
48+
49+
Sentry.init({
50+
dsn: "___PUBLIC_DSN___",
51+
// Set tracesSampleRate to 1.0 to capture 100% of transactions
52+
// We recommend adjusting this value in production
53+
tracesSampleRate: 1.0,
54+
});
55+
56+
const app = Sentry.withElysia(new Elysia());
57+
58+
app.get("/", () => "Hello World");
59+
app.listen(3000);
60+
```
61+
62+
```javascript {tabTitle:Node.js} {filename: index.ts}
63+
import * as Sentry from "@sentry/elysia";
64+
import { Elysia } from "elysia";
65+
import { node } from "@elysiajs/node";
66+
67+
Sentry.init({
68+
dsn: "___PUBLIC_DSN___",
69+
// Set tracesSampleRate to 1.0 to capture 100% of transactions
70+
// We recommend adjusting this value in production
71+
tracesSampleRate: 1.0,
72+
});
73+
74+
const app = Sentry.withElysia(new Elysia({ adapter: node() }));
75+
76+
app.get("/", () => "Hello World");
77+
app.listen(3000);
78+
```
79+
80+
`Sentry.withElysia()` returns the app instance, so you can chain routes directly:
81+
82+
```javascript
83+
const app = Sentry.withElysia(new Elysia())
84+
.get("/", () => "Hello World")
85+
.post("/users", createUser);
86+
```
87+
88+
The SDK re-exports everything from `@sentry/bun`, so all Sentry APIs (like `captureException`, `startSpan`, `setUser`, `setTag`) are available directly from `@sentry/elysia`.
89+
90+
## Step 3: Verify Your Setup
91+
92+
Add a test route that throws an error:
93+
94+
```javascript
95+
app.get("/debug-sentry", () => {
96+
throw new Error("My first Sentry error!");
97+
});
98+
```
99+
100+
Visit `/debug-sentry` in your browser. The error should appear in your Sentry project within a few moments.
101+
102+
## Features
103+
104+
### Automatic Error Capturing
105+
106+
The SDK captures 5xx errors automatically via a global `onError` hook. Client errors (3xx/4xx) are not captured by default.
107+
108+
You can customize which errors are captured using the `shouldHandleError` option:
109+
110+
```javascript
111+
Sentry.withElysia(app, {
112+
shouldHandleError: (context) => {
113+
const status = context.set.status;
114+
return status === 500 || status === 503;
115+
},
116+
});
117+
```
118+
119+
### Automatic Tracing
120+
121+
The SDK creates spans for every Elysia lifecycle phase: Request, Parse, Transform, BeforeHandle, Handle, AfterHandle, MapResponse, AfterResponse, and Error.
122+
123+
- The Handle span uses `op: 'request_handler.elysia'`; all other lifecycle spans use `op: 'middleware.elysia'`
124+
- Transactions use parameterized route names (e.g., `GET /users/:id`)
125+
- Named function handlers show their function name in spans; arrow functions show as `anonymous`
126+
127+
### Distributed Tracing
128+
129+
The SDK automatically propagates incoming `sentry-trace` and `baggage` headers and injects trace headers into outgoing responses. No additional configuration needed.
130+
131+
### Manual Spans
132+
133+
You can create manual spans within your route handlers:
134+
135+
```javascript
136+
app.get("/checkout", () => {
137+
return Sentry.startSpan({ name: "process-payment" }, () => {
138+
// ... your code
139+
});
140+
});
141+
```
142+
143+
## Runtime Behavior
144+
145+
- **Bun**: The SDK creates root server spans via Elysia's `.wrap()` API with `continueTrace` for trace propagation. No additional runtime instrumentation needed.
146+
- **Node.js**: The SDK uses Node's HTTP instrumentation for root spans and updates the transaction name with the parameterized route from Elysia.
147+
148+
## Next Steps
149+
150+
- Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup
151+
- Learn how to <PlatformLink to="/usage">manually capture errors</PlatformLink>
152+
- Continue to <PlatformLink to="/configuration">customize your configuration</PlatformLink>
153+
- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts

‎src/components/platformIcon.tsx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ import DotnetfxSVG from 'platformicons/svg/dotnetfx.svg';
4242
import EchoSVG from 'platformicons/svg/echo.svg';
4343
import EffectSVG from 'platformicons/svg/effect.svg';
4444
import ElectronSVG from 'platformicons/svg/electron.svg';
45+
import ElysiaSVG from 'platformicons/svg/elysia.svg';
4546
import ElixirSVG from 'platformicons/svg/elixir.svg';
4647
import EmberSVG from 'platformicons/svg/ember.svg';
4748
import ExpressSVG from 'platformicons/svg/express.svg';
@@ -193,6 +194,7 @@ import DotnetfxSVGLarge from 'platformicons/svg_80x80/dotnetfx.svg';
193194
import EchoSVGLarge from 'platformicons/svg_80x80/echo.svg';
194195
import EffectSVGLarge from 'platformicons/svg_80x80/effect.svg';
195196
import ElectronSVGLarge from 'platformicons/svg_80x80/electron.svg';
197+
import ElysiaSVGLarge from 'platformicons/svg_80x80/elysia.svg';
196198
import ElixirSVGLarge from 'platformicons/svg_80x80/elixir.svg';
197199
import EmberSVGLarge from 'platformicons/svg_80x80/ember.svg';
198200
import ExpressSVGLarge from 'platformicons/svg_80x80/express.svg';
@@ -488,6 +490,10 @@ const formatToSVG = {
488490
sm: ElectronSVG,
489491
lg: ElectronSVGLarge,
490492
},
493+
elysia: {
494+
sm: ElysiaSVG,
495+
lg: ElysiaSVGLarge,
496+
},
491497
elixir: {
492498
sm: ElixirSVG,
493499
lg: ElixirSVGLarge,
@@ -993,6 +999,7 @@ export const PLATFORM_TO_ICON = {
993999
'javascript-deno': 'deno',
9941000
'javascript-effect': 'effect',
9951001
'javascript-electron': 'electron',
1002+
'javascript-elysia': 'elysia',
9961003
'javascript-ember': 'ember',
9971004
'javascript-express': 'express',
9981005
'javascript-gatsby': 'gatsby',

0 commit comments

Comments
 (0)