README

Lightning Web Security (LWS) instrumentation package

The instrumentation package provides interfaces to facilitate instrumenting Lightning Web Security 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

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

Implementation for LWS instrumentation interface

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

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

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

    class MyInstrumentation extends Instrumentation {
        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();
}

let myInstrumentation = makeLockerInstrumentation(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 disect and re-format the data into the format that the instrumentation client accepts.

startActivity

const { startActivity } = myInstrumentation;
// 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;
} finally {
    // we stop the activity after last instrumeted 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:

Extend the class Instrumentation from @locker/instrumentation.

import { Activity, DefaultInstrumentation, LockerInstrumentationDataType } from '@locker/instrumentation';

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

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

class MyInstrumentation extends DefaultInstrumentation {
    startActivity(data: LockerInstrumentationDataType) {
        return new Activity(activityId, startCallback, stopCallback);
    }
    errorBeacon(data: LockerInstrumentationDataType) {
        errorCallback(sandboxKey, e.message, e.type, e.stack);
    }
    logBeacon(data: LockerInstrumentationDataType) {
        logCallback(sandboxKey, message);
    }
}

Activity will call startCallback and stopCallback respectively when an activity is started or stoped.

Invoke evaluateInSandbox or evaluateInCoreSandbox and provide MyInstrumentation as an argument

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

Usage no npm install needed!