@interopio/otel 0.1.14 → 0.1.15

package/insights.d.ts

@@ -146,7 +146,7 @@ export namespace IOInsights {
      *
      * Otherwise, if settings exist for a metric with this name, either provided
      * by the platform or by configuration, a metric will be created.
-     * 
+     *
      * Otherwise, returns undefined.
      *
      * Subsequent calls to this method with the same name return the same metric.
@@ -158,11 +158,11 @@ export namespace IOInsights {
      * Creates or retrieves a metric based on the provided settings.
      *
      * If a metric is already created with this name, it will be returned.
-     * 
+     *
      * Otherwise, if settings exist for a metric with this name, either provided
      * by the platform or by configuration, they will be merged with the
      * settings provided to this method before creating it.
-     * 
+     *
      * Otherwise, the settings provided will be used as is.
      *
      * Subsequent calls to this method with the same name return the same metric.
@@ -170,6 +170,57 @@ export namespace IOInsights {
      * @param settings settings to use when creating the metric
      */
     getFromSettings(settings: MetricSettings): Metric | undefined;
+
+    /**
+     * Creates or retrieves an observable metric by name.
+     *
+     * If a metric is already created with this name, it will be returned.
+     *
+     * Otherwise, if settings exist for a metric with this name, either provided
+     * by the platform or by configuration, a metric will be created.
+     *
+     * Otherwise, returns undefined.
+     *
+     * Subsequent calls to this method with the same name return the same metric.
+     *
+     * @param name the name of the metric, e.g. platform_startup
+     * @param observeCallback callback that provides the observable metric's value, invoked once per publishInterval
+     * @param subscribeCallback optional callback invoked when the metric is started, can be used to 
+     *  set up subscriptions if the metric is measuring event data
+     * @param unsubscribeCallback optional callback invoked when the metric is stopped, can be used to
+     *  destroy subscriptions if the metric is measuring event data
+     */
+    getObservable<TData extends Attributes>(
+      name: string,
+      observeCallback: (result: ObservableResult<TData>) => Promise<void>,
+      subscribeCallback?: () => Promise<void>,
+      unsubscribeCallback?: () => Promise<void>): Metric | undefined;
+
+    /**
+     * Creates or retrieves an observable metric based on the provided settings.
+     *
+     * If a metric is already created with this name, it will be returned.
+     *
+     * Otherwise, if settings exist for a metric with this name, either provided
+     * by the platform or by configuration, they will be merged with the
+     * settings provided to this method before creating it.
+     *
+     * Otherwise, the settings provided will be used as is.
+     *
+     * Subsequent calls to this method with the same name return the same metric.
+     *
+     * @param settings settings to use when creating the metric
+     * @param observeCallback callback that provides the observable metric's value, invoked once per publishInterval
+     * @param subscribeCallback optional callback invoked when the metric is started, can be used to 
+     *  set up subscriptions if the metric is measuring event data
+     * @param unsubscribeCallback optional callback invoked when the metric is stopped, can be used to
+     *  destroy subscriptions if the metric is measuring event data
+     */
+    getObservableFromSettings<TData extends Attributes>(
+      settings: IOInsights.MetricSettings,
+      observeCallback: (result: ObservableResult<TData>) => Promise<void>,
+      subscribeCallback?: () => Promise<void>,
+      unsubscribeCallback?: () => Promise<void>): Metric | undefined;
   }
 
   /**
@@ -379,7 +430,7 @@ export namespace IOInsights {
    * Settings describing a metric.
    */
   export interface MetricSettings {
-    enabled: boolean;
+    enabled?: boolean;
     type: MetricType;
     name?: string;
     description?: string;
@@ -1233,7 +1284,7 @@ export namespace IOInsights {
     /**
      * If `true`, io.Insights will instrument and trace the application startup process
      * automatically.
-     * 
+     *
      * @default true
      */
     instrumentAppStartup?: boolean;
@@ -1241,7 +1292,7 @@ export namespace IOInsights {
     /**
      * If `true`, io.Insights will instrument and trace the application loading process
      * automatically.
-     * 
+     *
      * @default true
      * @deprecated use instrumentAppStartup
      */
@@ -1842,11 +1893,29 @@ export namespace IOInsights {
     /**
      * If `true`, io.Insights will try to nest spans from other event listeners for the same event under
      * the Clickstream span. This is not guaranteed to always work due to specifics of how browsers execute
-     * event listeners, and will only work for listeners attached after io.Connect was initialized.
+     * event listeners, and will only work for listeners attached after io.Connect was initialized -
+     * unless `nestEventHandlersEagerly` is also enabled.
      *
      * @default true
      */
     nestEventListeners?: boolean;
+    /**
+     * If `true`, the io.Insights pre-init module (early.js, loaded from a preload script or an
+     * inline snippet before the application code) eagerly patches addEventListener at page start,
+     * so that listeners registered before io.Connect initialized also participate in
+     * `nestEventListeners` nesting. Without it, only listeners attached after initialization
+     * can be nested - and a listener that missed wrapping at registration stays unwrapped for
+     * every later dispatch.
+     *
+     * The flag is read by the pre-init module itself from the platform-provided configuration
+     * at `window.glue42gd.insights` (which mirrors this configuration object), so it has no
+     * effect when the pre-init module is not installed or when running outside io.Connect
+     * Desktop. The eager wrappers are inert pass-throughs until the SDK initializes, and remain
+     * inert if the SDK loads with clickstream or `nestEventListeners` disabled.
+     *
+     * @default false
+     */
+    nestEventHandlersEagerly?: boolean;
   }
 
   export interface RequestTraceConfig {
@@ -2390,16 +2459,22 @@ export namespace IOInsights {
 
     /**
      * Internal library property.
+     *
+     * @ignore
      */
     definitiveInstance?: boolean;
 
     /**
      * Internal library property.
+     *
+     * @ignore
      */
     platformInstance?: boolean;
     
     /**
      * Internal library property.
+     *
+     * @ignore
      */
     registerControlMethods?: boolean;
 

package/package.json

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