@salesforce/lds-instrumentation 1.100.2

package/dist/main.d.ts

@@ -0,0 +1,81 @@
+import type { Luvio, InMemoryStore, Adapter, CacheMissOutOfTtlEvent, DataOutOfTtlDurationUpdateEvent } from '@luvio/engine';
+import type { Registration as LdsUiapiRegistration } from '@salesforce/lds-adapters-uiapi';
+import type { Registration as LdsNetworkAdapterRegistration } from '@salesforce/lds-network-adapter';
+import type { AdapterReport } from '@salesforce/lds-utils-adapters';
+export * as METRIC_KEYS from './metric-keys';
+export { LRUCache } from './utils/lru-cache';
+interface AdapterMetadata {
+    apiFamily: string;
+    name: string;
+    ttl?: number;
+}
+export declare class Instrumentation {
+    /**
+     * Injected to LDS for Luvio specific instrumentation.
+     *
+     * @param context The transaction context.
+     */
+    instrumentLuvio(_context: unknown): void;
+}
+/**
+ * Provide this method for the instrument option for a Luvio instance.
+ * @param context The transaction context.
+ */
+export declare function instrumentLuvio(context: unknown): void;
+export type ReportObserver = (report: AdapterReport) => void;
+interface AdapterInstrumentationOptions {
+    trackL1Hits: boolean;
+    trackL2Hits: boolean;
+    reportObserver?: ReportObserver;
+}
+export declare function instrumentAdapter<C, D>(adapter: Adapter<C, D>, metadata: AdapterMetadata, adapterInstrumentationOptions?: AdapterInstrumentationOptions): Adapter<C, D>;
+/**
+ * Wraps methods to collect runtime performance using o11y's trackValue API
+ * @param obj Object instance containing the methods to instrument
+ * @param methods array containing objects with keys for the method name and the metric key to use in o11y
+ */
+export declare function instrumentMethods(obj: any, methods: {
+    methodName: string;
+    metricKey: string;
+}[]): void;
+/**
+ * Calls instrumentation/service telemetry counter
+ * @param name Name of the metric
+ * @param value number to increment by, if undefined increment by 1
+ */
+export declare function incrementCounterMetric(name: string, number?: number): void;
+/**
+ * Calls instrumentation/service telemetry percentileHistogram
+ * @param name Name of the metric
+ * @param value number used to update the percentileHistogram
+ */
+export declare function updatePercentileHistogramMetric(name: string, value: number): void;
+export declare function incrementGetRecordNormalInvokeCount(): void;
+export declare function incrementGetRecordNotifyChangeAllowCount(): void;
+export declare function incrementGetRecordNotifyChangeDropCount(): void;
+export declare function incrementNotifyRecordUpdateAvailableAllowCount(): void;
+export declare function incrementNotifyRecordUpdateAvailableDropCount(): void;
+/**
+ * Sets up instrumentation for @salesforce/lds-adapters-uiapi
+ */
+export declare function setLdsAdaptersUiapiInstrumentation(uiapiRegistration: LdsUiapiRegistration): void;
+/**
+ * Sets up instrumentation for @salesforce/lds-network-adapter
+ */
+export declare function setLdsNetworkAdapterInstrumentation(networkAdapterRegistration: LdsNetworkAdapterRegistration): void;
+/**
+ * Provides concrete implementations using o11y/client for instrumentation hooks
+ */
+export declare function setInstrumentationHooks(): void;
+/**
+ * Initialize the instrumentation and instrument the LDS instance and the InMemoryStore.
+ *
+ * @param luvio The Luvio instance to instrument.
+ * @param store The InMemoryStore to instrument.
+ */
+export declare function setupInstrumentation(luvio: Luvio, store: InMemoryStore): void;
+export declare function instrumentStoreMethods(luvio: Luvio, _store: InMemoryStore): void;
+export declare function handleIngestedNewData(event: CacheMissOutOfTtlEvent): void;
+export declare function handleOnDataOutOfTtlDurationUpdate(event: DataOutOfTtlDurationUpdateEvent): void;
+export declare function setStoreEventObservers(store: InMemoryStore): void;
+export declare const instrumentation: Instrumentation;

package/dist/metric-keys.d.ts

