@locker/instrumentation v0.23.5

@locker/instrumentation

Lightning Web Security instrumentation utilities

This package provides interfaces to facilitate instrumenting Lightning Web Security (LWS) code without having to bind the entire codebase to an external interface.

There are three instrumentation functions on the main interface, 1 for instrumenting errors, 1 for generic logging and 1 for metrics (activity).

Consumer of LWS needs to provide actual instrumentation service and the wrapper classes which implements the interfaces defined by this package. This package provides a mock implementation to be used when the consumer does not provide any instrumentation service.

Usage

LWS code base

// The `myInstrumentation` object is a wrapper for the actual instrumentation
// client which implements Locker instrumentation interface.
let { error, log, startActivity } = myInstrumentation;
let activity = startActivity('AwesomeActivity', data);
try {
    foo();
    error({ errorData });
    log({ logData });
} catch (e) {
    activity.error(e);
    throw e;
}
activity.stop();

Implementation for LWS instrumentation interface

import { LockerActivity, LockerInstrumentation } from '@locker/instrumentation';
import { evaluateInSandbox } from '@locker/sandbox';

function createLockerInstrumentation(myInstrumentationClient) {
    const activityStartCallback = (activity, data) => {
        // Call myInstrumentationService to start a performance activity metric.
    };

    const activityStopCallback = (activity, data) => {
        // Call myInstrumentationService to stop a performance activity metric.
    };

    class MyInstrumentation extends LockerInstrumentation {
        startActivity(activityName, data) {
            const activity = new LockerActivity(
                activityName,
                activityStartCallback,
                activityStopCallback
            );
            activity.start(data);
            return activity;
        }

        error(data) {
            // Call myInstrumentationClient to log an error.
        }

        log(data) {
            // Call myInstrumentationClient to make a regular log.
        }
    }

    return new MyInstrumentation();
}

const myInstrumentation = createLockerInstrumentation(myInstrumentationClient);

evaluateInSandbox(key, code, null, null, myInstrumentation);

Instrumentation interface

Due to possible restrictions on the instrumentation service, the high volume of method calls and privacy considerations in sandboxed code, Locker cannot instrument serialized method parameters or method return values. As a consequence, LWS instrumentation interface will invoke the instrumentation client using specific information.

LWS instrumentation interface accepts telemetry data with simple JSON objects or native simple types (string, boolean, number). It is expected that the wrapper of the instrumentation client to dissect and re-format the data into the format that the instrumentation client accepts.

startActivity

const { startActivity } = myInstrumentation;
// The instrumented activity is started for current `sandboxKey`.
const myActivity = startActivity(sandboxKey, 'fooActivity');
try {
    foo();
} catch (e) {
    // Stop the activity with error.
    activity.error(e);
    throw e;
}
// Stop the activity after last instrumented call.
activity.stop();

log

const { log } = const { startActivity } = myInstrumentation;
const foo: Array = bar();
log(`bar method returned ${foo.length} results.`);
log({ sandboxKey, message: `bar method returned ${foo.length} results.` });

error

const { error } = new LockerInstrumentation(myService);

try {
    foo();
} catch (e) {
    error(`${e}`);
    error({ sandboxKey, error: e });
    throw e;
}

Plugging in an external instrumentation service

To plug in an external service in Lightning Web Security the following steps are required:

1. Extend the class Instrumentation from @locker/instrumentation.

import { LockerActivity , LockerInstrumentation } from '@locker/instrumentation';
import type { DataType } from '@locker/instrumentation';

const activityStartCallback = (activity, data) => {
    // Call external instrumentation service to start a performance activity metric.
};

const activityStopCallback = (activity, data) => {
    // Call external instrumentation service to stop a performance activity metric.
};

class MyInstrumentation extends LockerInstrumentation {
    startActivity(activityName: string, data?: DataType) {
        return new LockerActivity(activityName, startCallback, stopCallback);
    }
    error(data?: DataType) {
        errorCallback(data);
    }
    log(data?: DataType) {
        logCallback(data);
    }
}

LockerActivity will call startCallback and stopCallback respectively when an activity is started or stopped.

2. Invoke evaluateInSandbox or evaluateInCoreSandbox and provide MyInstrumentation as an argument.

const instrumentation = new MyInstrumentation();
evaluateInSandbox(key, code, null, null, instrumentation);