Node Tracks

A Tracks wrapper for NodeJS

⚠️⚠️⚠️⚠️ This library is for internal use at Automattic only. Join us! ⚠️⚠️⚠️⚠️

How to use

Requires Node.js 22 or newer.

import tracker from '@automattic/node-tracks';

const trackEvent = tracker( '<valid_event_prefix>', { _ut: '<valid_event_user_type>' } ).trackEvent;
// tracker takes 2 arguments
// prefix (string): all your events will be prefixed with this
// globalParams (object): this is a global object that will be sent with all requests. `_ut` is required

trackEvent( 'eventName', extraParams, logger );
// trackEvent takes 3 arguments
// eventName (string) : Your event name
// extraParams (object): Any extra params
// logger (optional): will log to the console otherwise

Use trackEventAndForget in short-lived commands that need a bounded delivery attempt:

const trackEventAndForget = tracker( '<valid_event_prefix>', {
	_ut: '<valid_event_user_type>',
} ).trackEventAndForget;

await trackEventAndForget( 'event_name', extraParams, logger );

trackEventAndForget uses a non-keep-alive request and closes the response after its headers arrive. This prevents the response socket from keeping a CLI alive. Its default hard timeout is 500 ms. Pass a custom timeout in milliseconds as the fourth argument. A timeout or network failure closes the request and response and resolves the Promise. Telemetry failure does not change caller control flow. A slow DNS lookup can still keep the process alive after the Promise resolves.

Please refer to this table for a list of all extraParams

Contributing

See CONTRIBUTING.md for details on development, testing, publishing, etc.