0
# SDK Initialization and Configuration
1

2
Core functions for initializing and configuring the Sentry SDK, including client management and default integrations.
3

4
## Capabilities
5

6
### SDK Initialization
7

8
Initialize the Sentry SDK with configuration options.
9

10
```typescript { .api }
11
/**
12
 * Initialize the Sentry SDK with configuration options
13
 * @param options - Configuration options for the SDK
14
 * @returns Initialized NodeClient instance or undefined if initialization fails
15
 */
16
function init(options?: NodeOptions): NodeClient | undefined;
17

18
/**
19
 * Initialize the Sentry SDK without default integrations
20
 * @param options - Configuration options for the SDK
21
 * @returns Initialized NodeClient instance or undefined if initialization fails
22
 */
23
function initWithoutDefaultIntegrations(options?: NodeOptions): NodeClient | undefined;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import * as Sentry from "@sentry/node";
30

31
// Basic initialization
32
Sentry.init({
33
  dsn: "https://your-dsn@sentry.io/project-id",
34
});
35

36
// Advanced initialization
37
Sentry.init({
38
  dsn: "https://your-dsn@sentry.io/project-id",
39
  environment: "production",
40
  release: "1.0.0",
41
  tracesSampleRate: 0.1,
42
  debug: false,
43
  integrations: [
44
    Sentry.httpIntegration(),
45
    Sentry.expressIntegration(),
46
  ],
47
  beforeSend: (event) => {
48
    // Modify event before sending
49
    return event;
50
  },
51
});
52

53
// Initialize without default integrations
54
Sentry.initWithoutDefaultIntegrations({
55
  dsn: "https://your-dsn@sentry.io/project-id",
56
  integrations: [
57
    // Add only the integrations you need
58
    Sentry.httpIntegration(),
59
  ],
60
});
61
```
62

63
### OpenTelemetry Integration
64

65
Initialize OpenTelemetry integration for automatic instrumentation.
66

67
```typescript { .api }
68
/**
69
 * Initialize OpenTelemetry integration for automatic instrumentation
70
 * @param client - Sentry NodeClient instance
71
 * @param options - OpenTelemetry configuration options
72
 */
73
function initOpenTelemetry(client: NodeClient, options?: OpenTelemetryOptions): void;
74

75
/**
76
 * Preload OpenTelemetry instrumentation without initializing Sentry
77
 * @param options - Preload configuration options
78
 */
79
function preloadOpenTelemetry(options?: PreloadOptions): void;
80

81
/**
82
 * Set Node.js async context strategy for OpenTelemetry
83
 */
84
function setNodeAsyncContextStrategy(): void;
85

86
/**
87
 * Validate OpenTelemetry setup and configuration
88
 */
89
function validateOpenTelemetrySetup(): void;
90
```
91

92
### Default Integrations
93

94
Get default integrations for the SDK.
95

96
```typescript { .api }
97
/**
98
 * Get default integrations for the SDK
99
 * @param options - Configuration options
100
 * @returns Array of default integrations
101
 */
102
function getDefaultIntegrations(options: Options): Integration[];
103

104
/**
105
 * Get default integrations without performance monitoring
106
 * @returns Array of default integrations excluding performance
107
 */
108
function getDefaultIntegrationsWithoutPerformance(): Integration[];
109

110
/**
111
 * Get automatic performance integrations
112
 * @returns Array of automatic performance integrations
113
 */
114
function getAutoPerformanceIntegrations(): Integration[];
115
```
116

117
### Client Management
118

119
Manage the Sentry client instance.
120

121
```typescript { .api }
122
/**
123
 * Get the current Sentry client
124
 * @returns Current client instance or undefined
125
 */
126
function getClient<C extends Client>(): C | undefined;
127

128
/**
129
 * Set the current Sentry client
130
 * @param client - Client instance to set as current
131
 */
132
function setCurrentClient(client: Client): void;
133

134
/**
135
 * Check if the SDK is initialized
136
 * @returns True if SDK is initialized
137
 */
138
function isInitialized(): boolean;
139

140
/**
141
 * Check if the SDK is enabled
142
 * @returns True if SDK is enabled
143
 */
144
function isEnabled(): boolean;
145
```
146

147
### SDK Lifecycle
148

149
Control SDK lifecycle and resource cleanup.
150

151
```typescript { .api }
152
/**
153
 * Close the SDK and flush any pending events
154
 * @param timeout - Maximum time to wait for cleanup in milliseconds
155
 * @returns Promise that resolves to true if successful
156
 */
157
function close(timeout?: number): PromiseLike<boolean>;
158

159
/**
160
 * Flush any pending events to Sentry
161
 * @param timeout - Maximum time to wait for flush in milliseconds
162
 * @returns Promise that resolves to true if successful
163
 */
164
function flush(timeout?: number): PromiseLike<boolean>;
165
```
166

167
### Integration Management
168

