# SDK Initialization and Configuration

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

## Capabilities

### SDK Initialization

Initialize the Sentry SDK with configuration options.

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

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

**Usage Examples:**

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

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

// Advanced initialization
Sentry.init({
  dsn: "https://your-dsn@sentry.io/project-id",
  environment: "production",
  release: "1.0.0",
  tracesSampleRate: 0.1,
  debug: false,
  integrations: [
    Sentry.httpIntegration(),
    Sentry.expressIntegration(),
  ],
  beforeSend: (event) => {
    // Modify event before sending
    return event;
  },
});

// Initialize without default integrations
Sentry.initWithoutDefaultIntegrations({
  dsn: "https://your-dsn@sentry.io/project-id",
  integrations: [
    // Add only the integrations you need
    Sentry.httpIntegration(),
  ],
});
```

### OpenTelemetry Integration

Initialize OpenTelemetry integration for automatic instrumentation.

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

/**
 * Preload OpenTelemetry instrumentation without initializing Sentry
 * @param options - Preload configuration options
 */
function preloadOpenTelemetry(options?: PreloadOptions): void;

/**
 * Set Node.js async context strategy for OpenTelemetry
 */
function setNodeAsyncContextStrategy(): void;

/**
 * Validate OpenTelemetry setup and configuration
 */
function validateOpenTelemetrySetup(): void;
```

### Default Integrations

Get default integrations for the SDK.

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

/**
 * Get default integrations without performance monitoring
 * @returns Array of default integrations excluding performance
 */
function getDefaultIntegrationsWithoutPerformance(): Integration[];

/**
 * Get automatic performance integrations
 * @returns Array of automatic performance integrations
 */
function getAutoPerformanceIntegrations(): Integration[];
```

### Client Management

Manage the Sentry client instance.

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

/**
 * Set the current Sentry client
 * @param client - Client instance to set as current
 */
function setCurrentClient(client: Client): void;

/**
 * Check if the SDK is initialized
 * @returns True if SDK is initialized
 */
function isInitialized(): boolean;

/**
 * Check if the SDK is enabled
 * @returns True if SDK is enabled
 */
function isEnabled(): boolean;
```

### SDK Lifecycle

Control SDK lifecycle and resource cleanup.

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

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

### Integration Management

Add and manage integrations dynamically.

```typescript { .api }
/**
 * Add an integration to the current client
 * @param integration - Integration to add
 */
function addIntegration(integration: Integration): void;

/**
 * Add an event processor to the current client
 * @param processor - Event processor function
 */
function addEventProcessor(processor: EventProcessor): void;
```

## Node.js Specific Entry Points

### Auto-initialization Entry Point

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

```typescript
// Use with: node --import @sentry/node/init app.js
// or: node --require @sentry/node/init app.js
import "@sentry/node/init";
```

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

### Preload Entry Point

For preloading OpenTelemetry instrumentation without initializing Sentry.

```typescript
// Use with: node --import @sentry/node/preload app.js
// or: node --require @sentry/node/preload app.js
import "@sentry/node/preload";
```

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

## Types

### Configuration Options

```typescript { .api }
interface NodeOptions {
  /** Data Source Name for your Sentry project */
  dsn?: string;
  /** Enable debug logging */
  debug?: boolean;
  /** Sample rate for performance monitoring (0.0 to 1.0) */
  tracesSampleRate?: number;
  /** Environment name */
  environment?: string;
  /** Release version */
  release?: string;
  /** Server name for tagging */
  serverName?: string;
  /** Array of integrations to install */
  integrations?: Integration[];
  /** Hook called before sending events */
  beforeSend?: BeforeSendHook;
  /** Hook called before sending transactions */
  beforeSendTransaction?: BeforeSendHook;
  /** Maximum number of breadcrumbs to store */
  maxBreadcrumbs?: number;
  /** Attach stack traces to pure capture message calls */
  attachStacktrace?: boolean;
  /** Sample rate for error events (0.0 to 1.0) */
  sampleRate?: number;
  /** Maximum length for event values */
  maxValueLength?: number;
  /** Maximum depth for normalizing event data */
  normalizeDepth?: number;
  /** Maximum breadth for normalizing event data */
  normalizeMaxBreadth?: number;
  /** HTTP proxy URL */
  httpProxy?: string;
  /** HTTPS proxy URL */
  httpsProxy?: string;
  /** Skip automatic OpenTelemetry setup */
  skipOpenTelemetrySetup?: boolean;
  /** Include local variables in stack traces */
  includeLocalVariables?: boolean;
  /** Register ESM loader hooks for instrumentation */
  registerEsmLoaderHooks?: boolean;
  /** Enable automatic session tracking */
  autoSessionTracking?: boolean;
  /** Sample rate for profiling (0.0 to 1.0) */
  profilesSampleRate?: number;
}

interface OpenTelemetryOptions {
  /** Custom instrumentations to add */
  instrumentations?: Instrumentation[];
  /** Skip default instrumentations */
  skipDefaultInstrumentations?: boolean;
}

interface PreloadOptions {
  /** Custom instrumentations to preload */
  instrumentations?: Instrumentation[];
}
```

### Node Client

```typescript { .api }
interface NodeClient {
  /** Capture an exception */
  captureException(exception: any, hint?: EventHint, scope?: Scope): string;
  /** Capture a message */
  captureMessage(message: string, level?: SeverityLevel, hint?: EventHint, scope?: Scope): string;
  /** Capture a custom event */
  captureEvent(event: Event, hint?: EventHint, scope?: Scope): string;
  /** Close the client and flush events */
  close(timeout?: number): PromiseLike<boolean>;
  /** Flush pending events */
  flush(timeout?: number): PromiseLike<boolean>;
  /** Get the configured DSN */
  getDsn(): DsnLike | undefined;
  /** Get client options */
  getOptions(): Options;
  /** Get integration by name */
  getIntegrationByName<T extends Integration>(name: string): T | undefined;
}
```