What is @sentry/node?
The @sentry/node package is a tool designed for real-time monitoring and fixing crashes in Node.js applications. It provides error tracking and performance monitoring, helping developers to quickly identify, diagnose, and fix problems in their applications. Sentry integrates seamlessly with your existing codebase, offering a range of features to enhance application reliability and user experience.
What are @sentry/node's main functionalities?
Error Tracking
Automatically capture exceptions and errors in your Node.js applications. The code initializes Sentry with your project's DSN and demonstrates how an uncaught exception is automatically reported to Sentry.
const Sentry = require('@sentry/node');
Sentry.init({ dsn: 'YOUR_DSN_HERE' });
app.get('/', function mainHandler(req, res) {
throw new Error('Broke!');
});
Performance Monitoring
Track the performance of your application, including request times and slow operations. This code sample starts a transaction, simulates an operation with a timeout, and then finishes the transaction, which is then reported to Sentry for performance analysis.
const Sentry = require('@sentry/node');
const transaction = Sentry.startTransaction({ op: 'test', name: 'My First Test Transaction' });
setTimeout(() => {
transaction.finish();
}, 99);
Custom Event Capturing
Send custom messages or events to Sentry. This is useful for capturing non-exception events that are significant for your application's health monitoring and diagnostics.
const Sentry = require('@sentry/node');
Sentry.captureMessage('Something went wrong', 'error');
Other packages similar to @sentry/node
bugsnag-js
Bugsnag provides error monitoring for web, mobile, and server applications. Similar to @sentry/node, it offers real-time error reporting and allows for detailed error diagnostics and performance monitoring. Bugsnag differentiates itself with features tailored to mobile app monitoring.
rollbar
Rollbar offers real-time error tracking and debugging tools for developers. Like @sentry/node, it supports multiple programming languages and frameworks, including Node.js. Rollbar emphasizes its ability to help teams with workflow integrations and automated error grouping for efficient management.
raygun
Raygun provides crash reporting, real-user monitoring, and deployment tracking. It's similar to @sentry/node in its core functionalities of error tracking and performance monitoring but also offers unique features like user journey tracking and version comparisons to understand the impact of deployments.
Official Sentry SDK for Node (EXPERIMENTAL)
This is a WIP, proof of concept implementation of a Node SDK that uses OpenTelemetry for performance instrumentation under the hood.
THIS MAY/WILL BREAK IN MANY UNEXPECTED WAYS. We may remove, add, change any of the integrations, add/remove any exports, etc.
This package is NOT READY TO USE IN ANY FORM OF PRODUCTION ENVIRONMENT!
This SDK is considered experimental and in an alpha state. It may experience breaking changes, and may be discontinued at any time. Please reach out on
GitHub if you have any feedback/concerns.
Installation
npm install @sentry/node-experimental
yarn add @sentry/node-experimental
Usage
const Sentry = require('@sentry/node-experimental');
import * as Sentry from '@sentry/node-experimental';
Sentry.init({
dsn: '__DSN__',
});
Note that it is necessary to initialize Sentry before you import any package that may be instrumented by us.
Status of this Experiment
Currently, this SDK:
- Will capture errors (same as @sentry/node)
- Auto-instrument for performance - see below for which performance integrations are available.
- Provide some manual instrumentation APIs
- Sync OpenTelemetry Context with our Sentry Hub/Scope
Manual Instrumentation
You can manual instrument using the following APIs:
const Sentry = require('@sentry/node-experimental');
Sentry.startSpan({ description: 'outer' }, function (span) {
span.setData(customData);
doSomethingSlow();
Sentry.startSpan({ description: 'inner' }, function() {
doSomethingVerySlow();
});
});
You can also create spans without marking them as the active span.
Note that for most scenarios, we recommend the startSpan
syntax.
const Sentry = require('@sentry/node-experimental');
const span = Sentry.startInactiveSpan({ description: 'non-active span' });
doSomethingSlow();
span.end();
Finally you can also get the currently active span, if you need to do more with it:
const Sentry = require('@sentry/node-experimental');
const span = Sentry.getActiveSpan();
Async Context
We leverage the OpenTelemetry context forking in order to ensure isolation of parallel requests.
This means that as long as you are using an OpenTelemetry instrumentation for your framework of choice
(currently: Express or Fastify), you do not need to setup any requestHandler
or similar.
ESM Support
Due to the way OpenTelemetry handles instrumentation, this only works out of the box for CommonJS (require
) applications.
There is experimental support for running OpenTelemetry with ESM ("type": "module"
):
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs ./app.js
You'll need to install @opentelemetry/instrumentation
in your app to ensure this works.
See OpenTelemetry Instrumentation Docs for details on this -
but note that this is a) experimental, and b) does not work with all integrations.
Available (Performance) Integrations
- Http
- Express
- Fastify
- Nest
- Mysql
- Mysql2
- GraphQL
- Mongo
- Mongoose
- Postgres
- Prisma
All of these are auto-discovered, you don't need to configure anything for performance.
You still need to register middlewares etc. for error capturing.
Other, non-performance integrations from @sentry/node
are also available (except for Undici).
Links
8.0.0-alpha.1
This is the first Alpha release of the v8 cycle, which includes a variety of breaking changes.
Read the in-depth migration guide to find out how to address any breaking changes in your code.
Important Changes
- feat(node): Make @sentry/node
powered by OpenTelemetry (#10762)
The biggest change is the switch to use OpenTelemetry under the hood in @sentry/node
. This brings with it a variety of
changes:
- There is now automated performance instrumentation for Express, Fastify, Nest.js and Koa. You can remove any
performance and request isolation code you previously wrote manually for these frameworks.
- All performance instrumention is enabled by default, and will only take effect if the instrumented package is used.
You don't need to use
autoDiscoverNodePerformanceMonitoringIntegrations()
anymore. - You need to ensure to call
Sentry.init()
before you import any other packages. Otherwise, the packages cannot be
instrumented:
const Sentry = require('@sentry/node');
Sentry.init({
dsn: '...',
// ... other config here
});
// now require other things below this!
const http = require('http');
const express = require('express');
// ....
- Currently, we only support CJS-based Node application out of the box. There is experimental ESM support, see
the instructions.
startTransaction
and span.startChild()
are no longer supported. This is due to the underlying change to
OpenTelemetry powered performance instrumentation. See
docs on the new performance APIs for details.
Related changes:
- feat(node-experimental): Add missing re-exports (#10679)
- feat(node-experimental): Move
defaultStackParser
& getSentryRelease
(#10722) - feat(node-experimental): Move
errorHandler
(#10728) - feat(node-experimental): Move cron code over (#10742)
- feat(node-experimental): Move integrations from node (#10743)
- feat(node-experimental): Properly set request & session on http requests (#10676)
- feat(opentelemetry): Support
forceTransaction
in OTEL (#10807) - feat(opentelemetry): Align span options with core span options (#10761)
- feat(opentelemetry): Do not capture span events as breadcrumbs (#10612)
- feat(opentelemetry): Ensure DSC & attributes are correctly set (#10806)
- feat(opentelemetry): Fix & align isolation scope usage in node-experimental (#10570)
- feat(opentelemetry): Merge node-experimental changes into opentelemetry (#10689)
- ref(node-experimental): Cleanup re-exports (#10741)
- ref(node-experimental): Cleanup tracing intergations (#10730)
- ref(node-experimental): Copy transport & client to node-experimental (#10720)
- ref(node-experimental): Remove custom
isInitialized
(#10607) - ref(node-experimental): Remove custom hub & scope (#10616)
- ref(node-experimental): Remove deprecated class integrations (#10675)
- ref(node-experimental): Rename
errorHandler
to expressErrorHandler
(#10746) - ref(node-integration-tests): Migrate to new Http integration (#10765)
- ref(node): Align semantic attribute handling (#10827)
- feat: Remove @sentry/integrations
package (#10799)
This package is no longer published. You can instead import these pluggable integrations directly from your SDK package
(e.g. @sentry/browser
or @sentry/react
).
- feat: Remove @sentry/hub
package (#10783)
This package is no longer published. You can instead import directly from your SDK package (e.g. @sentry/react
or
@sentry/node
).
- feat(v8): Remove @sentry/tracing (#10625)
This package is no longer published. You can instead import directly from your SDK package (e.g. @sentry/react
or
@sentry/node
).
- feat: Set required node version to >=14.8.0 for all packages (#10834)
The minimum required node version is now 14.8+. If you need support for older node versions, you can stay on the v7
branch.
- Removed class-based integrations
We have removed most of the deprecated class-based integrations. Instead, you can use the functional styles:
import * as Sentry from '@sentry/browser';
// v7
Sentry.init({
integrations: [new Sentry.BrowserTracing()],
});
// v8
Sentry.init({
integrations: [new Sentry.browserTracingIntegration()],
});
- ref: Remove
BrowserTracing
(#10653) - feat(v8/node): Remove LocalVariables class integration (#10558)
- feat(v8/react): Delete react router exports (#10532)
- feat(v8/vue): Remove all deprecated exports from vue (#10533)
- feat(v8/wasm): Remove deprecated exports (#10552)
- feat(v8/browser): Remove XHR transport (#10703)
We have removed the XHR transport, and are instead using the fetch-based transport now by default. This means that if
you are using Sentry in a browser environment without fetch, you'll need to either provide a fetch polyfill, or provide
a custom transport to Sentry.
- feat(sveltekit): Update @sentry/vite-plugin
to 2.x and adjust options API (#10813)
We have updated @sentry/sveltekit
to use the latest version of @sentry/vite-plugin
, which lead to changes in
configuration options.
Other Changes
- feat: Ensure
withActiveSpan
is exported everywhere (#10878) - feat: Allow passing
null
to withActiveSpan
(#10717) - feat: Implement new Async Context Strategy (#10647)
- feat: Remove
hub
from global, hub.run
& hub utilities (#10718) - feat: Update default trace propagation targets logic in the browser (#10621)
- feat: Ignore ResizeObserver and undefined error (#10845)
- feat(browser): Export
getIsolationScope
and getGlobalScope
(#10658) - feat(browser): Prevent initialization in browser extensions (#10844)
- feat(core): Add metric summaries to spans (#10554)
- feat(core): Decouple metrics aggregation from client (#10628)
- feat(core): Lookup client on current scope, not hub (#10635)
- feat(core): Make
setXXX
methods set on isolation scope (#10678) - feat(core): Make custom tracing methods return spans & set default op (#10633)
- feat(core): Make global
addBreadcrumb
write to the isolation scope instead of current scope (#10586) - feat(core): Remove health check transaction filters (#10818)
- feat(core): Streamline custom hub creation for node-experimental (#10555)
- feat(core): Update
addEventProcessor
to add to isolation scope (#10606) - feat(core): Update
Sentry.addBreadcrumb
to skip hub (#10601) - feat(core): Use global
TextEncoder
and TextDecoder
(#10701) - feat(deps): bump @sentry/cli from 2.26.0 to 2.28.0 (#10496)
- feat(deps): bump @sentry/cli from 2.28.0 to 2.28.5 (#10620)
- feat(deps): bump @sentry/cli from 2.28.5 to 2.28.6 (#10727)
- feat(integrations): Capture error arguments as exception regardless of level in
captureConsoleIntegration
(#10744) - feat(metrics): Remove metrics method from
BaseClient
(#10789) - feat(node): Remove unnecessary URL imports (#10860)
- feat(react): Drop support for React 15 (#10115)
- feat(remix): Add Vite dev-mode support to Express instrumentation. (#10784)
- fix: Export session API (#10711)
- fix(angular-ivy): Add
exports
field to package.json
(#10569) - fix(angular): Ensure navigations always create a transaction (#10646)
- fix(core): Add lost scope tests & fix update case (#10738)
- fix(core): Fix scope capturing via
captureContext
function (#10735) - fix(feedback): Replay breadcrumb for feedback events was incorrect (#10536)
- fix(nextjs): Remove
webpack://
prefix more broadly from source map sources
field (#10642) - fix(node): import
worker_threads
and fix node v14 types (#10791) - fix(node): Record local variables with falsy values,
null
and undefined
(#10821) - fix(stacktrace): Always use
?
for anonymous function name (#10732) - fix(sveltekit): Avoid capturing Http 4xx errors on the client (#10571)
- fix(sveltekit): Ensure navigations and redirects always create a new transaction (#10656)
- fix(sveltekit): Properly await sourcemaps flattening (#10602)
- fix(types): Improve attachment type (#10832)
- fx(node): Fix anr worker check (#10719)
- ref: Cleanup browser profiling integration (#10766)
- ref: Collect child spans references via non-enumerable on Span object (#10715)
- ref: Make scope setters on hub only write to isolation scope (#10572)
- ref: Store runtime on isolation scope (#10657)
- ref(astro): Put request as SDK processing metadata instead of span data (#10840)
- ref(core): Always use a (default) ACS (#10644)
- ref(core): Make
on
and emit
required on client (#10603) - ref(core): Make remaining client methods required (#10605)
- ref(core): Rename
Span
class to SentrySpan
(#10687) - ref(core): Restructure hub exports (#10639)
- ref(core): Skip hub in top level
captureXXX
methods (#10688) - ref(core): Allow
number
as span traceFlag
(#10855) - ref(core): Remove
status
field from Span (#10856) - ref(remix): Make
@remix-run/router
a dependency. (#10479) - ref(replay): Use
beforeAddBreadcrumb
hook instead of scope listener (#10600) - ref(sveltekit): Hard-pin Vite plugin version (#10843)
Other Deprecation Removals/Changes
We have also removed or updated a variety of deprecated APIs.
- feat(v8): Remove
extractTraceparentData
export (#10559) - feat(v8): Remove defaultIntegrations deprecated export (#10691)
- feat(v8): Remove deprecated
span.isSuccess
method (#10699) - feat(v8): Remove deprecated
traceHeaders
method (#10776) - feat(v8): Remove deprecated addInstrumentationHandler (#10693)
- feat(v8): Remove deprecated configureScope call (#10565)
- feat(v8): Remove deprecated runWithAsyncContext API (#10780)
- feat(v8): Remove deprecated spanStatusfromHttpCode export (#10563)
- feat(v8): Remove deprecated trace and startActiveSpan methods (#10593)
- feat(v8): Remove requestData deprecations (#10626)
- feat(v8): Remove Severity enum (#10551)
- feat(v8): Remove span.origin (#10753)
- feat(v8): Remove span.toTraceparent method (#10698)
- feat(v8): Remove usage of span.description and span.name (#10697)
- feat(v8): Update eventFromUnknownInput to only use client (#10692)
- feat(v8/astro): Remove deprecated exports from Astro SDK (#10611)
- feat(v8/browser): Remove
_eventFromIncompleteOnError
usage (#10553) - feat(v8/browser): Remove XHR transport (#10703)
- feat(v8/browser): Rename TryCatch integration to
browserApiErrorsIntegration
(#10755) - feat(v8/core): Remove deprecated setHttpStatus (#10774)
- feat(v8/core): Remove deprecated updateWithContext method (#10800)
- feat(v8/core): Remove getters for span.op (#10767)
- feat(v8/core): Remove span.finish call (#10773)
- feat(v8/core): Remove span.instrumenter and instrumenter option (#10769)
- feat(v8/ember): Remove deprecated exports (#10535)
- feat(v8/integrations): Remove deprecated exports (#10556)
- feat(v8/node): Remove deepReadDirSync export (#10564)
- feat(v8/node): Remove deprecated anr methods (#10562)
- feat(v8/node): Remove getModuleFromFilename export (#10754)
- feat(core): Remove deprecated props from
Span
interface (#10854) - fix(v8): Remove deprecated tracing config (#10870)
- ref: Make
setupOnce
optional in integrations (#10729) - ref: Migrate transaction source from metadata to attributes (#10674)
- ref: Refactor remaining
makeMain
usage (#10713) - ref(astro): Remove deprecated Replay and BrowserTracing (#10768)
- feat(core): Remove deprecated
scope.applyToEvent()
method (#10842) - ref(integrations): Remove offline integration (#9456)
- ref(nextjs): Remove all deprecated API (#10549)
- ref: Remove
lastEventId
(#10585) - ref: Remove
reuseExisting
option for ACS (#10645) - ref: Remove
tracingOrigins
options (#10614) - ref: Remove deprecated
showReportDialog
APIs (#10609) - ref: Remove usage of span tags (#10808)
- ref: Remove user segment (#10575)
7.x
A full list of changes in the 7.x
release of the SDK can be found in the 7.x Changelog.
6.x
A full list of changes in the 6.x
release of the SDK can be found in the 6.x Changelog.
5.x
A full list of changes in the 5.x
release of the SDK can be found in the 5.x Changelog.
4.x
A full list of changes in the 4.x
release of the SDK can be found in the 4.x Changelog.