Tracking

Command Tracking

Command tracking allows you to monitor the progress of long-running write operations (SET VAR, INSTCMD) on the NUT server. Requires NUT 2.8.0+ (protocol v1.3).

When tracking is enabled, write commands return OK TRACKING <uuid> instead of OK. The UUID can be polled to check the command outcome: PENDING, SUCCESS, or ERR.

Enable Tracking

await client.setTracking(true);

Manual Polling

const result = await client.runCommand('myups', 'shutdown.return', '60');

if (result.tracked && 'trackingUid' in result) {
  let status;
  do {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    status = await client.getTracking(result.trackingUid);
    console.log('Status:', status);
  } while (status === 'PENDING');

  if (status === 'SUCCESS') {
    console.log('Command completed successfully');
  } else {
    console.log('Command failed');
  }
}

Automatic Polling with followTracking

Pass followTracking: true in the options to have the client poll automatically and resolve when the command completes:

const result = await client.runCommand('myups', 'shutdown.return', '60', {
  followTracking: true,
  trackingTimeout: 60000,       // max wait time (default: 30s)
  trackingPollInterval: 5000    // poll interval (default: 1s)
});

if (result.tracked && result.status === 'SUCCESS') {
  console.log('Command completed successfully');
}

The same works with setVariable:

const result = await client.setVariable('myups', 'ups.delay.start', '60', {
  followTracking: true,
  trackingTimeout: 30000,
  trackingPollInterval: 1000
});

How It Works

1. You call setTracking(true) to tell the NUT server to include tracking IDs in responses.
2. When you run a write command (runCommand or setVariable), the server responds with OK TRACKING <uuid> instead of OK.
3. NUTClient.runCommand() parses this into a CommandResult object: { tracked: true, trackingUid: '...' }.
4. With followTracking: true, the client polls getTracking(uuid) at the configured interval until the status is no longer PENDING.
5. The final result is a TrackedResult: { tracked: true, status: 'SUCCESS' | 'ERR' }.

Types

interface TrackingOptions {
  followTracking?: boolean;         // auto-poll until completion
  trackingTimeout?: number;         // max wait in ms (default: 30000)
  trackingPollInterval?: number;    // poll interval in ms (default: 1000)
}

type CommandResult =
  | { tracked: true; trackingUid: string }
  | { tracked: false; success: true };

type TrackedResult =
  | { tracked: true; status: 'SUCCESS' | 'ERR' }
  | { tracked: false; success: true };

Disable Tracking

await client.setTracking(false);

Notes

• Only write commands are tracked (SET VAR, INSTCMD). Read operations (GET VAR, LIST) are not affected.
• If tracking is not enabled on the server, commands return { tracked: false, success: true } — they still work, but you can't poll for status.
• The followTracking option throws an error if the polling times out (trackingTimeout).
• See the NUT network protocol documentation for details.