169
Add and manage integrations dynamically.
170

171
```typescript { .api }
172
/**
173
 * Add an integration to the current client
174
 * @param integration - Integration to add
175
 */
176
function addIntegration(integration: Integration): void;
177

178
/**
179
 * Add an event processor to the current client
180
 * @param processor - Event processor function
181
 */
182
function addEventProcessor(processor: EventProcessor): void;
183
```
184

185
## Node.js Specific Entry Points
186

187
### Auto-initialization Entry Point
188

189
For use with Node.js `--import` or `--require` flags to initialize Sentry automatically.
190

191
```typescript
192
// Use with: node --import @sentry/node/init app.js
193
// or: node --require @sentry/node/init app.js
194
import "@sentry/node/init";
195
```
196

197
This entry point reads configuration from environment variables:
198
- `SENTRY_DSN` - The DSN for your Sentry project
199
- `SENTRY_ENVIRONMENT` - Environment name (e.g., production, development)
200
- `SENTRY_RELEASE` - Release version
201
- `SENTRY_TRACES_SAMPLE_RATE` - Tracing sample rate (0.0 to 1.0)
202

203
### Preload Entry Point
204

205
For preloading OpenTelemetry instrumentation without initializing Sentry.
206

207
```typescript
208
// Use with: node --import @sentry/node/preload app.js
209
// or: node --require @sentry/node/preload app.js
210
import "@sentry/node/preload";
211
```
212

213
This is useful when you want to set up instrumentation but defer Sentry initialization until later in your application lifecycle.
214

215
## Types
216

217
### Configuration Options
218

219
```typescript { .api }
220
interface NodeOptions {
221
  /** Data Source Name for your Sentry project */
222
  dsn?: string;
223
  /** Enable debug logging */
224
  debug?: boolean;
225
  /** Sample rate for performance monitoring (0.0 to 1.0) */
226
  tracesSampleRate?: number;
227
  /** Environment name */
228
  environment?: string;
229
  /** Release version */
230
  release?: string;
231
  /** Server name for tagging */
232
  serverName?: string;
233
  /** Array of integrations to install */
234
  integrations?: Integration[];
235
  /** Hook called before sending events */
236
  beforeSend?: BeforeSendHook;
237
  /** Hook called before sending transactions */
238
  beforeSendTransaction?: BeforeSendHook;
239
  /** Maximum number of breadcrumbs to store */
240
  maxBreadcrumbs?: number;
241
  /** Attach stack traces to pure capture message calls */
242
  attachStacktrace?: boolean;
243
  /** Sample rate for error events (0.0 to 1.0) */
244
  sampleRate?: number;
245
  /** Maximum length for event values */
246
  maxValueLength?: number;
247
  /** Maximum depth for normalizing event data */
248
  normalizeDepth?: number;
249
  /** Maximum breadth for normalizing event data */
250
  normalizeMaxBreadth?: number;
251
  /** HTTP proxy URL */
252
  httpProxy?: string;
253
  /** HTTPS proxy URL */
254
  httpsProxy?: string;
255
  /** Skip automatic OpenTelemetry setup */
256
  skipOpenTelemetrySetup?: boolean;
257
  /** Include local variables in stack traces */
258
  includeLocalVariables?: boolean;
259
  /** Register ESM loader hooks for instrumentation */
260
  registerEsmLoaderHooks?: boolean;
261
  /** Enable automatic session tracking */
262
  autoSessionTracking?: boolean;
263
  /** Sample rate for profiling (0.0 to 1.0) */
264
  profilesSampleRate?: number;
265
}
266

267
interface OpenTelemetryOptions {
268
  /** Custom instrumentations to add */
269
  instrumentations?: Instrumentation[];
270
  /** Skip default instrumentations */
271
  skipDefaultInstrumentations?: boolean;
272
}
273

274
interface PreloadOptions {
275
  /** Custom instrumentations to preload */
276
  instrumentations?: Instrumentation[];
277
}
278
```
279

280
### Node Client
281

282
```typescript { .api }
283
interface NodeClient {
284
  /** Capture an exception */
285
  captureException(exception: any, hint?: EventHint, scope?: Scope): string;
286
  /** Capture a message */
287
  captureMessage(message: string, level?: SeverityLevel, hint?: EventHint, scope?: Scope): string;
288
  /** Capture a custom event */
289
  captureEvent(event: Event, hint?: EventHint, scope?: Scope): string;
290
  /** Close the client and flush events */
291
  close(timeout?: number): PromiseLike<boolean>;
292
  /** Flush pending events */
293
  flush(timeout?: number): PromiseLike<boolean>;
294
  /** Get the configured DSN */
295
  getDsn(): DsnLike | undefined;
296
  /** Get client options */
297
  getOptions(): Options;
298
  /** Get integration by name */
299
  getIntegrationByName<T extends Integration>(name: string): T | undefined;
300
}
301
```