@interopio/otel 0.1.8 → 0.1.11

package/insights.d.ts

@@ -256,11 +256,15 @@ export namespace IOInsights {
 
     /**
      * Whether to enable automatic collection of platform-level metrics (CPU, memory, etc.).
+     * If `true`, the library will initialize all predefined platform metrics automatically.
+     * If `only-explicit`, it will not initialize them automatically, but will still allow you to
+     * configure your own platform metrics based on the predefined types using the `metrics` config property.
+     * If `false`, any platform metrics will be automatically disabled.
      */
-    platformMetricsEnabled?: boolean;
+    platformMetricsEnabled?: boolean | "only-explicit";
 
     /**
-     * Array of individual metric configurations to collect.
+     * Array of custom metric configurations. It allows specifying overrides for both platform and custom metrics.
      */
     metrics?: MetricSettings[];
 
@@ -1127,6 +1131,7 @@ export namespace IOInsights {
     endSpan(endTime?: Date, allowDoubleEnd?: boolean): Promise<void>;
     context?: Context;
     span?: Span;
+    matchingFilter?: SpanFilter | null;
     /**
      * Gets the propagation info for the current span (see https://www.w3.org/TR/trace-context/#tracestate-field)
      * @returns the propagation info, if a span is currently active
@@ -1189,13 +1194,56 @@ export namespace IOInsights {
      * 
      * @default true
      */
-    instrumentRequests?: boolean;
+    instrumentRequests?: boolean | RequestTraceConfig;
+
+    // https://github.com/open-telemetry/opentelemetry-browser/blob/main/packages/instrumentation/README.md#fetch
+    /**
+     * If `true`, uncaught errors and unhandled promise rejections are published as
+     * error spans ("interopio.api.instrumentation.error" / ".unhandledRejection"),
+     * including errors buffered before initialization by the pre-init recorder.
+     * Capped per session to guard against error storms. When enabled, the app
+     * startup trace defers its own error capture to this instrumentation.
+     *
+     * @default true
+     */
+    instrumentErrors?: boolean;
+
+    /**
+     * If `true`, resource loads (scripts, stylesheets, images, fonts, ...) are
+     * published as spans ("interopio.api.instrumentation.resource") with their real
+     * timings from the resource timing buffer, including resources loaded before
+     * initialization. fetch/XHR resources are excluded (the request instrumentation
+     * covers them in more detail), as are telemetry uploads. When enabled, the app
+     * startup trace defers its slowest-resource child spans to this instrumentation.
+     *
+     * @default true
+     */
+    instrumentResources?: boolean;
+
+    /**
+     * If `true`, in-page (SPA) navigations - history pushState/replaceState,
+     * popstate and hashchange - are published as spans
+     * ("interopio.api.instrumentation.navigation") with the sanitized from/to URLs.
+     * Same-URL state updates are not reported.
+     *
+     * @default true
+     */
+    instrumentNavigation?: boolean;
+
+    /**
+     * If `true`, io.Insights will instrument and trace the application startup process
+     * automatically.
+     * 
+     * @default true
+     */
+    instrumentAppStartup?: boolean;
 
     /**
      * If `true`, io.Insights will instrument and trace the application loading process
      * automatically.
      * 
      * @default true
+     * @deprecated use instrumentAppStartup
      */
     instrumentAppLoad?: boolean;
 
@@ -1204,6 +1252,7 @@ export namespace IOInsights {
      * and initialization process automatically
      *
      * @default true
+     * @deprecated use instrumentAppStartup
      */
     instrumentDocumentLoad?: boolean;
 
@@ -1505,6 +1554,12 @@ export namespace IOInsights {
   export interface WithSpanOptions extends Omit<SpanCreationOptions, "sample"> {
     defaultFilters?: SpanFilter[];
     structure?: "sibling" | "nested";
+    /**
+     * Overrides the name of the exported OTEL span. The `source` remains the identity
+     * used for span filtering, metrics and logging - this only changes the recorded
+     * span name (e.g. to follow a semantic convention).
+     */
+    spanName?: string;
   }
 
   export interface SpanCreationOptions {
@@ -1658,6 +1713,12 @@ export namespace IOInsights {
      * @default false
      */
     overrideDefaultFilters?: boolean;
+
+    /**
+     * If set, will force the span to have this status code, regardless of anything set explicitly
+     * or any errors caught automatically.
+     */
+    forceStatus?: SpanStatusCode;
   }
 
   /**
@@ -1684,6 +1745,28 @@ export namespace IOInsights {
     context?: {
       [key: string]: string | number | boolean;
     };
+
+    /**
+     * For spans instrumenting HTTP requests, controls automatic injection of the trace
+     * context headers with the current span's context. The headers are produced by the
+     * globally registered propagator (W3C trace context - `traceparent`/`tracestate` -
+     * by default; replaceable via the traces settings' `propagator`, e.g. with B3 or a
+     * composite propagator including baggage).
+     *
+     * `"same-origin"` injects into same-origin requests only: adding a custom header
+     * to a cross-origin request triggers a CORS preflight, and a server that does not
+     * allow the header would fail the request itself. (The legacy value `true` is
+     * treated as `"same-origin"` at runtime.)
+     *
+     * `"all-origins"` injects into every request this filter matches, including
+     * cross-origin ones - use it in filters whose `context.url` matches origins
+     * known to accept the headers (e.g. via Access-Control-Allow-Headers).
+     *
+     * @default false
+     */
+    injectOTELHeaders?: false | "same-origin" | "all-origins";
+
+    [key: string]: any;
   }
 
   /**
@@ -1766,6 +1849,188 @@ export namespace IOInsights {
     nestEventListeners?: boolean;
   }
 
+  export interface RequestTraceConfig {
+    /**
+     * Whether fetch and XHR requests will be instrumented with traces automatically.
+     */
+    enabled: boolean;
+
+    /**
+     * Whether request instrumentation spans can be root spans of new traces. This allows you
+     * to trace requests without any instrumentation in your own code, but may create a large
+     * number of traces. This will not affect metrics.
+     *
+     * @default true
+     */
+    allowRoot?: boolean;
+
+    /**
+     * If `true`, requests to the OTEL Collector endpoints will not be instrumented.
+     * Recommended to keep `true`, since otherwise the request caused by the auto instrumentation
+     * telemetry will itself cause auto instrumentation to kick in and so on, creating unnecessary
+     * telemetry.
+     *
+     * @default true
+     */
+    ignoreTelemetryURLs?: boolean;
+
+    /**
+     * Optional regex pattern for URLs that should be excluded from auto instrumentation.
+     */
+    ignorePattern?: string;
+
+    /**
+     * Optional regex pattern, if specified, only matching URLs will be auto instrumented.
+     */
+    matchPattern?: string;
+
+    /**
+     * An array of HTTP response status codes to consider as errors. Status code families can be described as 4xx, 5xx, etc.
+     *
+     * @default ["4xx", "5xx"]
+     */
+    errorStatusCodes?: (string | number)[];
+
+    /**
+     * If `true` or a string, the request's time to first byte (request issued until the
+     * response headers were received) will be published as a histogram metric. If a string
+     * value is specified, this will be the name of the metric. Otherwise, the default
+     * "io.insights.http.client.request.ttfb.duration" is used.
+     *
+     * Deliberately not named after the semantic convention: samples other instrumentations
+     * publish under "http.client.request.duration" cover the full operation, and mixing
+     * time-to-headers samples into that name would skew cross-tool comparisons - the
+     * semconv name is instead the default of requestTotalDurationMetric.
+     *
+     * Cheap and always available: measured for every request (including failures, until
+     * the failure), with no response body observation required.
+     *
+     * @default false
+     */
+    requestFirstByteDurationMetric?: boolean | string;
+
+    /**
+     * If `true` or a string, the end-to-end request time (request issued until the response
+     * body was fully delivered) will be published as a histogram metric. If a string value
+     * is specified, this will be the name of the metric. Otherwise, the semantic convention
+     * default "http.client.request.duration" is used - the end-to-end measurement matches
+     * what other instrumentations publish under that name.
+     *
+     * Successful requests only. Requests whose body completion cannot be observed (e.g.
+     * streaming responses) contribute no sample, so this metric's sample count is expected
+     * to be lower than requestFirstByteDurationMetric's.
+     *
+     * Cost caveat: when this or requestBodyDownloadDurationMetric is enabled, body delivery of every
+     * non-streaming fetch response is observed by fully reading a clone of the body. As a
+     * side effect, responses the application abandons without reading (e.g. only checking
+     * `response.ok`) are downloaded in full over the network instead of being cancelled by
+     * the browser. Streaming content types (server-sent events etc.) are exempt. Weigh this
+     * before enabling in deployments with large-payload traffic.
+     *
+     * @default false
+     */
+    requestTotalDurationMetric?: boolean | string;
+
+    /**
+     * If `true` or a string, the download phase (response headers received until the response
+     * body was fully delivered) will be published as a histogram metric. If a string value
+     * is specified, this will be the name of the metric. Otherwise, the default
+     * "io.insights.http.client.response.download.duration" is used (no semantic convention
+     * exists for this metric).
+     *
+     * Same population and cost caveats as requestTotalDurationMetric: successful requests with an
+     * observable body completion only, and enabling it causes abandoned fetch response
+     * bodies to be downloaded in full.
+     *
+     * @default false
+     */
+    requestBodyDownloadDurationMetric?: boolean | string;
+
+    /**
+     * Explicit histogram bucket boundaries for requestFirstByteDurationMetric, in seconds, ascending.
+     * The default is the semantic-convention-recommended set for HTTP client durations,
+     * which suits time-to-first-byte distributions well.
+     *
+     * @default [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10]
+     */
+    requestFirstByteDurationMetricBuckets?: number[];
+
+    /**
+     * Explicit histogram bucket boundaries for requestTotalDurationMetric, in seconds, ascending.
+     * The default is the semantic-convention-recommended set (this metric carries the
+     * semconv name by default), extended upward to cover long transfers of large payloads;
+     * overriding the sub-10s boundaries trades away comparability with other
+     * instrumentations that use the recommended set.
+     *
+     * @default [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10, 30, 60, 120, 240]
+     */
+    requestTotalDurationMetricBuckets?: number[];
+
+    /**
+     * Explicit histogram bucket boundaries for requestBodyDownloadDurationMetric, in seconds, ascending.
+     *
+     * @default [0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 240]
+     */
+    requestBodyDownloadDurationMetricBuckets?: number[];
+
+    /**
+     * If `true` or a string, the request size in bytes will be published as a histogram metric.
+     * If a string value is specified, this will be the name of the metric. Otherwise, the
+     * semantic convention default "http.client.request.body.size" is used.
+     *
+     * @default false
+     */
+    requestBytesMetric?: boolean | string;
+
+    /**
+     * If `true` or a string, the request size in bytes will be published as a histogram metric.
+     * If a string value is specified, this will be the name of the metric. Otherwise, the
+     * semantic convention default "http.client.response.body.size" is used.
+     *
+     * @default false
+     */
+    responseBytesMetric?: boolean | string;
+
+    /**
+     * Controls only the naming of the fetch/XHR request spans.
+     *
+     * "semconv" (default) names the spans by the normalized HTTP request method (e.g. "GET"),
+     * per the OTEL semantic conventions for HTTP client spans. "product" keeps the product
+     * span names ("interopio.api.instrumentation.fetch"/".xhr").
+     *
+     * Everything else is the same in both modes: the spans always carry the semconv
+     * attributes (url.full, http.request.method[_original], http.response.status_code,
+     * http.response.header.*, server.address/server.port, http.request.body.size /
+     * http.response.body.size, error.type), span kind CLIENT, and the semconv status
+     * rules. The filtering identity is also unaffected: span filters match these spans
+     * on source "interopio.api.instrumentation.fetch"/".xhr" and on context.url /
+     * context.method.
+     *
+     * @default "semconv"
+     */
+    spanNames?: "semconv" | "product";
+
+    /**
+     * Which measurement responseBytesMetric (and the corresponding span data) reports:
+     *
+     * - "content-length" (default): only the value of the content-length response header
+     *   (the actual transfer size, after content-encoding). Cheap - the body is never read
+     *   for sizing - but responses without the header (e.g. chunked transfer encoding)
+     *   contribute no sample.
+     * - "raw": only bytes counted by fully reading a clone of every fetch response body
+     *   (the size after the browser removed any content-encoding; for XHR the already
+     *   buffered response is measured). Always available, but carries the same cost caveat
+     *   as requestTotalDurationMetric: every non-streaming fetch response body is drained,
+     *   including ones the application abandons.
+     * - "both": prefers content-length and falls back to the raw count when the header is
+     *   absent. Maximizes coverage but mixes the two measurement kinds in one histogram -
+     *   use the sizeKind metric attribute to separate them when querying.
+     *
+     * @default "content-length"
+     */
+    responseBytesMeasurement?: "content-length" | "raw" | "both";
+  }
+
   /**
    * Configuration for User Journey trace behavior.
    * Controls how significant User Journey milestones are tracked throughout the platform session.
@@ -1812,7 +2077,9 @@ export namespace IOInsights {
    */
   export type MarkerSpanCallback = (
     source: string,
-    data?: DataByVerbosity
+    data?: DataByVerbosity,
+    newTrace?: boolean,
+    parentSpan?: PropagationInfo
   ) => Promise<PropagationInfo | null> | void;
 
   /**
@@ -2266,4 +2533,8 @@ export namespace IOInsights {
   export type DataByVerbosity = {
     [level in SpanVerbosity]: any;
   }
+
+  export type TracingMap<T> = {
+    [propertyName in keyof Partial<T>]: ({ source: string; decoratorOptions?: IOInsights.WithSpanDecoratorOptions } | string);
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interopio/otel",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "description": "io.Insights observability library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",