@launchdarkly/o11y 1.4.1 → 1.6.0

package/dist/index.d.ts

@@ -623,6 +623,7 @@ declare class Highlight_2 {
     _isCrossOriginIframe: boolean;
     _eventBytesSinceSnapshot: number;
     _lastSnapshotTime: number;
+    _snapshotPayloadIds: Set<number>;
     _lastVisibilityChangeTime: number;
     pushPayloadTimerId: ReturnType<typeof setTimeout> | undefined;
     hasSessionUnloaded: boolean;
@@ -1160,6 +1161,19 @@ declare type Hook = Omit<Hook_2, 'afterEvaluation'> & {
  */
 declare type HrTime = [number, number];
 
+/**
+ * Describes the request behind an auto-instrumented browser `fetch` or
+ * `XMLHttpRequest` span.
+ */
+export declare type HttpSpanRequest = {
+    /** Which instrumentation created the span. */
+    type: 'fetch' | 'xhr';
+    /** Upper-cased HTTP method, e.g. `GET`. */
+    method: string;
+    /** The concrete request URL, e.g. `https://app.example.com/api/users/42`. */
+    url: string;
+};
+
 declare type IdentifyMessage = {
     type: MessageType.Identify;
     userIdentifier: string;
@@ -1240,6 +1254,14 @@ declare interface LDClientMin {
 export declare let LDObserve: _LDObserve;
 
 declare class _LDObserve extends BufferedClass<Observe_2> implements Observe_2 {
+    /**
+     * Applies buffered `setAttributes`/`removeAttributes` calls to `sdk`
+     * without attaching it. Call it before `sdk.start()` so attributes set
+     * before init reach spans recorded synchronously during start (e.g. the
+     * document load span). `load` also does this, so calling it is optional.
+     */
+    applyBufferedAttributes(sdk: Observe_2): void;
+    load(sdk: Observe_2, options?: BufferedLoadOptions): void;
     protected _startSdk(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -1257,6 +1279,8 @@ declare class _LDObserve extends BufferedClass<Observe_2> implements Observe_2 {
         [key: string]: string;
     }, source?: string, type?: ErrorMessageType): any;
     setLDContextKeyAttributes(contextKeys: Attributes): any;
+    setAttributes(attributes: Record<string, AttributeValue | null | undefined>): any;
+    removeAttributes(keys: string[]): any;
     getLDContextKeyAttributes(): Attributes | undefined;
 }
 
@@ -1756,6 +1780,40 @@ declare interface Observe_2 {
      * Useful when you don't want to emit a console log to the browser dev tools but still want to report a custom log.
      */
     recordLog: (message: any, level: ConsoleMethods, metadata?: Attributes) => void;
+    /**
+     * Adds attributes to all telemetry recorded from now on: every span
+     * (including automatically instrumented ones such as document load,
+     * fetch/XHR, clicks and page views), log, error and metric.
+     *
+     * Calling it again merges with the attributes already set; a `null` or
+     * `undefined` value removes that key. Attributes passed to an individual
+     * call (for example `recordLog` metadata or metric attributes) take
+     * precedence over these. Keys in namespaces the SDK sets itself
+     * (`highlight.*`, `launchdarkly.*`, `session.*`, `context.contextKeys.*`)
+     * are ignored.
+     *
+     * Attributes are held in memory for the current page load only: they are
+     * never persisted, and a full page load starts without them.
+     *
+     * Each attribute is also added to every metric, so a value with many
+     * distinct values (such as a user ID) creates as many metric series.
+     *
+     * @example
+     * ```typescript
+     * LDObserve.setAttributes({ utm_campaign: 'spring_promo', utm_source: 'email' })
+     * ```
+     */
+    setAttributes(attributes: Record<string, AttributeValue | null | undefined>): void;
+    /**
+     * Removes attributes previously added with `setAttributes`. Telemetry
+     * recorded afterwards no longer carries them.
+     *
+     * @example
+     * ```typescript
+     * LDObserve.removeAttributes(['utm_campaign'])
+     * ```
+     */
+    removeAttributes(keys: string[]): void;
     register(client: LDClientMin, environmentMetadata: LDPluginEnvironmentMetadata): void;
     getHooks?(metadata: LDPluginEnvironmentMetadata): Hook[];
     setLDContextKeyAttributes(contextKeys: Attributes): void;
@@ -1867,6 +1925,55 @@ export declare type ObserveOptions = CommonOptions & {
      * @default 2000
      */
     flagExposureDedupeMaxSize?: number;
+    /**
+     * Query parameters to read from the page URL and add as attributes to all
+     * telemetry, as if passed to `LDObserve.setAttributes`.
+     *
+     * When the SDK initializes, each listed parameter present in
+     * `location.search` becomes an attribute named after the parameter (e.g.
+     * `utm_campaign`) on every span (including document load, page view and
+     * fetch/XHR spans), log, error and metric for the rest of the page load,
+     * including after SPA navigation drops it from the URL.
+     *
+     * Last touch: when an SPA navigation lands on a URL with any listed
+     * parameter, the captured values are replaced by that URL's values, and
+     * previously captured keys missing from it are removed, so the set always
+     * reflects one landing. A navigation without listed parameters keeps the
+     * current values. Spans already started keep the values they had.
+     *
+     * Values are kept in memory only; nothing is written to storage or
+     * cookies, so a later full page load captures again from its own URL.
+     *
+     * Only the listed keys are captured, so other query parameters (which may
+     * hold personal data such as emails or tokens) are never recorded this
+     * way. The default list contains UTM parameters only. A name ending in `*`
+     * matches every parameter with that prefix (e.g. `'utm_*'`).
+     *
+     * Keys set with `setAttributes` win: capture never replaces or removes a
+     * key the app set itself. `removeAttributes` removes a captured value
+     * (a later landing with that parameter captures it again). Keys in the
+     * namespaces the SDK sets itself (`highlight.*`, `launchdarkly.*`,
+     * `session.*`, `context.contextKeys.*`) are ignored.
+     *
+     * A custom list replaces the default. Set to `false` or `[]` to turn
+     * capture off.
+     * @default ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content']
+     * @example captureQueryParams: ['utm_source', 'utm_campaign', 'gclid']
+     */
+    captureQueryParams?: string[] | false;
+    /**
+     * Specifies whether to record the page that linked to this one. When the
+     * SDK initializes and `document.referrer` is a different origin, it is
+     * added as the `landing.referrer` attribute to all telemetry for the rest
+     * of the page load, as if passed to `LDObserve.setAttributes`.
+     *
+     * Only the origin and path are kept: the query string, fragment and any
+     * credentials are stripped so tokens or personal data in the referrer URL
+     * are not recorded. An empty or same-origin referrer sets nothing, and
+     * the value is not updated on SPA navigation.
+     * @default true
+     */
+    captureReferrer?: boolean;
 };
 
 declare interface OnHighlightReadyOptions {
@@ -1893,6 +2000,32 @@ declare interface OTelMetric {
 
 declare type OtelOptions = {
     instrumentations?: OtelInstrumentatonOptions;
+    /**
+     * Called for each auto-instrumented `fetch` and `XMLHttpRequest` span just
+     * before it ends, so the response and error status are already on it.
+     * Use it to rename the span or add attributes, for example to give it a
+     * route template:
+     *
+     * ```ts
+     * onHttpRequestSpan: (span, { method, url }) => {
+     *   const route = matchRoute(url) // '/api/users/{userId}'
+     *   if (!route) return
+     *   span.updateName(`${method} ${route}`)
+     *   span.setAttributes({
+     *     'http.route': route,
+     *     'url.template': route,
+     *     'launchdarkly.operation.name': route,
+     *   })
+     * }
+     * ```
+     *
+     * The span's trace and span ids are fixed when the request starts, so
+     * renaming does not affect the `traceparent` sent to your backend.
+     * Errors thrown by the callback are swallowed. Requires
+     * `networkRecording` to be enabled, as the instrumentations are not
+     * installed otherwise.
+     */
+    onHttpRequestSpan?: (span: Span, request: HttpSpanRequest) => void;
 };
 
 declare class Plugin_2<T extends RecordOptions | ObserveOptions> {
@@ -2196,6 +2329,7 @@ declare class RecordSDK implements Record_3 {
     _isCrossOriginIframe: boolean;
     _eventBytesSinceSnapshot: number;
     _lastSnapshotTime: number;
+    _snapshotPayloadIds: Set<number>;
     _lastVisibilityChangeTime: number;
     pushPayloadTimerId: ReturnType<typeof setTimeout> | undefined;
     hasSessionUnloaded: boolean;