The Telemetry Client is an NPM package available as @guardian/user-telemetry-client
to make sending events to the
backend simple.
The package provides two benefits, type safety for the events format and a mechanism for sending events featuring a buffer, throttle and retry mechanism.
Initalisation:
const telemetrySender = new UserTelemetryEventSender(url, 100);
Example event:
const exampleEvent: IUserTelemetryEvent = {
app: "example-app",
stage: "PROD",
type: "EXAMPLE_EVENT_TYPE",
value: 1,
eventTime: "2020-09-03T07:51:27.669Z",
tags: {
ruleId: "id",
suggestion: "suggestion",
matchId: "matchId",
matchedText: "some matched text",
matchContext: "matchContext",
documentUrl: "documentUrl"
}
};
Sending events:
// Add event to buffer to be sent
telemetrySender.addEvent(exampleEvent);
// Send all events immediately
await telemetrySender.flushEvents()
Authentication can be handled in several ways:
By default, the client will apply credentials: "include"
to outgoing telemetry event requests. This uses the standard
browser features to provide authentication cookies and headers in requests.
The Telemetry client backend is designed to expect a Panda Auth Cookie.
An alternative is to use HMAC headers. This is useful when the client may be running in an environment with no request cookies available. It also provides the means for machine-to-machine authentication.
The HMAC headers middleware makes use of the crypto
Node package, which is not available in the browser. Therefore, it
can only be used in a Node environment.
To avoid issues with attempt to import a Node only module, the middleware is made available specifically
on @guardian/user-telemetry-client/authentication/node
.
It is possible to provide your own middleware for any custom requirements.
Format:
type GuAuthMiddleware = (requestInit: RequestInit) => RequestInit