@pingops/sdk 0.1.3 → 0.2.1

package/README.md

@@ -1,6 +1,36 @@
 # @pingops/sdk
 
-PingOps SDK for Node.js. Provides a simple API for bootstrapping OpenTelemetry and capturing outgoing API and LLM calls.
+**PingOps SDK for Node.js** — Bootstrap OpenTelemetry and capture outgoing HTTP and fetch API calls with minimal code. Built for observability of external API usage, AI/LLM calls, and third-party integrations.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [Tracing](#tracing)
+- [Filtering & Privacy](#filtering--privacy)
+- [Integration with Existing OpenTelemetry](#integration-with-existing-opentelemetry)
+- [What Gets Captured](#what-gets-captured)
+- [Requirements](#requirements)
+
+---
+
+## Overview
+
+The PingOps SDK gives you:
+
+- **Automatic instrumentation** — Outgoing HTTP (Node.js `http` module) and `fetch` (via Undici) are instrumented without wrapping your code.
+- **Structured traces** — Start traces with `userId`, `sessionId`, tags, and metadata so every span is tied to your business context.
+- **Control over what is captured** — Domain allow/deny lists, header filtering, and optional request/response body capture with size limits.
+- **Flexible setup** — Use environment variables, a config file (JSON or YAML), or pass config programmatically. Auto-initialize via `--require` or import `@pingops/sdk/register` first.
+
+You initialize once (at process startup or before any HTTP clients load); after that, outgoing requests are captured and sent to your PingOps backend in batches or immediately.
+
+---
 
 ## Installation
 
@@ -8,17 +38,29 @@ PingOps SDK for Node.js. Provides a simple API for bootstrapping OpenTelemetry a
 pnpm add @pingops/sdk
 ```
 
+Or with npm:
+
+```bash
+npm install @pingops/sdk
+```
+
+**Requirement:** Node.js **20 or later** (for native `fetch` and modern APIs).
+
+---
+
 ## Quick Start
 
-### Option 1: Auto-initialization (Recommended)
+### Option 1: Auto-initialization (recommended)
+
+**Best for:** Getting started quickly and for production when config comes from environment or a config file.
 
-**Most automatic approach** - Use Node.js `--require` flag (runs before any imports):
+**A. Using Node.js `--require`** (runs before any application code):
 
 ```bash
 node --require @pingops/sdk/register your-app.js
 ```
 
-Set environment variables:
+Set required environment variables:
 
 ```bash
 export PINGOPS_API_KEY="your-api-key"
@@ -26,168 +68,409 @@ export PINGOPS_BASE_URL="https://api.pingops.com"
 export PINGOPS_SERVICE_NAME="my-service"
 ```
 
-**Or** import the register file FIRST in your code:
+**B. Importing the register entry first** (must be before any HTTP client imports):
 
 ```typescript
-// Import this FIRST, before any HTTP clients
+// Must be first — before axios, node-fetch, or any code that makes HTTP requests
 import "@pingops/sdk/register";
 
 import axios from "axios";
-// ... rest of your code
+// ... rest of your application
 ```
 
+With a config file, set `PINGOPS_CONFIG_FILE` to the path to your JSON or YAML file; environment variables override values from the file.
+
 ### Option 2: Manual initialization
 
+**Best for:** Config from code, feature flags, or when you need to ensure initialization order explicitly.
+
 ```typescript
 import { initializePingops } from "@pingops/sdk";
 
-// Option A: pass a config object directly
+// Before importing or using any HTTP clients
 initializePingops({
-  apiKey: "your-api-key", // or set PINGOPS_API_KEY env var
+  apiKey: process.env.PINGOPS_API_KEY,
   baseUrl: "https://api.pingops.com",
   serviceName: "my-service",
 });
 
-// Option B: pass a JSON/YAML config file path (env vars override file values)
+import axios from "axios";
+// ... rest of your application
+```
+
+You can also initialize from a config file path (environment variables still override file values):
+
+```typescript
 initializePingops("./pingops.config.yaml");
-// or:
+// or
 initializePingops({ configFile: "./pingops.config.json" });
 ```
 
-**Important**: If using manual initialization, call `initializePingops()` before importing any HTTP clients (axios, fetch, etc.) to ensure proper instrumentation.
+**Important:** Call `initializePingops` before any HTTP client is loaded or used so instrumentation is applied correctly.
+
+---
+
+## Configuration
+
+Configuration can be provided via:
+
+1. **Programmatic config** — Object passed to `initializePingops(...)`
+2. **Config file** — Path as first argument or `{ configFile: "path" }`; supports JSON and YAML
+3. **Environment variables** — Always override file and can supply all required fields for auto-init
+
+### Required fields
+
+| Field         | Env var                | Description               |
+| ------------- | ---------------------- | ------------------------- |
+| `baseUrl`     | `PINGOPS_BASE_URL`     | PingOps backend base URL  |
+| `serviceName` | `PINGOPS_SERVICE_NAME` | Service name for resource |
+
+`apiKey` is optional at config level; if your backend requires it, set `apiKey` or `PINGOPS_API_KEY`.
+
+### Full configuration reference
+
+| Option                | Type                         | Default      | Description                                    |
+| --------------------- | ---------------------------- | ------------ | ---------------------------------------------- |
+| `apiKey`              | `string`                     | —            | API key (or `PINGOPS_API_KEY`)                 |
+| `baseUrl`             | `string`                     | **required** | Backend base URL                               |
+| `serviceName`         | `string`                     | **required** | Service name                                   |
+| `debug`               | `boolean`                    | `false`      | Enable debug logs (`PINGOPS_DEBUG=true`)       |
+| `headersAllowList`    | `string[]`                   | —            | Headers to include (case-insensitive)          |
+| `headersDenyList`     | `string[]`                   | —            | Headers to exclude (overrides allow)           |
+| `captureRequestBody`  | `boolean`                    | `false`      | Capture request bodies (global)                |
+| `captureResponseBody` | `boolean`                    | `false`      | Capture response bodies (global)               |
+| `maxRequestBodySize`  | `number`                     | `4096`       | Max request body size in bytes                 |
+| `maxResponseBodySize` | `number`                     | `4096`       | Max response body size in bytes                |
+| `domainAllowList`     | `DomainRule[]`               | —            | Domains (and optional rules) to allow          |
+| `domainDenyList`      | `DomainRule[]`               | —            | Domains to exclude                             |
+| `headerRedaction`     | `HeaderRedactionConfig`      | —            | Custom header redaction                        |
+| `batchSize`           | `number`                     | `50`         | Spans per batch (`PINGOPS_BATCH_SIZE`)         |
+| `batchTimeout`        | `number`                     | `5000`       | Flush interval in ms (`PINGOPS_BATCH_TIMEOUT`) |
+| `exportMode`          | `"batched"` \| `"immediate"` | `"batched"`  | `PINGOPS_EXPORT_MODE`                          |
+
+**Config file path:** Set `PINGOPS_CONFIG_FILE` to the path of your JSON or YAML file when using the register entry.
+
+**Export mode:**
+
+- **`batched`** — Best for long-running processes; spans are sent in batches (default).
+- **`immediate`** — Best for serverless/short-lived processes; each span is sent as it finishes to reduce loss on freeze/exit.
+
+### Config file examples
+
+**JSON (`pingops.config.json`):**
+
+```json
+{
+  "apiKey": "your-api-key",
+  "baseUrl": "https://api.pingops.com",
+  "serviceName": "my-service",
+  "debug": false,
+  "exportMode": "batched",
+  "batchSize": 50,
+  "batchTimeout": 5000,
+  "captureRequestBody": false,
+  "captureResponseBody": false
+}
+```
+
+**YAML (`pingops.config.yaml`):**
 
-## Features
+```yaml
+apiKey: your-api-key
+baseUrl: https://api.pingops.com
+serviceName: my-service
+debug: false
+exportMode: batched
+batchSize: 50
+batchTimeout: 5000
+```
 
-- **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
+## API Reference
 
 ### `initializePingops(config)`
 
-Initializes the PingOps SDK with OpenTelemetry.
+Initializes the PingOps SDK: sets up OpenTelemetry `NodeSDK`, registers the PingOps span processor, and enables HTTP and Undici (fetch) instrumentation.
+
+**Overloads:**
+
+- `initializePingops(config: PingopsProcessorConfig): void`
+- `initializePingops(configFilePath: string): void`
+- `initializePingops({ configFile: string }): void`
 
-**Configuration:**
+**Example:**
 
 ```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
-}
+import { initializePingops } from "@pingops/sdk";
+
+initializePingops({
+  baseUrl: "https://api.pingops.com",
+  serviceName: "my-service",
+  apiKey: process.env.PINGOPS_API_KEY,
+  exportMode: "immediate", // e.g. for serverless
+});
 ```
 
-### `pingops.startSpan(name, attributes, fn)`
+Calling `initializePingops` again after the first successful call is a no-op (idempotent).
+
+---
 
-Creates a manual span for custom instrumentation.
+### `shutdownPingops()`
+
+Gracefully shuts down the SDK and flushes remaining spans. Returns a `Promise<void>`.
+
+**Example:**
 
 ```typescript
-import { pingops } from "@pingops/sdk";
+import { shutdownPingops } from "@pingops/sdk";
+
+process.on("SIGTERM", async () => {
+  await shutdownPingops();
+  process.exit(0);
+});
+```
+
+---
+
+### `startTrace(options, fn)`
+
+Starts a new trace, sets PingOps attributes (e.g. `userId`, `sessionId`, tags, metadata) in context, runs the given function inside that context, and returns the function’s result. Any spans created inside the function (including automatic HTTP/fetch spans) are part of this trace and carry the same context.
+
+**Parameters:**
+
+- `options.attributes` — Optional [PingopsTraceAttributes](#pingopstraceattributes) to attach to the trace and propagate to spans.
+- `options.seed` — Optional string; when provided, a deterministic trace ID is derived from it (useful for idempotency or correlation with external systems).
+- `fn` — `() => T | Promise<T>`. Your code; runs inside the new trace and attribute context.
 
-await pingops.startSpan(
-  "external.api.call",
+**Returns:** `Promise<T>` — The result of `fn`.
+
+**Example:**
+
+```typescript
+import { startTrace, initializePingops } from "@pingops/sdk";
+
+initializePingops({ baseUrl: "...", serviceName: "my-api" });
+
+const data = await startTrace(
   {
-    customer_id: "cust_123",
-    correlation_id: "req_456",
-    "custom_attributes.request_type": "webhook",
+    attributes: {
+      userId: "user-123",
+      sessionId: "sess-456",
+      tags: ["checkout", "v2"],
+      metadata: { plan: "pro", region: "us" },
+      captureRequestBody: true,
+      captureResponseBody: true,
+    },
+    seed: "order-789", // optional: stable trace ID for this order
   },
-  async (span) => {
-    // Your code here
-    const result = await fetch("https://api.example.com/data");
-    return result.json();
+  async () => {
+    const res = await fetch("https://api.stripe.com/v1/charges", { ... });
+    return res.json();
   }
 );
 ```
 
-The span is automatically ended when the function completes or throws an error.
+---
 
-### `shutdownPingops()`
+### `getActiveTraceId()`
+
+Returns the trace ID of the currently active span, or `undefined` if there is none.
 
-Gracefully shuts down the SDK and flushes remaining spans.
+**Example:**
 
 ```typescript
-import { shutdownPingops } from "@pingops/sdk";
+import { getActiveTraceId } from "@pingops/sdk";
 
-await shutdownPingops();
+const traceId = getActiveTraceId();
+console.log("Current trace:", traceId);
 ```
 
-## Domain Filtering
+---
+
+### `getActiveSpanId()`
 
-Control which domains and paths are captured:
+Returns the span ID of the currently active span, or `undefined` if there is none.
+
+**Example:**
 
 ```typescript
-initializePingops({
-  // ... other config
-  domainAllowList: [
-    {
-      domain: "api.github.com",
-      paths: ["/repos"],
-      headersAllowList: ["authorization", "user-agent"],
-    },
+import { getActiveSpanId } from "@pingops/sdk";
+
+const spanId = getActiveSpanId();
+```
+
+---
+
+### `PingopsTraceAttributes`
+
+Type for attributes you can pass into `startTrace({ attributes })`:
+
+| Field                 | Type                     | Description                                                           |
+| --------------------- | ------------------------ | --------------------------------------------------------------------- |
+| `traceId`             | `string`                 | Override trace ID (otherwise one is generated or derived from `seed`) |
+| `userId`              | `string`                 | User identifier                                                       |
+| `sessionId`           | `string`                 | Session identifier                                                    |
+| `tags`                | `string[]`               | Tags for the trace                                                    |
+| `metadata`            | `Record<string, string>` | Key-value metadata                                                    |
+| `captureRequestBody`  | `boolean`                | Override request body capture for spans in this trace                 |
+| `captureResponseBody` | `boolean`                | Override response body capture for spans in this trace                |
+
+---
+
+## Tracing
+
+### Why use `startTrace`?
+
+- **Correlation** — Tie all outgoing calls in a request (or job) to one trace and to a user/session.
+- **Stable IDs** — Use `seed` (e.g. request ID or order ID) to get a deterministic trace ID for logging or external systems.
+- **Scoped body capture** — Enable `captureRequestBody` / `captureResponseBody` only for specific traces (e.g. a single webhook or LLM call) instead of globally.
+
+### Auto-initialization when using `startTrace`
+
+If you call `startTrace` before calling `initializePingops`, the SDK will try to auto-initialize from environment variables (`PINGOPS_API_KEY`, `PINGOPS_BASE_URL`, `PINGOPS_SERVICE_NAME`). If any of these are missing, `startTrace` throws. For predictable behavior, prefer initializing explicitly at startup.
+
+### Example: request-scoped trace
+
+```typescript
+import { startTrace, getActiveTraceId, initializePingops } from "@pingops/sdk";
+
+initializePingops({ baseUrl: "...", serviceName: "my-api" });
+
+app.post("/webhook", async (req, res) => {
+  const result = await startTrace(
     {
-      domain: ".openai.com", // Suffix match
+      attributes: {
+        userId: req.user?.id,
+        sessionId: req.sessionId,
+        tags: ["webhook"],
+        metadata: { provider: req.body.provider },
+      },
+      seed: req.headers["x-request-id"] ?? undefined,
     },
-  ],
-  domainDenyList: [
+    async () => {
+      await callExternalApi(req.body);
+      return { ok: true };
+    }
+  );
+
+  const traceId = getActiveTraceId();
+  res.setHeader("X-Trace-Id", traceId ?? "");
+  res.json(result);
+});
+```
+
+---
+
+## Filtering & Privacy
+
+### Domain allow/deny lists
+
+Restrict which domains (and optionally paths) are captured:
+
+```typescript
+initializePingops({
+  baseUrl: "https://api.pingops.com",
+  serviceName: "my-service",
+  domainAllowList: [
+    { domain: "api.github.com", paths: ["/repos"] },
+    { domain: ".openai.com" }, // suffix match
     {
-      domain: "internal.service.local",
+      domain: "generativelanguage.googleapis.com",
+      captureRequestBody: true,
+      captureResponseBody: true,
     },
   ],
+  domainDenyList: [{ domain: "internal.corp.local" }],
 });
 ```
 
-## Header Filtering
+Each rule in `domainAllowList` / `domainDenyList` can include:
+
+- `domain` — Exact or suffix (e.g. `.openai.com`) match.
+- `paths` — Optional path prefixes to allow/deny.
+- `headersAllowList` / `headersDenyList` — Header rules for that domain.
+- `captureRequestBody` / `captureResponseBody` — Override body capture for that domain.
 
-Control which headers are captured:
+### Header allow/deny lists
+
+Control which headers are included on captured spans (global default; domain rules can refine):
 
 ```typescript
 initializePingops({
-  // ... other config
-  headersAllowList: ["user-agent", "x-request-id"],
-  headersDenyList: ["authorization", "cookie"],
+  baseUrl: "https://api.pingops.com",
+  serviceName: "my-service",
+  headersAllowList: ["user-agent", "x-request-id", "content-type"],
+  headersDenyList: ["authorization", "cookie", "x-api-key"],
 });
 ```
 
+Deny list takes precedence over allow list. Sensitive headers are redacted by default; use `headerRedaction` in config for custom behavior.
+
+### Request/response body capture
+
+- **Global:** `captureRequestBody` and `captureResponseBody` in config.
+- **Per-domain:** Same flags on a [DomainRule](#domain-allowdeny-lists).
+- **Per-trace:** `captureRequestBody` / `captureResponseBody` in [PingopsTraceAttributes](#pingopstraceattributes) in `startTrace`.
+
+Body size is capped by `maxRequestBodySize` and `maxResponseBodySize` (default 4096 bytes each). Larger bodies are truncated.
+
+---
+
 ## Integration with Existing OpenTelemetry
 
-If you already have OpenTelemetry set up, you can use just the `PingopsSpanProcessor`:
+If you already use OpenTelemetry and only want the PingOps exporter and filtering, use `PingopsSpanProcessor` from `@pingops/otel` and add it to your existing `TracerProvider`:
 
 ```typescript
+import { NodeSDK } from "@opentelemetry/sdk-node";
 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 sdk = new NodeSDK({
+  spanProcessors: [
+    new PingopsSpanProcessor({
+      apiKey: "your-api-key",
+      baseUrl: "https://api.pingops.com",
+      serviceName: "my-service",
+      exportMode: "batched",
+      domainAllowList: [{ domain: "api.example.com" }],
+    }),
+  ],
+  // your existing instrumentations, resource, etc.
 });
 
-const tracerProvider = getTracerProvider();
-// Add processor to your existing tracer provider
+sdk.start();
 ```
 
+You can still use `@pingops/sdk` for `startTrace`, `getActiveTraceId`, and `getActiveSpanId`; ensure your tracer provider is the one that uses `PingopsSpanProcessor` (or is bridged to it) so those spans are exported to PingOps.
+
+---
+
 ## 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
+- **Outgoing HTTP** — Requests made with Node’s `http` / `https` (e.g. many HTTP clients under the hood).
+- **Outgoing fetch** — Requests made with the global `fetch` (in Node.js 18+ this is implemented by Undici; both are instrumented).
 
-## What Doesn't Get Captured
+Only **CLIENT** spans with HTTP (or supported semantic) attributes are exported to PingOps; server-side and internal spans are filtered out.
 
-- 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
+- **Node.js** ≥ **20**
+- **ESM** — The package is published as ES modules; use `import` and, if needed, `"type": "module"` or `.mjs`.
+
+---
+
+## Summary
+
+| Goal               | What to do                                                                                      |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| Install            | `pnpm add @pingops/sdk`                                                                         |
+| Auto-init from env | `node --require @pingops/sdk/register your-app.js` or `import "@pingops/sdk/register"` first    |
+| Manual init        | `initializePingops({ baseUrl, serviceName, ... })` before any HTTP usage                        |
+| Config from file   | `PINGOPS_CONFIG_FILE=./pingops.config.yaml` or `initializePingops("./pingops.config.json")`     |
+| Trace with context | `startTrace({ attributes: { userId, sessionId, tags, metadata }, seed? }, async () => { ... })` |
+| Get current IDs    | `getActiveTraceId()`, `getActiveSpanId()`                                                       |
+| Graceful shutdown  | `await shutdownPingops()`                                                                       |
+
+For more detail on types and options, see the [Configuration](#configuration) and [API Reference](#api-reference) sections above.

package/dist/index.cjs

@@ -1,5 +1,7 @@
-const require_pingops = require('./pingops-Cb6UV5D8.cjs');
+const require_pingops = require('./pingops-BBXegVtL.cjs');
 
+exports.getActiveSpanId = require_pingops.getActiveSpanId;
+exports.getActiveTraceId = require_pingops.getActiveTraceId;
 exports.initializePingops = require_pingops.initializePingops;
 exports.shutdownPingops = require_pingops.shutdownPingops;
-exports.wrapHttp = require_pingops.wrapHttp;
+exports.startTrace = require_pingops.startTrace;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { PingopsProcessorConfig } from "@pingops/otel";
-import { WrapHttpAttributes, WrapHttpAttributes as WrapHttpAttributes$1 } from "@pingops/core";
+import { PingopsTraceAttributes, PingopsTraceAttributes as PingopsTraceAttributes$1 } from "@pingops/core";
 
 //#region src/pingops.d.ts
 
@@ -15,7 +15,7 @@ import { WrapHttpAttributes, WrapHttpAttributes as WrapHttpAttributes$1 } from "
  *
  * @param config - Configuration object, config file path, or config file wrapper
  * @param explicit - Whether this is an explicit call (default: true).
- *                   Set to false when called internally by wrapHttp auto-initialization.
+ *                   Set to false when called internally by startTrace auto-initialization.
  */
 declare function initializePingops(config: PingopsProcessorConfig, explicit?: boolean): void;
 declare function initializePingops(configFilePath: string, explicit?: boolean): void;
@@ -27,61 +27,46 @@ declare function initializePingops(config: {
  */
 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.
+ * Returns the trace ID of the currently active span, if any.
+ */
+declare function getActiveTraceId(): string | undefined;
+/**
+ * Returns the span ID of the currently active span, if any.
+ */
+declare function getActiveSpanId(): string | undefined;
+/**
+ * Starts a new trace using the PingOps tracer provider and runs the callback within that trace.
+ * Sets attributes (traceId, userId, sessionId, tags, metadata, etc.) in context so they are
+ * propagated to spans created within the callback.
  *
- * @param options - Options including attributes to propagate to spans
- * @param fn - Function to execute within the attribute context
- * @returns The result of the function
+ * @param options - Options including optional attributes and optional seed for deterministic traceId
+ * @param fn - Function to execute within the trace and attribute context
+ * @returns Promise resolving to the result of the function
  *
  * @example
  * ```typescript
- * import { wrapHttp } from '@pingops/sdk';
+ * import { startTrace, initializePingops } from '@pingops/sdk';
  *
- * // Scenario 1: initializePingops was called
  * initializePingops({ ... });
  *
- * // All HTTP requests are instrumented, but this block adds attributes
- * const result = await wrapHttp({
+ * const result = await startTrace({
  *   attributes: {
  *     userId: 'user-123',
  *     sessionId: 'session-456',
  *     tags: ['production', 'api'],
  *     metadata: { environment: 'prod', version: '1.0.0' }
- *   }
+ *   },
+ *   seed: 'request-123' // optional: deterministic traceId from this seed
  * }, 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');
  * ```
  */
-declare function wrapHttp<T>(options: {
-  attributes?: WrapHttpAttributes$1;
-}, fn: () => T | Promise<T>): T | Promise<T>;
+declare function startTrace<T>(options: {
+  attributes?: PingopsTraceAttributes$1;
+  seed?: string;
+}, fn: () => T | Promise<T>): Promise<T>;
 //#endregion
-export { type WrapHttpAttributes, initializePingops, shutdownPingops, wrapHttp };
+export { type PingopsTraceAttributes, getActiveSpanId, getActiveTraceId, initializePingops, shutdownPingops, startTrace };
 //# sourceMappingURL=index.d.cts.map