TelemetryCollector-Api for developers

Developers
,
1

Minimal lightweight logging for Homey Apps

This module will be used in a Homey app to send logs to the TelemetryCollector App.

This module is implemented as a mixin pattern to simplify the use of the interface.

(For more information about mixins, see: > Useful Links > Mixins)

Setting it up

Install

npm install homey-telemetrycollector-api

Add permission

"permissions": ["homey:app:org.cflat-inc.telemetryCollector"]

Install TelemetryCollector-Api

require('homey-telemetrycollector-api').install;

Use it

this.logDebug('So easy it goes');

API

Error: error conditions

this.logError('logError-Message');

Warning: warning conditions

this.logWarning('logWarning-Message');

Notice: normal but significant condition

this.logNotice('logNotice-Message');

Informational: informational messages

this.logInfo('logInfo-Message');

Debug: debug-level messages

this.logDebug('logDebug-Message');

Code examples

Homey.App


'use strict';

const Homey = require('homey');

// Install the TelemetryCollector Api
require('homey-telemetrycollector-api').install;

// Development
const inspector = require('node:inspector');

if (process.env.DEBUG === '1') {
  try {
    inspector.waitForDebugger();
  } catch (err) {
    inspector.open(9229, '0.0.0.0', true);
  }
}

module.exports = class MyApp extends Homey.App {
  async onInit() {
    // ...
    this.logInfo('App has been initialized');
  }
};

Migrations guide

Preferred

Rename the methods, it’s fast (global search & replace), the code is more readable and the method calls the console message at the end anyway.

  • this.log() > (renameTo) > this.logInfo()

  • this.error() > (renameTo) > this.logError()

  • this.debug() > (renameTo) > this.logDebug()

Useful Links

Logging

Mixins

ToDo

Thanks

Special thanks to all for the help in testing the new version.

Disclaimer

Use at your own risk. I accept no responsibility for any damages caused by using this app.

Copyright

© Chris Gross / cflat-inc.org, 2025

2

Good to know

Not all console messages are output in debug mode.

During the HP2023 beta phase, I already noticed that no console message is output for classes that inherit directly from the “Homey.SimpleClass”. I reported this to Athom and received the response “It works as designed”.

But the TelemetryCollector-Api sends the message to the agents in any case.

Enhancement of the log message

Each message text is automatically enhanced by the api with the class name and, if available, the name of the device.

this.logInfo('Initialized')

‘[ClassName] > [Message]’ result: ’ MyApp > Initialized’

‘[ClassName] > [DeviceName] > [Message]’ result: ‘MyDevice > Sample Device > Initialized’

Log message and metadata.

Metadata is added to each log message. These can be used by the observability servers as filters (labels).

Example:

{
  level: "debug",
  message: "PlayerDevice > Büro 31 Audio > setUnavailable()",
  timestamp: "2025-03-01T09:20:28.364Z",
  metadata: {
    id: "89e4cf57-29b0-4f38-89ff-0269e04271ea",
    app: "WiiM",
    appID: "org.cflat-inc.wiim",
    facility: "17",
    facilityName: "Device",
    class: "PlayerDevice",
    deviceID: "FF98F09C-74E9-46A5-07FF-155EFF98F09C",
    deviceName: "Büro 31 Audio",
  },
}
3
  1. For later use
4
  1. For later use