Sentry module for plugins for js-controller and adapters
npm install @iobroker/plugin-sentrySentry.io, developers can receive real-time notifications and detailed reports of errors or exceptions in ioBroker systems, helping to identify and resolve issues promptly and ensuring the stability and reliability of home automation setups.The integration with our Sentry server enables users to gather valuable information about the errors, including the stack trace, affected devices, and other relevant data.
This information helps analyze and debug the problems effectively, leading to improved performance and stability of the ioBroker system.
Providing consent to iobroker GmbH to collect diagnostic data, results in the inclusion of an anonymous installation ID without any additional information about you, such as email or name, is included.
This enables Sentry to group errors and gain insight into the number of unique users affected by a particular error. It's important to note that no IP addresses are present within crash reports, with all data deleted within 90 days at the latest.
All of these helps developers to provide an error-free smart home system that never crashes. :-)
1. Use the ioBroker CLI commands:
- To disable Sentry for the current host, use: iobroker plugin disable sentry.
- To disable Sentry for a specific adapter/instance, use:
iobroker plugin disable sentry --instance adaptername.nr
1. Adjust the corresponding state values:
- For js-controller hosts, set the state system.host.NAME.plugins.sentry.enabled to false.
- Set the state system.adapter.NAME.INSTANCE.plugins.sentry.enabled to false for adapter instances.
Upon making these changes, you should see a log message confirming the disabling of Sentry.
Note: Once the plugin is disabled, the automatic reporting of system crashes will cease. If you still want to report any issues, you must do so manually.
``json`
{
"common": {
"plugins": {
"sentry": {
"dsn": "https://...@.../..."
}
}
}
}
Two additional optional configuration options that can be also provided if required:
`json`
{
"common": {
"plugins": {
"sentry": {
"dsn": "https://...@.../...",
"pathWhitelist": [
"@iobroker",
"iobroker.js-controller"
],
"pathBlacklist": [
"scripts.js"
],
"errorBlacklist": [
"SyntaxError"
]
}
}
}
}
The configuration includes the following settings:
- dsn (Required): This is the Sentry DSN, obtained after creating the Sentry project.
- pathWhitelist (Optional): An array of strings that specify the required path components for reporting. Only sends exceptions with filenames containing at least one of these strings.
- pathBlacklist (Optional): An array of strings used to check against each exception's lines. The exception will not send if any line contains one of these strings.
- errorBlacklist (Optional): An array of error types that will not be reported. Automatically adds the "SyntaxError" type since these errors are typically caught during development and not in production with real customers.
Define configurations in either the "common" area of the io-package.json file or in iobroker.data/iobroker.json at the main level, specifically for the js-controller.
1. Sentry.io: You can sign up for a free account on Sentry.io, which offers up to 5,000 monthly events at no cost. With this option, you have complete control over your account, but it's important to note that the service is hosted in the USA.
2. Contact @Apollon77: Another option is to reach out to @Apollon77 to discuss the possibility of getting an account on the ioBroker own Sentry Server instance. However, please be aware that this option may be subject to limitations based on available server resources, so it cannot be guaranteed.
The basic process to use the ioBroker Sentry system is as follows:
1. Contact @Apollon77 by creating an issue in this project for each adapter you require access to. Make sure to include the link to the adapter repository.
1. We will conduct an enhanced adapter review, specifically focusing on error handling to ensure that adapters do not flood the Sentry system.
1. We will need your email address to invite you to the Sentry instance, and you will need a Two-Factor-Authentication app (e.g., Google Authenticator) to secure your account.
1. We will create the project on Sentry and assign it to you.
1. We will provide you with the necessary Sentry DSN for your configuration.
1. You must add the configuration to the io-package.json file and include a short information section in your README. Please add the following notice to the top of your README:
This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and instructions on disabling error reporting, please refer to the Sentry-Plugin Documentation! Use of Sentry reporting starts with js-controller 3.0.
1. We can discuss the details separately if you wish to transfer your own errors or other events.
1. With everything finally set up, you can test and release your adapter.
Please follow these steps for smooth integration with the ioBroker Sentry system.
This plugin respects the "enabled" state created by system.adapter.name.X.plugins.sentry.enabled and will not initialize the error reporting if set to false.
It will not create additional states.
To catch uncaught exceptions and unhandled promises, add the configuration above to the common section of your io-package.json file. Once you have done that, you're all set. Automatic use of the plugin will occur when js-controller 3.0 is in use.
`javascript`
try {
// ...
throw new Error('...');
} catch(error) {
if (adapter.supportsFeature && adapter.supportsFeature('PLUGINS')) {
const sentryInstance = adapter.getPluginInstance('sentry');
if (sentryInstance) {
sentryInstance.getSentryObject().captureException(error);
}
}
}
`javascript`
if (adapter.supportsFeature && adapter.supportsFeature('PLUGINS')) {
const sentryInstance = adapter.getPluginInstance('sentry');
if (sentryInstance) {
const Sentry = sentryInstance.getSentryObject();
Sentry && Sentry.withScope(scope => {
scope.setLevel('info');
scope.setExtra('key', 'value');
Sentry.captureMessage('Event name', 'info'); // Level "info"
});
}
}
huhu();
or
setTimeout(huhu, 10000);
This should cause the adapter to crash and the exception to be shown in the sentry UI some seconds/minutes later
Breaking Changes: Due to the port to Plugin Base v2, init` now returns a promise instead of accepting a callback parameter, also the export has changed to a named export