@pingops/sdk 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# @pingops/sdk
+
+PingOps SDK for Node.js. Provides a simple API for bootstrapping OpenTelemetry and capturing outgoing API and LLM calls.
+
+## Installation
+
+```bash
+pnpm add @pingops/sdk
+```
+
+## Quick Start
+
+```typescript
+import { initializePingops } from "@pingops/sdk";
+
+initializePingops({
+  apiKey: "your-api-key", // or set PINGOPS_API_KEY env var
+  baseUrl: "https://api.pingops.com",
+  serviceName: "my-service",
+});
+```
+
+## Features
+
+- **Automatic Instrumentation**: Captures HTTP and fetch API calls automatically
+- **Node.js Support**: Works in Node.js environments (including Node.js 20+ with native fetch)
+- **GenAI Support**: Captures LLM calls using OpenTelemetry GenAI semantic conventions
+- **Manual Instrumentation**: Create custom spans for specific operations
+- **Zero Configuration**: Works out of the box with sensible defaults
+
+## API
+
+### `initializePingops(config)`
+
+Initializes the PingOps SDK with OpenTelemetry.
+
+**Configuration:**
+
+```typescript
+interface PingopsInitConfig {
+  apiKey?: string; // Defaults to PINGOPS_API_KEY env var
+  baseUrl: string; // Required
+  serviceName: string; // Required
+  debug?: boolean;
+  headersAllowList?: string[];
+  headersDenyList?: string[];
+  domainAllowList?: DomainRule[];
+  domainDenyList?: DomainRule[];
+  batchSize?: number; // Default: 50
+  batchTimeout?: number; // Default: 5000ms
+}
+```
+
+### `pingops.startSpan(name, attributes, fn)`
+
+Creates a manual span for custom instrumentation.
+
+```typescript
+import { pingops } from "@pingops/sdk";
+
+await pingops.startSpan(
+  "external.api.call",
+  {
+    customer_id: "cust_123",
+    correlation_id: "req_456",
+    "custom_attributes.request_type": "webhook",
+  },
+  async (span) => {
+    // Your code here
+    const result = await fetch("https://api.example.com/data");
+    return result.json();
+  }
+);
+```
+
+The span is automatically ended when the function completes or throws an error.
+
+### `shutdownPingops()`
+
+Gracefully shuts down the SDK and flushes remaining spans.
+
+```typescript
+import { shutdownPingops } from "@pingops/sdk";
+
+await shutdownPingops();
+```
+
+## Domain Filtering
+
+Control which domains and paths are captured:
+
+```typescript
+initializePingops({
+  // ... other config
+  domainAllowList: [
+    {
+      domain: "api.github.com",
+      paths: ["/repos"],
+      headersAllowList: ["authorization", "user-agent"],
+    },
+    {
+      domain: ".openai.com", // Suffix match
+    },
+  ],
+  domainDenyList: [
+    {
+      domain: "internal.service.local",
+    },
+  ],
+});
+```
+
+## Header Filtering
+
+Control which headers are captured:
+
+```typescript
+initializePingops({
+  // ... other config
+  headersAllowList: ["user-agent", "x-request-id"],
+  headersDenyList: ["authorization", "cookie"],
+});
+```
+
+## Integration with Existing OpenTelemetry
+
+If you already have OpenTelemetry set up, you can use just the `PingopsSpanProcessor`:
+
+```typescript
+import { PingopsSpanProcessor } from "@pingops/otel";
+import { getTracerProvider } from "@opentelemetry/api";
+
+const processor = new PingopsSpanProcessor({
+  apiKey: "your-api-key",
+  baseUrl: "https://api.pingops.com",
+  serviceName: "my-service",
+});
+
+const tracerProvider = getTracerProvider();
+// Add processor to your existing tracer provider
+```
+
+## What Gets Captured
+
+- **HTTP Requests**: All outgoing HTTP requests (via `http` module in Node.js)
+- **Fetch API**: All `fetch()` calls (universal JS)
+- **GenAI Calls**: LLM API calls that follow OpenTelemetry GenAI semantic conventions
+
+## What Doesn't Get Captured
+
+- Incoming requests (server-side)
+- Internal spans (non-CLIENT spans)
+- Spans without HTTP or GenAI attributes
+
+## Requirements
+
+- **Node.js**: Requires Node.js 20+ (for native fetch support) or Node.js 18+ with fetch polyfill

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Configuration types for @pingops/sdk
+ */
+import type { PingopsProcessorConfig } from '@pingops/otel';
+export interface PingopsInitConfig extends PingopsProcessorConfig {
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE5D,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;CAAG"}

package/dist/config.js

@@ -0,0 +1,5 @@
+/**
+ * Configuration types for @pingops/sdk
+ */
+export {};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @pingops/sdk - Public API
+ */
+export { initializePingops, shutdownPingops, wrapHttp } from "./pingops";
+export type { WrapHttpAttributes } from "@pingops/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACzE,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * @pingops/sdk - Public API
+ */
+export { initializePingops, shutdownPingops, wrapHttp } from "./pingops";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/init-state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared state for tracking SDK initialization
+ * This module exists to avoid circular dependencies between pingops.ts and instrumentation.ts
+ */
+/**
+ * Sets the SDK initialization flag.
+ * Called by initializePingops when the SDK is initialized.
+ */
+export declare function setSdkInitialized(initialized: boolean): void;
+/**
+ * Checks if global instrumentation is enabled.
+ * This is used to determine instrumentation behavior:
+ * - If true: all HTTP requests are instrumented
+ * - If false: only requests within wrapHttp blocks are instrumented
+ */
+export declare function isGlobalInstrumentationEnabled(): boolean;
+//# sourceMappingURL=init-state.d.ts.map

package/dist/init-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-state.d.ts","sourceRoot":"","sources":["../src/init-state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,IAAI,OAAO,CAExD"}

package/dist/init-state.js

@@ -0,0 +1,22 @@
+/**
+ * Shared state for tracking SDK initialization
+ * This module exists to avoid circular dependencies between pingops.ts and instrumentation.ts
+ */
+let isSdkInitializedFlag = false;
+/**
+ * Sets the SDK initialization flag.
+ * Called by initializePingops when the SDK is initialized.
+ */
+export function setSdkInitialized(initialized) {
+    isSdkInitializedFlag = initialized;
+}
+/**
+ * Checks if global instrumentation is enabled.
+ * This is used to determine instrumentation behavior:
+ * - If true: all HTTP requests are instrumented
+ * - If false: only requests within wrapHttp blocks are instrumented
+ */
+export function isGlobalInstrumentationEnabled() {
+    return isSdkInitializedFlag;
+}
+//# sourceMappingURL=init-state.js.map

package/dist/init-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-state.js","sourceRoot":"","sources":["../src/init-state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,IAAI,oBAAoB,GAAG,KAAK,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAoB;IACpD,oBAAoB,GAAG,WAAW,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B;IAC5C,OAAO,oBAAoB,CAAC;AAC9B,CAAC"}

package/dist/initialize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Initializes PingOps SDK with OpenTelemetry
+ */
+import type { PingopsProcessorConfig } from '@pingops/otel';
+/**
+ * Initializes PingOps SDK
+ *
+ * This function:
+ * 1. Creates an OpenTelemetry NodeSDK instance
+ * 2. Configures Resource with service.name
+ * 3. Registers PingopsSpanProcessor
+ * 4. Enables HTTP/fetch/GenAI instrumentation
+ * 5. Starts the SDK
+ */
+export declare function initializePingops(config: PingopsProcessorConfig): void;
+/**
+ * Shuts down the SDK and flushes remaining spans
+ */
+export declare function shutdownPingops(): Promise<void>;
+//# sourceMappingURL=initialize.d.ts.map

package/dist/initialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize.d.ts","sourceRoot":"","sources":["../src/initialize.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAe5D;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CA4DtE;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAWrD"}

package/dist/initialize.js

@@ -0,0 +1,86 @@
+/**
+ * Initializes PingOps SDK with OpenTelemetry
+ */
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { getInstrumentations } from './instrumentation';
+import { setPingopsTracerProvider, shutdownTracerProvider, PingopsSpanProcessor, } from '@pingops/otel';
+import { createLogger } from '@pingops/core';
+let sdkInstance = null;
+let isInitialized = false;
+const logger = createLogger('[PingOps Initialize]');
+/**
+ * Initializes PingOps SDK
+ *
+ * This function:
+ * 1. Creates an OpenTelemetry NodeSDK instance
+ * 2. Configures Resource with service.name
+ * 3. Registers PingopsSpanProcessor
+ * 4. Enables HTTP/fetch/GenAI instrumentation
+ * 5. Starts the SDK
+ */
+export function initializePingops(config) {
+    if (isInitialized) {
+        if (config.debug) {
+            logger.warn('[PingOps] SDK already initialized, skipping');
+        }
+        return;
+    }
+    // Create resource with service name
+    const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: config.serviceName,
+    });
+    // Create PingopsSpanProcessor
+    const processor = new PingopsSpanProcessor(config);
+    // Get instrumentations only if autoInstrumentation is enabled (defaults to true)
+    const autoInstrumentation = config.autoInstrumentation !== false;
+    const instrumentations = autoInstrumentation ? getInstrumentations() : [];
+    // Node.js SDK
+    const nodeSdk = new NodeSDK({
+        resource,
+        spanProcessors: [processor],
+        instrumentations,
+    });
+    nodeSdk.start();
+    sdkInstance = nodeSdk;
+    // Initialize isolated TracerProvider for manual spans AFTER NodeSDK starts
+    // This ensures manual spans created via startSpan are processed by the same processor
+    // We register it after NodeSDK so it takes precedence as the global provider
+    try {
+        // In version 2.2.0, span processors are passed in the constructor
+        const isolatedProvider = new NodeTracerProvider({
+            resource,
+            spanProcessors: [processor],
+        });
+        // Register the provider globally
+        isolatedProvider.register();
+        // Set it in global state
+        setPingopsTracerProvider(isolatedProvider);
+    }
+    catch (error) {
+        if (config.debug) {
+            logger.error('[PingOps] Failed to create isolated TracerProvider:', error instanceof Error ? error.message : String(error));
+        }
+        // Continue without isolated provider - manual spans will use global provider
+    }
+    if (config.debug) {
+        logger.info('[PingOps] SDK initialized');
+    }
+    isInitialized = true;
+}
+/**
+ * Shuts down the SDK and flushes remaining spans
+ */
+export async function shutdownPingops() {
+    // Shutdown isolated TracerProvider first
+    await shutdownTracerProvider();
+    if (!sdkInstance) {
+        return;
+    }
+    await sdkInstance.shutdown();
+    sdkInstance = null;
+    isInitialized = false;
+}
+//# sourceMappingURL=initialize.js.map