@@ -0,0 +1,191 @@
+export declare const ADAPTER_CACHE_HIT_COUNT_METRIC_NAME = "cache-hit-count";
+export declare const ADAPTER_CACHE_HIT_DURATION_METRIC_NAME = "cache-hit-duration";
+export declare const ADAPTER_CACHE_HIT_L2_COUNT_METRIC_NAME = "cache-hit-l2-count";
+export declare const ADAPTER_CACHE_HIT_L2_DURATION_METRIC_NAME = "cache-hit-l2-duration";
+export declare const ADAPTER_CACHE_MISS_COUNT_METRIC_NAME = "cache-miss-count";
+export declare const ADAPTER_CACHE_MISS_DURATION_METRIC_NAME = "cache-miss-duration";
+export declare const ADAPTER_CACHE_MISS_OUT_OF_TTL_COUNT_METRIC_NAME = "cache-miss-out-of-ttl-count";
+export declare const ADAPTER_CACHE_MISS_OUT_OF_TTL_DURATION_METRIC_NAME = "cache-miss-out-of-ttl-duration";
+export declare const REPRESENTATION_CACHE_MISS_OUT_OF_TTL_DATA_CHANGED_COUNT_METRIC_NAME = "cache-miss-out-of-ttl-data-changed-count";
+export declare const REPRESENTATION_CACHE_MISS_OUT_OF_TTL_DATA_UNCHANGED_COUNT_METRIC_NAME = "cache-miss-out-of-ttl-data-unchanged-count";
+export declare const REPRESENTATION_CACHE_MISS_OUT_OF_TTL_DATA_CHANGED_DURATION_METRIC_NAME = "cache-miss-out-of-ttl-data-changed-duration";
+export declare const REPRESENTATION_CACHE_MISS_OUT_OF_TTL_DATA_UNCHANGED_DURATION_METRIC_NAME = "cache-miss-out-of-ttl-data-unchanged-duration";
+/**
+ * W-8121791
+ * Number of subqueries used when aggregateUi is invoked for getRecord
+ */
+export declare const AGGREGATE_UI_CHUNK_COUNT = "aggregate-ui-chunk-count";
+/**
+ * W-6981216
+ * Counter for overall LDS cache hits.
+ * Note: This is also being recorded in AILTN logging.
+ */
+export declare const CACHE_HIT_COUNT = "cache-hit-count";
+/**
+ * W-6981216
+ * Counter for overall LDS cache hits.
+ * Note: This is also being recorded in AILTN logging.
+ */
+export declare const CACHE_MISS_COUNT = "cache-miss-count";
+/**
+ * W-9949353
+ * Used to track how often we dedupe HTTP requests
+ * Invoked when an HTTP request is deduped against an already in-flight request
+ */
+export declare const DUPLICATE_REQUEST_COUNT = "duplicate-request-count";
+/**
+ * W-7667066
+ * This count represents the number of times getRecord() was invoked, but not including
+ * executeAggregateUi calls.  It can be represented as the sum of the Aura Action invocations
+ * GetRecordWithLayouts and GetRecordWithFields.
+ */
+export declare const GET_RECORD_NORMAL_INVOKE_COUNT = "get-record-normal-invoke-count";
+/**
+ * W-7667066
+ * This count represents the number of times getRecord() was invoked, with a large enough payload
+ * that executeAggregateUi was used.
+ */
+export declare const GET_RECORD_AGGREGATE_INVOKE_COUNT = "get-record-aggregate-invoke-count";
+/**
+ * W-7301684
+ * Counter for when getRecordNotifyChange api calls are allowed through.
+ */
+export declare const GET_RECORD_NOTIFY_CHANGE_ALLOW_COUNT = "get-record-notify-change-allow-count";
+/**
+ * W-7301684
+ * Counter for when getRecordNotifyChange api calls are dropped/throttled.
+ */
+export declare const GET_RECORD_NOTIFY_CHANGE_DROP_COUNT = "get-record-notify-change-drop-count";
+/**
+ * W-11118785
+ * Counter for when notifyRecordUpdateAvailable api calls are allowed through.
+ */
+export declare const NOTIFY_RECORD_UPDATE_AVAILABLE_ALLOW_COUNT = "notify-record-update-available-allow-count";
+/**
+ * W-11118785
+ * Counter for when notifyRecordUpdateAvailable api calls are dropped/throttled.
+ */
+export declare const NOTIFY_RECORD_UPDATE_AVAILABLE_DROP_COUNT = "notify-record-update-available-drop-count";
+/**
+ * W-8278006
+ * Counter for rate limiting telemetry. Is updated whenever the network adapter hits the specified limit.
+ */
+export declare const NETWORK_RATE_LIMIT_EXCEEDED_COUNT = "network-rate-limit-exceeded-count";
+/**
+ * W-6981216
+ * Timer to measure performance for Luvio.storeBroadcast() method.
+ */
+export declare const STORE_BROADCAST_DURATION = "store-broadcast-duration";
+/**
+ * W-6981216
+ * Timer to measure performance for Luvio.storeIngest() method.
+ */
+export declare const STORE_INGEST_DURATION = "store-ingest-duration";
+/**
+ * W-6981216
+ * Timer to measure performance for Luvio.storeLookup() method.
+ */
+export declare const STORE_LOOKUP_DURATION = "store-lookup-duration";
+/**
+ * W-9805009
+ * Timer to measure performance for Luvio.storeSetTTLOverride() method.
+ */
+export declare const STORE_SET_TTL_OVERRIDE_DURATION = "store-set-ttl-override-duration";
+/**
+ * W-9805009
+ * Timer to measure performance for Luvio.storeSetDefaultTTLOverride() method.
+ */
+export declare const STORE_SET_DEFAULT_TTL_OVERRIDE_DURATION = "store-set-default-ttl-override-duration";
+/**
+ * W-11118785
+ * Timer to measure performance for Luvio.notifyStoreUpdateAvailable() method.
+ */
+export declare const NOTIFY_STORE_UPDATE_AVAILABLE_DURATION = "notify-store-update-available-duration";
+/**
+ * W-6981216
+ * Counter for number of records in LDS store. Is updated by periodicLogger invocations.
+ * Note: This is also being recorded in AILTN logging.
+ */
+export declare const STORE_SIZE_COUNT = "store-size-count";
+/**
+ * W-6981216
+ * Counter for number of LDS snapshot subscription. Is updated by periodicLogger invocations.
+ * Note: This is also being recorded in AILTN logging.
+ */
+export declare const STORE_SNAPSHOT_SUBSCRIPTIONS_COUNT = "store-snapshot-subscriptions-count";
+/**
+ * W-6981216
+ * Counter for number of LDS watch subscriptions. Is updated by periodicLogger invocations.
+ * Note: This is also being recorded in AILTN logging.
+ */
+export declare const STORE_WATCH_SUBSCRIPTIONS_COUNT = "store-watch-subscriptions-count";
+/**
+ * W-9131128
+ * Counter for graphQL get adapter response with mixed bag of both data and error in response
+ */
+export declare const GET_GRAPHQL_RESPONSE_MIXED = "get-graphql-response-mixed-count";
+/**
+ * W-9537401
+ * Counter for Luvio store trim task invocation
+ */
+export declare const STORE_TRIM_TASK_COUNT = "store-trim-task-count";
+/**
+ * W-9537401
+ * Timer to measure performance for Luvio store trim task
+ */
+export declare const STORE_TRIM_TASK_DURATION = "store-trim-task-duration";
+/**
+ * W-9804037
+ * Counters for Luvio cache policy usage
+ * Note: Undefined cache policy defaults to different cache policies based on runtime
+ */
+export declare const CACHE_POLICY_COUNTERS: {
+    'cache-and-network': string;
+    'cache-then-network': string;
+    'no-cache': string;
+    'only-if-cached': string;
+    'stale-while-revalidate': string;
+    'valid-at': string;
+};
+export declare const CACHE_POLICY_UNDEFINED_COUNTER = "cache-policy-undefined";
+export declare const STALE_TAG = "stale";
+/**
+ * W-9804037
+ * Durable Store health metric
+ * Counter to track Durable Store read, write and error rates
+ */
+export declare const DURABLE_STORE_COUNT = "durable-store-count";
+/**
+ * W-10490363
+ * GraphQL Eval health metric
+ * Counter to track Success and Error Rate on Eval
+ */
+export declare const GRAPHQL_ADAPTER_COUNT = "graphql-adapter-count";
+/**
+ * Counter for tracking invalid record type IDs
+ */
+export declare const RECORD_TYPE_ID_IS_NULL_COUNT = "record-type-id-is-null-count";
+/**
+ * W-12293528
+ * GraphQL health metric
+ * Counter to track size of the top-level GraphQL object
+ */
+export declare const STORE_GRAPHQL_SIZE_COUNT = "store-graphql-size-count";
+/**
+ * W-12293528
+ * GraphQL health metric
+ * Counter to track validation errors in query
+ */
+export declare const GRAPHQL_QUERY_VALIDATION_ERROR_COUNT = "graphql-query-validation-error-count";
+/**
+ * W-12293528
+ * GraphQL health metric
+ * Counter to track syntax errors in query
+ */
+export declare const GRAPHQL_QUERY_SYNTAX_ERROR_COUNT = "graphql-query-syntax-error-count";
+/**
+ * W-12293528
+ * GraphQL health metric
+ * Counter to track miscellaneous errors in query
+ */
+export declare const GRAPHQL_QUERY_OTHER_ERROR_COUNT = "graphql-query-other-error-count";

