@pingops/otel 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -0,0 +1,342 @@
+import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { DomainRule, HeaderRedactionConfig } from "@pingops/core";
+import { Attributes, Context, Span as Span$1, TracerProvider } from "@opentelemetry/api";
+import "@opentelemetry/sdk-trace-node";
+import { HttpInstrumentation, HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
+import { Instrumentation, InstrumentationBase, InstrumentationConfig } from "@opentelemetry/instrumentation";
+
+//#region src/config.d.ts
+
+/**
+ * Span export mode to use.
+ *
+ * - **batched**: Recommended for production environments with long-running processes.
+ *   Spans are batched and exported in groups for optimal performance.
+ * - **immediate**: Recommended for short-lived environments such as serverless functions.
+ *   Spans are exported immediately to prevent data loss when the process terminates / is frozen.
+ *
+ * @defaultValue "batched"
+ */
+type PingopsExportMode = "immediate" | "batched";
+/**
+ * Configuration parameters for the PingopsSpanProcessor.
+ */
+interface PingopsProcessorConfig {
+  /**
+   * API key for authentication. Can also be set via PINGOPS_API_KEY environment variable.
+   */
+  apiKey?: string;
+  /**
+   * PingOps backend base URL (required).
+   */
+  baseUrl: string;
+  /**
+   * Enable debug logging.
+   * @defaultValue false
+   */
+  debug?: boolean;
+  /**
+   * Service name for resource identification (required).
+   */
+  serviceName: string;
+  /**
+   * List of headers to include (case-insensitive).
+   */
+  headersAllowList?: string[];
+  /**
+   * List of headers to exclude (case-insensitive, takes precedence over allow list).
+   */
+  headersDenyList?: string[];
+  /**
+   * Capture request body.
+   */
+  captureRequestBody?: boolean;
+  /**
+   * Capture response body.
+   */
+  captureResponseBody?: boolean;
+  /**
+   * Domain allow list rules.
+   */
+  domainAllowList?: DomainRule[];
+  /**
+   * Domain deny list rules.
+   */
+  domainDenyList?: DomainRule[];
+  /**
+   * Configuration for header value redaction.
+   * If not provided, default redaction is enabled for sensitive headers.
+   */
+  headerRedaction?: HeaderRedactionConfig;
+  /**
+   * Number of spans to batch before flushing (only used in batched mode).
+   * @defaultValue 50
+   */
+  batchSize?: number;
+  /**
+   * Flush interval in milliseconds (only used in batched mode).
+   * @defaultValue 5000
+   */
+  batchTimeout?: number;
+  /**
+   * Span export mode to use.
+   *
+   * - **batched**: Recommended for production environments with long-running processes.
+   *   Spans are batched and exported in groups for optimal performance.
+   * - **immediate**: Recommended for short-lived environments such as serverless functions.
+   *   Spans are exported immediately to prevent data loss when the process terminates / is frozen.
+   *
+   * @defaultValue "batched"
+   */
+  exportMode?: PingopsExportMode;
+}
+//#endregion
+//#region src/span-processor.d.ts
+
+/**
+ * OpenTelemetry span processor for sending spans to PingOps backend.
+ *
+ * This processor wraps OpenTelemetry's built-in processors (BatchSpanProcessor or SimpleSpanProcessor)
+ * and applies filtering before passing spans to the OTLP exporter.
+ */
+declare class PingopsSpanProcessor implements SpanProcessor {
+  private processor;
+  private config;
+  /**
+   * Creates a new PingopsSpanProcessor instance.
+   *
+   * @param config - Configuration parameters for the processor
+   */
+  constructor(config: PingopsProcessorConfig);
+  /**
+   * Called when a span starts - extracts parent attributes from context and adds them to the span
+   */
+  onStart(span: Span, parentContext: Context): void;
+  /**
+   * Called when a span ends. Filters the span and passes it to the underlying processor if eligible.
+   *
+   * This method:
+   * 1. Checks if the span is eligible (CLIENT + HTTP/GenAI attributes)
+   * 2. Applies domain filtering (determines if span should be exported)
+   * 3. Applies header filtering via FilteredSpan wrapper (domain-specific and global rules)
+   * 4. If eligible, passes filtered span to underlying OTLP processor for export
+   */
+  onEnd(span: ReadableSpan): void;
+  /**
+   * Forces an immediate flush of all pending spans.
+   *
+   * @returns Promise that resolves when all pending operations are complete
+   */
+  forceFlush(): Promise<void>;
+  /**
+   * Gracefully shuts down the processor, ensuring all pending operations are completed.
+   *
+   * @returns Promise that resolves when shutdown is complete
+   */
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/tracer-provider.d.ts
+/**
+ * Sets an isolated TracerProvider for PingOps tracing operations.
+ *
+ * This allows PingOps to use its own TracerProvider instance, separate from
+ * the global OpenTelemetry TracerProvider. This is useful for avoiding conflicts
+ * with other OpenTelemetry instrumentation in the application.
+ *
+ * @param provider - The TracerProvider instance to use, or null to clear the isolated provider
+ * @public
+ */
+declare function setPingopsTracerProvider(provider: TracerProvider | null): void;
+/**
+ * Gets the TracerProvider for PingOps tracing operations.
+ *
+ * Returns the isolated TracerProvider if one has been set via setPingopsTracerProvider(),
+ * otherwise falls back to the global OpenTelemetry TracerProvider.
+ *
+ * @returns The TracerProvider instance to use for PingOps tracing
+ * @public
+ */
+declare function getPingopsTracerProvider(): TracerProvider;
+/**
+ * Shuts down the TracerProvider and flushes remaining spans
+ */
+declare function shutdownTracerProvider(): Promise<void>;
+//#endregion
+//#region src/instrumentations/index.d.ts
+/**
+ * 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
+ *
+ * @param isGlobalInstrumentationEnabled - Function that checks if global instrumentation is enabled
+ * @returns Array of Instrumentation instances
+ */
+declare function getInstrumentations(isGlobalInstrumentationEnabled: () => boolean): Instrumentation[];
+//#endregion
+//#region src/instrumentations/http/pingops-http.d.ts
+declare const PingopsSemanticAttributes: {
+  HTTP_REQUEST_BODY: string;
+  HTTP_RESPONSE_BODY: string;
+  NETWORK_DNS_LOOKUP_DURATION: string;
+  NETWORK_TCP_CONNECT_DURATION: string;
+  NETWORK_TLS_HANDSHAKE_DURATION: string;
+  NETWORK_TTFB_DURATION: string;
+  NETWORK_CONTENT_TRANSFER_DURATION: string;
+};
+type NetworkTimings = {
+  startAt?: number;
+  dnsLookupAt?: number;
+  tcpConnectionAt?: number;
+  tlsHandshakeAt?: number;
+  firstByteAt?: number;
+  endAt?: number;
+};
+interface PingopsInstrumentationConfig {
+  /**
+   * Maximum size of request body to capture in bytes
+   * @defaultValue 4096 (4 KB)
+   */
+  maxRequestBodySize?: number;
+  /**
+   * Maximum size of response body to capture in bytes
+   * @defaultValue 4096 (4 KB)
+   */
+  maxResponseBodySize?: number;
+}
+declare const PingopsHttpSemanticAttributes: {
+  HTTP_REQUEST_BODY: string;
+  HTTP_RESPONSE_BODY: string;
+  NETWORK_DNS_LOOKUP_DURATION: string;
+  NETWORK_TCP_CONNECT_DURATION: string;
+  NETWORK_TLS_HANDSHAKE_DURATION: string;
+  NETWORK_TTFB_DURATION: string;
+  NETWORK_CONTENT_TRANSFER_DURATION: string;
+};
+interface PingopsHttpInstrumentationConfig extends HttpInstrumentationConfig, PingopsInstrumentationConfig {}
+declare class PingopsHttpInstrumentation extends HttpInstrumentation {
+  constructor(config?: PingopsHttpInstrumentationConfig);
+  private _createConfig;
+  private _createRequestHook;
+  private _createResponseHook;
+}
+//#endregion
+//#region src/instrumentations/http/http.d.ts
+/**
+ * Creates an HTTP instrumentation instance
+ *
+ * @param isGlobalInstrumentationEnabled - Function that checks if global instrumentation is enabled
+ * @param config - Optional configuration for the instrumentation
+ * @returns PingopsHttpInstrumentation instance
+ */
+declare function createHttpInstrumentation(isGlobalInstrumentationEnabled: () => boolean, config?: Partial<PingopsHttpInstrumentationConfig>): PingopsHttpInstrumentation;
+//#endregion
+//#region src/instrumentations/undici/types.d.ts
+interface UndiciRequest {
+  origin: string;
+  method: string;
+  path: string;
+  /**
+   * Serialized string of headers in the form `name: value\r\n` for v5
+   * Array of strings `[key1, value1, key2, value2]`, where values are
+   * `string | string[]` for v6
+   */
+  headers: string | (string | string[])[];
+  /**
+   * Helper method to add headers (from v6)
+   */
+  addHeader: (name: string, value: string) => void;
+  throwOnError: boolean;
+  completed: boolean;
+  aborted: boolean;
+  idempotent: boolean;
+  contentLength: number | null;
+  contentType: string | null;
+  body: any;
+}
+interface UndiciResponse {
+  headers: Buffer[];
+  statusCode: number;
+  statusText: string;
+}
+interface IgnoreRequestFunction<T = UndiciRequest> {
+  (request: T): boolean;
+}
+interface RequestHookFunction<T = UndiciRequest> {
+  (span: Span$1, request: T): void;
+}
+interface ResponseHookFunction<RequestType = UndiciRequest, ResponseType = UndiciResponse> {
+  (span: Span$1, info: {
+    request: RequestType;
+    response: ResponseType;
+  }): void;
+}
+interface StartSpanHookFunction<T = UndiciRequest> {
+  (request: T): Attributes;
+}
+interface UndiciInstrumentationConfig<RequestType = UndiciRequest, ResponseType = UndiciResponse> extends InstrumentationConfig {
+  /** Not trace all outgoing requests that matched with custom function */
+  ignoreRequestHook?: IgnoreRequestFunction<RequestType>;
+  /** Function for adding custom attributes before request is handled */
+  requestHook?: RequestHookFunction<RequestType>;
+  /** Function called once response headers have been received */
+  responseHook?: ResponseHookFunction<RequestType, ResponseType>;
+  /** Function for adding custom attributes before a span is started */
+  startSpanHook?: StartSpanHookFunction<RequestType>;
+  /** Require parent to create span for outgoing requests */
+  requireParentforSpans?: boolean;
+  /** Map the following HTTP headers to span attributes. */
+  headersToSpanAttributes?: {
+    requestHeaders?: string[];
+    responseHeaders?: string[];
+  };
+  /**
+   * Maximum size of request body to capture in bytes
+   * @defaultValue 4096 (4 KB)
+   */
+  maxRequestBodySize?: number;
+  /**
+   * Maximum size of response body to capture in bytes
+   * @defaultValue 4096 (4 KB)
+   */
+  maxResponseBodySize?: number;
+}
+//#endregion
+//#region src/instrumentations/undici/pingops-undici.d.ts
+declare class UndiciInstrumentation extends InstrumentationBase<UndiciInstrumentationConfig> {
+  private _channelSubs;
+  private _recordFromReq;
+  private _httpClientDurationHistogram;
+  constructor(config?: UndiciInstrumentationConfig);
+  protected init(): undefined;
+  disable(): void;
+  enable(): void;
+  protected _updateMetricInstruments(): void;
+  private subscribeToChannel;
+  private parseRequestHeaders;
+  private onRequestCreated;
+  private onRequestHeaders;
+  private onResponseHeaders;
+  private onDone;
+  private onError;
+  private onBodyChunkSent;
+  private onBodySent;
+  private onBodyChunkReceived;
+  private recordRequestDuration;
+  private getRequestMethod;
+}
+//#endregion
+//#region src/instrumentations/undici/undici.d.ts
+/**
+ * Creates an Undici instrumentation instance
+ *
+ * @param isGlobalInstrumentationEnabled - Function that checks if global instrumentation is enabled
+ * @returns UndiciInstrumentation instance
+ */
+declare function createUndiciInstrumentation(isGlobalInstrumentationEnabled: () => boolean): UndiciInstrumentation;
+//#endregion
+export { type NetworkTimings, PingopsHttpInstrumentation, type PingopsHttpInstrumentationConfig, PingopsHttpSemanticAttributes, type PingopsInstrumentationConfig, type PingopsProcessorConfig, PingopsSemanticAttributes, PingopsSpanProcessor, createHttpInstrumentation, createUndiciInstrumentation, getInstrumentations, getPingopsTracerProvider, setPingopsTracerProvider, shutdownTracerProvider };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/span-processor.ts","../src/tracer-provider.ts","../src/instrumentations/index.ts","../src/instrumentations/http/pingops-http.ts","../src/instrumentations/http/http.ts","../src/instrumentations/undici/types.ts","../src/instrumentations/undici/pingops-undici.ts","../src/instrumentations/undici/undici.ts"],"sourcesContent":[],"mappings":"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"}