package/dist/initialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize.js","sourceRoot":"","sources":["../src/initialize.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,IAAI,WAAW,GAAmB,IAAI,CAAC;AACvC,IAAI,aAAa,GAAG,KAAK,CAAC;AAE1B,MAAM,MAAM,GAAG,YAAY,CAAC,sBAAsB,CAAC,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA8B;IAC9D,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO;IACT,CAAC;IAED,oCAAoC;IACpC,MAAM,QAAQ,GAAG,sBAAsB,CAAC;QACpC,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,WAAW;KACxC,CAAC,CAAC;IAEL,8BAA8B;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAEnD,iFAAiF;IACjF,MAAM,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,KAAK,KAAK,CAAC;IACjE,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAE1E,cAAc;IACd,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC;QAC1B,QAAQ;QACR,cAAc,EAAE,CAAC,SAAS,CAAC;QAC3B,gBAAgB;KACjB,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,WAAW,GAAG,OAAO,CAAC;IAEtB,2EAA2E;IAC3E,sFAAsF;IACtF,6EAA6E;IAC7E,IAAI,CAAC;QACH,kEAAkE;QAClE,MAAM,gBAAgB,GAAG,IAAI,kBAAkB,CAAC;YAC9C,QAAQ;YACR,cAAc,EAAE,CAAC,SAAgB,CAAC;SACnC,CAAC,CAAC;QAEH,iCAAiC;QACjC,gBAAgB,CAAC,QAAQ,EAAE,CAAC;QAE5B,yBAAyB;QACzB,wBAAwB,CAAC,gBAAgB,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,CAAC,KAAK,CACV,qDAAqD,EACrD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;QACJ,CAAC;QACD,6EAA6E;IAC/E,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAC3C,CAAC;IAED,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,yCAAyC;IACzC,MAAM,sBAAsB,EAAE,CAAC;IAE/B,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IAED,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;IAC7B,WAAW,GAAG,IAAI,CAAC;IACnB,aAAa,GAAG,KAAK,CAAC;AACxB,CAAC"}