package/dist/utils/language.d.ts

@@ -0,0 +1,13 @@
+declare const create: {
+    (o: object | null): any;
+    (o: object | null, properties: PropertyDescriptorMap & ThisType<any>): any;
+}, keys: {
+    (o: object): string[];
+    (o: {}): string[];
+};
+declare const isArray: (arg: any) => arg is any[];
+declare const parse: (text: string, reviver?: ((this: any, key: string, value: any) => any) | undefined) => any, stringify: {
+    (value: any, replacer?: ((this: any, key: string, value: any) => any) | undefined, space?: string | number | undefined): string;
+    (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string;
+};
+export { create as ObjectCreate, keys as ObjectKeys, isArray as ArrayIsArray, stringify as JSONStringify, parse as JSONParse, };

package/dist/utils/lru-cache.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Inspired by https://www.npmjs.com/package/hashlru
+ */
+export declare class LRUCache {
+    private oldCache;
+    private newCache;
+    private size;
+    private limit;
+    constructor(limit: number);
+    private checkSize;
+    get(key: string): any;
+    set(key: string, value: any): void;
+    delete(key: string): void;
+}

package/dist/utils/observability.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Observability / Critical Availability Program (230+)
+ *
+ * This file is intended to be used as a consolidated place for all definitions, functions,
+ * and helpers related to "M1"[1].
+ *
+ * Below are the R.E.A.D.S. metrics for the Lightning Data Service, defined here[2].
+ *
+ * [1] https://salesforce.quip.com/NfW9AsbGEaTY
+ * [2] https://salesforce.quip.com/1dFvAba1b0eq
+ */
+export declare const OBSERVABILITY_NAMESPACE = "LIGHTNING.lds.service";
+export declare const ADAPTER_INVOCATION_COUNT_METRIC_NAME = "request";
+export declare const ADAPTER_ERROR_COUNT_METRIC_NAME = "error";
+/**
+ * W-8828410
+ * Counter for the number of UnfulfilledSnapshotErrors the luvio engine has.
+ */
+export declare const TOTAL_ADAPTER_ERROR_COUNT = "error";
+/**
+ * W-8828410
+ * Counter for the number of invocations made into LDS by a wire adapter.
+ */
+export declare const TOTAL_ADAPTER_REQUEST_SUCCESS_COUNT = "request";

package/dist/utils/utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A deterministic JSON stringify implementation. Heavily adapted from https://github.com/epoberezkin/fast-json-stable-stringify.
+ * This is needed because insertion order for JSON.stringify(object) affects output:
+ * JSON.stringify({a: 1, b: 2})
+ *      "{"a":1,"b":2}"
+ * JSON.stringify({b: 2, a: 1})
+ *      "{"b":2,"a":1}"
+ * Modified from the apex implementation to sort arrays non-destructively.
+ * @param data Data to be JSON-stringified.
+ * @returns JSON.stringified value with consistent ordering of keys.
+ */
+export declare function stableJSONStringify(node: any): string | undefined;
+export declare function isPromise<D>(value: D | Promise<D> | null): value is Promise<D>;
+export declare function isAdapterError(error: unknown): boolean;
+export declare function throttle(callback: () => void, ms: number): () => void;

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@salesforce/lds-instrumentation",
+    "version": "1.100.2",
+    "license": "SEE LICENSE IN LICENSE.txt",
+    "description": "Instrumentation utils for Lightning Data Service",
+    "main": "dist/ldsInstrumentation.js",
+    "module": "dist/ldsInstrumentation.js",
+    "types": "dist/main.d.ts",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "import": "./dist/ldsInstrumentation.js",
+            "types": "./dist/main.d.ts",
+            "default": "./dist/ldsInstrumentation.js"
+        }
+    },
+    "sfdc": {
+        "path": "forcelds/ldsInstrumentation/",
+        "publishedFileName": "ldsInstrumentation.js",
+        "overrides": {
+            "artifactDirectory": "dist"
+        }
+    },
+    "scripts": {
+        "prepare": "yarn build",
+        "build": "rollup --config rollup.config.js",
+        "clean": "rm -rf dist",
+        "test:unit": "jest",
+        "test:debug": "node --inspect-brk ../../node_modules/.bin/jest --runInBand",
+        "test:size": "bundlesize",
+        "release:corejar": "yarn build && ../core-build/scripts/core.js --name=lds-instrumentation"
+    },
+    "dependencies": {
+        "@salesforce/lds-bindings": "^1.100.2",
+        "@salesforce/lds-default-luvio": "^1.100.2",
+        "@salesforce/lds-utils-adapters": "^1.100.2",
+        "o11y": "244.0.0",
+        "o11y_schema": "244.0.0"
+    },
+    "devDependencies": {
+        "@salesforce/lds-adapters-uiapi": "^1.100.2",
+        "@salesforce/lds-network-adapter": "^1.100.2"
+    },
+    "bundlesize": [
+        {
+            "path": "./dist/ldsInstrumentation.js",
+            "maxSize": "15 kB",
+            "compression": "brotli"
+        }
+    ]
+}