Skip to content

Commit d90d5b8

Browse files
AbhiPrasadAbhiPrasad
authored
docs: Improve docstrings for node otel integrations (#14217)
Related to #13317 Improve the docstrings and link to documentation pages as appropriate (as they contain information about opentelemetry and supported versions).
1 parent 127083e commit d90d5b8

19 files changed

+337
-39
lines changed

‎packages/node/src/integrations/tracing/amqplib.ts

+14
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,18 @@ const _amqplibIntegration = (() => {
2727
};
2828
}) satisfies IntegrationFn;
2929

30+
/**
31+
* Adds Sentry tracing instrumentation for the [amqplib](https://www.npmjs.com/package/amqplib) library.
32+
*
33+
* For more information, see the [`amqplibIntegration` documentation](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/amqplib/).
34+
*
35+
* @example
36+
* ```javascript
37+
* const Sentry = require('@sentry/node');
38+
*
39+
* Sentry.init({
40+
* integrations: [Sentry.amqplibIntegration()],
41+
* });
42+
* ```
43+
*/
3044
export const amqplibIntegration = defineIntegration(_amqplibIntegration);

‎packages/node/src/integrations/tracing/connect.ts

+35
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,22 @@ const _connectIntegration = (() => {
2929
};
3030
}) satisfies IntegrationFn;
3131

32+
/**
33+
* Adds Sentry tracing instrumentation for [Connect](https://github.com/senchalabs/connect/).
34+
*
35+
* If you also want to capture errors, you need to call `setupConnectErrorHandler(app)` after you initialize your connect app.
36+
*
37+
* For more information, see the [connect documentation](https://docs.sentry.io/platforms/javascript/guides/connect/).
38+
*
39+
* @example
40+
* ```javascript
41+
* const Sentry = require('@sentry/node');
42+
*
43+
* Sentry.init({
44+
* integrations: [Sentry.connectIntegration()],
45+
* })
46+
* ```
47+
*/
3248
export const connectIntegration = defineIntegration(_connectIntegration);
3349

3450
// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -37,6 +53,25 @@ function connectErrorMiddleware(err: any, req: any, res: any, next: any): void {
3753
next(err);
3854
}
3955

56+
/**
57+
* Add a Connect middleware to capture errors to Sentry.
58+
*
59+
* @param app The Connect app to attach the error handler to
60+
*
61+
* @example
62+
* ```javascript
63+
* const Sentry = require('@sentry/node');
64+
* const connect = require("connect");
65+
*
66+
* const app = connect();
67+
*
68+
* Sentry.setupConnectErrorHandler(app);
69+
*
70+
* // Add you connect routes here
71+
*
72+
* app.listen(3000);
73+
* ```
74+
*/
4075
export const setupConnectErrorHandler = (app: ConnectApp): void => {
4176
app.use(connectErrorMiddleware);
4277

‎packages/node/src/integrations/tracing/dataloader.ts

+11-2
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,17 @@ const _dataloaderIntegration = (() => {
5050
}) satisfies IntegrationFn;
5151

5252
/**
53-
* Dataloader integration
53+
* Adds Sentry tracing instrumentation for the [dataloader](https://www.npmjs.com/package/dataloader) library.
5454
*
55-
* Capture tracing data for Dataloader.
55+
* For more information, see the [`dataloaderIntegration` documentation](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/dataloader/).
56+
*
57+
* @example
58+
* ```javascript
59+
* const Sentry = require('@sentry/node');
60+
*
61+
* Sentry.init({
62+
* integrations: [Sentry.dataloaderIntegration()],
63+
* });
64+
* ```
5665
*/
5766
export const dataloaderIntegration = defineIntegration(_dataloaderIntegration);

‎packages/node/src/integrations/tracing/express.ts

+34-4
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,20 @@ const _expressIntegration = (() => {
6060
}) satisfies IntegrationFn;
6161

6262
/**
63-
* Express integration
63+
* Adds Sentry tracing instrumentation for [Express](https://expressjs.com/).
6464
*
65-
* Capture tracing data for express.
66-
* In order to capture exceptions, you have to call `setupExpressErrorHandler(app)` before any other middleware and after all controllers.
65+
* If you also want to capture errors, you need to call `setupExpressErrorHandler(app)` after you set up your Express server.
66+
*
67+
* For more information, see the [express documentation](https://docs.sentry.io/platforms/javascript/guides/express/).
68+
*
69+
* @example
70+
* ```javascript
71+
* const Sentry = require('@sentry/node');
72+
*
73+
* Sentry.init({
74+
* integrations: [Sentry.expressIntegration()],
75+
* })
76+
* ```
6777
*/
6878
export const expressIntegration = defineIntegration(_expressIntegration);
6979

@@ -134,8 +144,28 @@ export function expressErrorHandler(options?: ExpressHandlerOptions): ExpressMid
134144
}
135145