package/dist/instrumentation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Instrumentation setup for HTTP, fetch, undici, and GenAI
+ */
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+/**
+ * Registers instrumentations for Node.js environment.
+ * This function is idempotent and can be called multiple times safely.
+ *
+ * Instrumentation behavior:
+ * - If global instrumentation is enabled: all HTTP requests are instrumented
+ * - If global instrumentation is NOT enabled: only requests within wrapHttp blocks are instrumented
+ */
+export declare function getInstrumentations(): Instrumentation[];
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAOtE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,CAwEvD"}

package/dist/instrumentation.js

@@ -0,0 +1,76 @@
+/**
+ * Instrumentation setup for HTTP, fetch, undici, and GenAI
+ */
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import { context } from '@opentelemetry/api';
+import { PINGOPS_HTTP_ENABLED, normalizeHeaders } from '@pingops/core';
+import { isGlobalInstrumentationEnabled } from './init-state';
+let installed = false;
+/**
+ * Registers instrumentations for Node.js environment.
+ * This function is idempotent and can be called multiple times safely.
+ *
+ * Instrumentation behavior:
+ * - If global instrumentation is enabled: all HTTP requests are instrumented
+ * - If global instrumentation is NOT enabled: only requests within wrapHttp blocks are instrumented
+ */
+export function getInstrumentations() {
+    if (installed) {
+        return [];
+    }
+    registerInstrumentations({
+        instrumentations: [
+            new HttpInstrumentation({
+                ignoreIncomingRequestHook: () => true, // Only instrument outgoing requests
+                ignoreOutgoingRequestHook: () => {
+                    // If global instrumentation is enabled, instrument all outgoing requests
+                    if (isGlobalInstrumentationEnabled()) {
+                        return false;
+                    }
+                    // If global instrumentation is NOT enabled, only instrument when PINGOPS_HTTP_ENABLED is true
+                    return context.active().getValue(PINGOPS_HTTP_ENABLED) !== true;
+                },
+                requestHook: (span, request) => {
+                    const headers = normalizeHeaders(request.headers);
+                    for (const [key, value] of Object.entries(headers)) {
+                        span.setAttribute(`http.request.header.${key.toLowerCase()}`, Array.isArray(value) ? value.join(',') : String(value));
+                    }
+                },
+                responseHook: (span, response) => {
+                    const headers = normalizeHeaders(response.headers);
+                    for (const [key, value] of Object.entries(headers)) {
+                        span.setAttribute(`http.response.header.${key.toLowerCase()}`, Array.isArray(value) ? value.join(',') : String(value));
+                    }
+                },
+            }),
+            new UndiciInstrumentation({
+                enabled: true,
+                ignoreRequestHook: () => {
+                    // If global instrumentation is enabled, instrument all requests
+                    if (isGlobalInstrumentationEnabled()) {
+                        return false;
+                    }
+                    // If global instrumentation is NOT enabled, only instrument when PINGOPS_HTTP_ENABLED is true
+                    return context.active().getValue(PINGOPS_HTTP_ENABLED) !== true;
+                },
+                requestHook: (span, request) => {
+                    const headers = normalizeHeaders(request.headers);
+                    for (const [key, value] of Object.entries(headers)) {
+                        span.setAttribute(`http.request.header.${key.toLowerCase()}`, Array.isArray(value) ? value.join(',') : String(value));
+                    }
+                },
+                responseHook: (span, { response }) => {
+                    const headers = normalizeHeaders(response.headers);
+                    for (const [key, value] of Object.entries(headers)) {
+                        span.setAttribute(`http.response.header.${key.toLowerCase()}`, Array.isArray(value) ? value.join(',') : String(value));
+                    }
+                },
+            }),
+        ],
+    });
+    installed = true;
+    return [];
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Global logger utility for PingOps SDK
+ *
+ * Provides consistent logging across all SDK components with support for
+ * different log levels and debug mode control via PINGOPS_DEBUG environment variable.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Creates a logger instance with a specific prefix
+ *
+ * @param prefix - Prefix to add to all log messages (e.g., '[PingOps TracerProvider]')
+ * @returns Logger instance
+ */
+export declare function createLogger(prefix: string): Logger;
+/**
+ * Default logger instance for general SDK logging
+ */
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAwBnD;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,QAAgC,CAAC"}

package/dist/logger.js

@@ -0,0 +1,40 @@
+/**
+ * Global logger utility for PingOps SDK
+ *
+ * Provides consistent logging across all SDK components with support for
+ * different log levels and debug mode control via PINGOPS_DEBUG environment variable.
+ */
+/**
+ * Creates a logger instance with a specific prefix
+ *
+ * @param prefix - Prefix to add to all log messages (e.g., '[PingOps TracerProvider]')
+ * @returns Logger instance
+ */
+export function createLogger(prefix) {
+    const isDebugEnabled = true;
+    const formatMessage = (level, message) => {
+        const timestamp = new Date().toISOString();
+        return `[${timestamp}] ${prefix} [${level.toUpperCase()}] ${message}`;
+    };
+    return {
+        debug(message, ...args) {
+            if (isDebugEnabled) {
+                console.debug(formatMessage('debug', message), ...args);
+            }
+        },
+        info(message, ...args) {
+            console.log(formatMessage('info', message), ...args);
+        },
+        warn(message, ...args) {
+            console.warn(formatMessage('warn', message), ...args);
+        },
+        error(message, ...args) {
+            console.error(formatMessage('error', message), ...args);
+        },
+    };
+}
+/**
+ * Default logger instance for general SDK logging
+ */
+export const logger = createLogger('[PingOps SDK]');
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,cAAc,GAAG,IAAI,CAAC;IAE5B,MAAM,aAAa,GAAG,CAAC,KAAe,EAAE,OAAe,EAAU,EAAE;QACjE,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,OAAO,IAAI,SAAS,KAAK,MAAM,KAAK,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,CAAC;IACxE,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;YACvC,IAAI,cAAc,EAAE,CAAC;gBACnB,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;YACtC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;YACtC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QACxD,CAAC;QACD,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;YACvC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1D,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC"}

package/dist/pingops.d.ts

@@ -0,0 +1,85 @@
+/**
+ * PingOps SDK singleton for manual instrumentation
+ *
+ * Provides initializePingops and shutdownPingops functions.
+ * wrapHttp is available from @pingops/core and will auto-initialize
+ * from environment variables if needed.
+ */
+import type { PingopsProcessorConfig } from "@pingops/otel";
+import { type WrapHttpAttributes } from "@pingops/core";
+/**
+ * Initializes PingOps SDK
+ *
+ * This function:
+ * 1. Creates an OpenTelemetry NodeSDK instance
+ * 2. Configures Resource with service.name
+ * 3. Registers PingopsSpanProcessor
+ * 4. Enables HTTP/fetch/GenAI instrumentation
+ * 5. Starts the SDK
+ *
+ * @param config - Configuration for the SDK
+ * @param explicit - Whether this is an explicit call (default: true).
+ *                   Set to false when called internally by wrapHttp auto-initialization.
+ */
+export declare function initializePingops(config: PingopsProcessorConfig, explicit?: boolean): void;
+/**
+ * Shuts down the SDK and flushes remaining spans
+ */
+export declare function shutdownPingops(): Promise<void>;
+/**
+ * Wraps a function to set attributes on HTTP spans created within the wrapped block.
+ *
+ * This function sets attributes (userId, sessionId, tags, metadata) in the OpenTelemetry
+ * context, which are automatically propagated to all spans created within the wrapped function.
+ *
+ * Instrumentation behavior:
+ * - If `initializePingops` was called: All HTTP requests are instrumented by default.
+ *   `wrapHttp` only adds attributes to spans created within the wrapped block.
+ * - If `initializePingops` was NOT called: Only HTTP requests within `wrapHttp` blocks
+ *   are instrumented. Requests outside `wrapHttp` are not instrumented.
+ *
+ * @param options - Options including attributes to propagate to spans
+ * @param fn - Function to execute within the attribute context
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * import { wrapHttp } from '@pingops/sdk';
+ *
+ * // Scenario 1: initializePingops was called
+ * initializePingops({ ... });
+ *
+ * // All HTTP requests are instrumented, but this block adds attributes
+ * const result = await wrapHttp({
+ *   attributes: {
+ *     userId: 'user-123',
+ *     sessionId: 'session-456',
+ *     tags: ['production', 'api'],
+ *     metadata: { environment: 'prod', version: '1.0.0' }
+ *   }
+ * }, async () => {
+ *   // This HTTP request will be instrumented AND have the attributes set above
+ *   const response = await fetch('https://api.example.com/users/123');
+ *   return response.json();
+ * });
+ *
+ * // HTTP requests outside wrapHttp are still instrumented, just without the attributes
+ * const otherResponse = await fetch('https://api.example.com/other');
+ *
+ * // Scenario 2: initializePingops was NOT called
+ * // Only requests within wrapHttp are instrumented
+ * await wrapHttp({
+ *   attributes: { userId: 'user-123' }
+ * }, async () => {
+ *   // This request IS instrumented
+ *   return fetch('https://api.example.com/data');
+ * });
+ *
+ * // This request is NOT instrumented (outside wrapHttp)
+ * await fetch('https://api.example.com/other');
+ * ```
+ */
+export declare function wrapHttp<T>(options: {
+    attributes?: WrapHttpAttributes;
+}, fn: () => T | Promise<T>): T | Promise<T>;
+//# sourceMappingURL=pingops.d.ts.map

package/dist/pingops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pingops.d.ts","sourceRoot":"","sources":["../src/pingops.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAW5D,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAgBvB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,GAAE,OAAc,GACvB,IAAI,CA6DN;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAYrD;AA+GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,OAAO,EAAE;IAAE,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAAE,EAC5C,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUhB"}