@locker/instrumentation

Locker vNext instrumentation package

The instrumentation package provides utility functions, also known as beacons, to facilitate instrumenting Locker vNext code without having to bind the entire codebase to an external interface.

There are 3 beacons provided, 1 for instrumenting errors, 1 for generic logging and 1 for metrics (activity).

Usage

import { LockerInstrumentation } from '@locker/instrumentation';

const { activityBeacon, errorBeacon, logBeacon } = new LockerInstrumentation();

The beacons can now be used to instrument code in Locker.

Beacons 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, the beacons will invoke the instrumentation client using specific information.

activityBeacon

const { activityBeacon } = new LockerInstrumentation(myService);
// instrumented activity is started for current sandboxKey
const myActivity = activityBeacon(sandboxKey, 'fooActivity');
myActivity.start();
// or use chaining
// const myActivity = activityBeacon(sandboxKey, 'fooActivity').start();

foo();
// we stop the activity after last instrumeted call
myActivity.stop();

logBeacon

const { logBeacon } = new LockerInstrumentation(myService);
const foo: Array = bar();
logBeacon(sandboxKey, `bar method returned ${foo.length} results.`);

errorBeacon

const { errorBeacon } = new LockerInstrumentation(myService);

try {
    foo();
} catch (e) {
    errorBeacon(sandboxKey, e);
    throw e;
}

Plugging in an external instrumentation service

To plug in an external service in Locker vNext the following steps are required:

1. Extend the class LockerInstrumentation.

class MyInstrumentation extends LockerInstrumentation {
    activityBeacon(sandboxKey, nameOrDescription) {
        return new Activity(sandboxKey, nameOrDescription, startCallback, stopCallback);
    }
    errorBeacon(sandboxKey, e) {
        errorCallback(sandboxKey, e.message, e.type, e.stack);
    }
    logBeacon(sandboxKey, message) {
        logCallback(sandboxKey, message);
    }
}

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

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