136146
/**
137-
* Setup an error handler for Express.
147+
* Add an Express error handler to capture errors to Sentry.
148+
*
138149
* The error handler must be before any other middleware and after all controllers.
150+
*
151+
* @param app The Express instances
152+
* @param options {ExpressHandlerOptions} Configuration options for the handler
153+
*
154+
* @example
155+
* ```javascript
156+
* const Sentry = require('@sentry/node');
157+
* const express = require("express");
158+
*
159+
* const app = express();
160+
*
161+
* // Add your routes, etc.
162+
*
163+
* // Add this after all routes,
164+
* // but before any and other error-handling middlewares are defined
165+
* Sentry.setupExpressErrorHandler(app);
166+
*
167+
* app.listen(3000);
168+
* ```
139169
*/
140170
export function setupExpressErrorHandler(
141171
app: { use: (middleware: ExpressMiddleware) => unknown },

‎packages/node/src/integrations/tracing/fastify.ts

+30-3
Original file line numberDiff line numberDiff line change
@@ -55,14 +55,41 @@ const _fastifyIntegration = (() => {
5555
}) satisfies IntegrationFn;
5656

5757
/**
58-
* Express integration
58+
* Adds Sentry tracing instrumentation for [Fastify](https://fastify.dev/).
5959
*
60-
* Capture tracing data for fastify.
60+
* If you also want to capture errors, you need to call `setupFastifyErrorHandler(app)` after you set up your Fastify server.
61+
*
62+
* For more information, see the [fastify documentation](https://docs.sentry.io/platforms/javascript/guides/fastify/).
63+
*
64+
* @example
65+
* ```javascript
66+
* const Sentry = require('@sentry/node');
67+
*
68+
* Sentry.init({
69+
* integrations: [Sentry.fastifyIntegration()],
70+
* })
71+
* ```
6172
*/
6273
export const fastifyIntegration = defineIntegration(_fastifyIntegration);
6374

6475
/**
65-
* Setup an error handler for Fastify.
76+
* Add an Fastify error handler to capture errors to Sentry.
77+
*
78+
* @param fastify The Fastify instance to which to add the error handler
79+
*
80+
* @example
81+
* ```javascript
82+
* const Sentry = require('@sentry/node');
83+
* const Fastify = require("fastify");
84+
*
85+
* const app = Fastify();
86+
*
87+
* Sentry.setupFastifyErrorHandler(app);
88+
*
89+
* // Add your routes, etc.
90+
*
91+
* app.listen({ port: 3000 });
92+
* ```
6693
*/
6794
export function setupFastifyErrorHandler(fastify: Fastify): void {
6895
const plugin = Object.assign(

‎packages/node/src/integrations/tracing/genericPool.ts

+11-2
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,17 @@ const _genericPoolIntegration = (() => {
3333
}) satisfies IntegrationFn;
3434

3535
/**
36-
* GenericPool integration
36+
* Adds Sentry tracing instrumentation for the [generic-pool](https://www.npmjs.com/package/generic-pool) library.
3737
*
38-
* Capture tracing data for GenericPool.
38+
* For more information, see the [`genericPoolIntegration` documentation](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/genericpool/).
39+
*
40+
* @example
41+
* ```javascript
42+
* const Sentry = require('@sentry/node');
43+
*
44+
* Sentry.init({
45+
* integrations: [Sentry.genericPoolIntegration()],
46+
* });
47+
* ```
3948
*/
4049
export const genericPoolIntegration = defineIntegration(_genericPoolIntegration);

‎packages/node/src/integrations/tracing/graphql.ts

+12-2
Original file line numberDiff line numberDiff line change
@@ -93,9 +93,19 @@ const _graphqlIntegration = ((options: GraphqlOptions = {}) => {
9393
}) satisfies IntegrationFn;
9494

9595
/**
96-
* GraphQL integration
96+
* Adds Sentry tracing instrumentation for the [graphql](https://www.npmjs.com/package/graphql) library.
9797
*
98-
* Capture tracing data for GraphQL.
98+
* For more information, see the [`graphqlIntegration` documentation](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/graphql/).
99+
*
100+
* @param {GraphqlOptions} options Configuration options for the GraphQL integration.
101+
*
102+
* @example
103+
* ```javascript
104+
* const Sentry = require('@sentry/node');
105+
*
106+
* Sentry.init({
107+
* integrations: [Sentry.graphqlIntegration()],
108+
* });
99109
*/
100110
export const graphqlIntegration = defineIntegration(_graphqlIntegration);
101111

‎packages/node/src/integrations/tracing/hapi/index.ts

+30-2
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,20 @@ const _hapiIntegration = (() => {
3131
}) satisfies IntegrationFn;
3232

3333
/**
34-
* Hapi integration
34+
* Adds Sentry tracing instrumentation for [Hapi](https://hapi.dev/).
3535
*
36-
* Capture tracing data for Hapi.
3736
* If you also want to capture errors, you need to call `setupHapiErrorHandler(server)` after you set up your server.
37+
*
38+
* For more information, see the [hapi documentation](https://docs.sentry.io/platforms/javascript/guides/hapi/).
39+
*
40+
* @example
41+
* ```javascript
42+
* const Sentry = require('@sentry/node');
43+
*
44+
* Sentry.init({
45+
* integrations: [Sentry.hapiIntegration()],
46+
* })
47+
* ```
3848
*/
3949
export const hapiIntegration = defineIntegration(_hapiIntegration);
4050

@@ -81,6 +91,24 @@ export const hapiErrorPlugin = {
8191

8292
/**
8393
* Add a Hapi plugin to capture errors to Sentry.
94+
*
95+
* @param server The Hapi server to attach the error handler to
96+
*
97+
* @example
98+
* ```javascript
99+
* const Sentry = require('@sentry/node');
100+
* const Hapi = require('@hapi/hapi');
101+
*
102+
* const init = async () => {
103+
* const server = Hapi.server();
104+
*
105+
* // all your routes here
106+
*
107+
* await Sentry.setupHapiErrorHandler(server);
108+
*
109+
* await server.start();
110+
* };
111+
* ```
84112
*/
85113
export async function setupHapiErrorHandler(server: Server): Promise<void> {
86114
await server.register(hapiErrorPlugin);

‎packages/node/src/integrations/tracing/kafka.ts

+10-2
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,16 @@ const _kafkaIntegration = (() => {
3030
}) satisfies IntegrationFn;
3131

3232
/**
33-
* KafkaJs integration
33+
* Adds Sentry tracing instrumentation for the [kafkajs](https://www.npmjs.com/package/kafkajs) library.
3434
*
35-
* Capture tracing data for KafkaJs.
35+
* For more information, see the [`kafkaIntegration` documentation](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/kafka/).
36+
*
37+
* @example
38+
* ```javascript
39+
* const Sentry = require('@sentry/node');
40+
*
41+
* Sentry.init({
42+
* integrations: [Sentry.kafkaIntegration()],
43+
* });
3644
*/
3745
export const kafkaIntegration = defineIntegration(_kafkaIntegration);

‎packages/node/src/integrations/tracing/koa.ts

+38
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,46 @@ const _koaIntegration = (() => {
4848
};
4949
}) satisfies IntegrationFn;
5050

51+
/**
52+
* Adds Sentry tracing instrumentation for [Koa](https://koajs.com/).
53+
*
54+
* If you also want to capture errors, you need to call `setupKoaErrorHandler(app)` after you set up your Koa server.
55+
*
56+
* For more information, see the [koa documentation](https://docs.sentry.io/platforms/javascript/guides/koa/).
57+
*
58+
* @example
59+
* ```javascript
60+
* const Sentry = require('@sentry/node');
61+
*
62+
* Sentry.init({
63+
* integrations: [Sentry.koaIntegration()],
64+
* })
65+
* ```
66+
*/
5167
export const koaIntegration = defineIntegration(_koaIntegration);
5268

69+
/**
70+
* Add an Koa error handler to capture errors to Sentry.
71+
*
72+
* The error handler must be before any other middleware and after all controllers.
73+
*
74+
* @param app The Express instances
75+
* @param options {ExpressHandlerOptions} Configuration options for the handler
76+
*
77+
* @example
78+
* ```javascript
79+
* const Sentry = require('@sentry/node');
80+
* const Koa = require("koa");
81+
*
82+
* const app = new Koa();
83+
*
84+
* Sentry.setupKoaErrorHandler(app);
85+
*
86+
* // Add your routes, etc.
87+
*
88+
* app.listen(3000);
89+
* ```
90+
*/
5391
// eslint-disable-next-line @typescript-eslint/no-explicit-any
5492
export const setupKoaErrorHandler = (app: { use: (arg0: (ctx: any, next: any) => Promise<void>) => void }): void => {
5593
app.use(async (ctx, next) => {

‎packages/node/src/integrations/tracing/lrumemoizer.ts

+10-2
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,16 @@ const _lruMemoizerIntegration = (() => {
1818
}) satisfies IntegrationFn;
1919

2020
/**
21-
* LruMemoizer integration
21+
* Adds Sentry tracing instrumentation for the [lru-memoizer](https://www.npmjs.com/package/lru-memoizer) library.
2222
*
23-
* Propagate traces through LruMemoizer.
23+
* For more information, see the [`lruMemoizerIntegration` documentation](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/lrumemoizer/).
24+
*
25+
* @example
26+
* ```javascript
27+
* const Sentry = require('@sentry/node');
28+
*
29+
* Sentry.init({
30+
* integrations: [Sentry.lruMemoizerIntegration()],
31+
* });
2432
*/
2533
export const lruMemoizerIntegration = defineIntegration(_lruMemoizerIntegration);

‎packages/node/src/integrations/tracing/mongo.ts

+11-2
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,17 @@ const _mongoIntegration = (() => {
2727
}) satisfies IntegrationFn;
2828

2929
/**
30-
* MongoDB integration
30+
* Adds Sentry tracing instrumentation for the [mongodb](https://www.npmjs.com/package/mongodb) library.
3131
*
32-
* Capture tracing data for MongoDB.
32+
* For more information, see the [`mongoIntegration` documentation](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/mongo/).
33+
*
34+
* @example
35+
* ```javascript
36+
* const Sentry = require('@sentry/node');
37+
*
38+
* Sentry.init({
39+
* integrations: [Sentry.mongoIntegration()],
40+
* });
41+
* ```
3342
*/
3443
export const mongoIntegration = defineIntegration(_mongoIntegration);

0 commit comments

Comments
 (0)