87 KiB
Modules
- import-meta-url
Utility module to provide a compatible import.meta.url equivalent in CommonJS modules.
This module creates a URL object that represents the current file's path, which can be used in a similar way to import.meta.url in ES modules. This is necessary for CommonJS modules that need file path resolution capabilities similar to those available in ES modules.
Classes
- Settings
- UdpEvents
Class for tracking counts of UDP events received from Qlik Sense.
This class provides thread-safe methods to track different types of events:
- Log events (from various Qlik Sense services)
- User events (user session related events)
- Rejected log events (events that didn't match filtering criteria)
Constants
- requestHealth
Creates and executes an HTTP request to check if the application is healthy. Used for Docker health checks to determine container health status. Exits with code 0 if health check succeeds, 1 otherwise.
- confifgFileSchema :
object Schema definition for Butler SOS configuration file validation.
This schema is used with AJV (Another JSON Validator) to validate the structure and content of the Butler SOS YAML configuration file. It defines all possible configuration options, their data types, validation rules, and which options are required.
The schema includes validation for:
- General application settings (logging, telemetry, etc.)
- Server connection details
- Integration configurations (InfluxDB, MQTT, etc.)
- User event and log event handling
- Monitoring options and filters
- Prometheus metrics
- Third-party tool credentials
- callRemoteURL ⇒
void Sends anonymous telemetry data to PostHog.
This function collects information about the Butler SOS instance, its environment, and which features are enabled/disabled. This data helps the developers understand how Butler SOS is being used and prioritize development efforts accordingly.
The telemetry includes:
- System information (OS, architecture, Node.js version)
- Enabled/disabled features
- Configuration settings (without sensitive information)
- Whether the app is running in Docker
No personally identifiable information or sensitive configuration data is collected.
- isoDateRegex :
RegExp Regular expression that matches ISO8601 date format strings. Matches patterns like "2021-11-09T15:37:26.028+0200".
- uuidRegex :
RegExp Regular expression that matches UUID format strings. Matches standard UUID patterns like "550e8400-e29b-41d4-a716-446655440000".
Functions
- sleep(ms) ⇒
Promise.<void> Delays execution for the specified amount of time.
- mainScript() ⇒
Promise.<void> Main application entry point that initializes and starts all Butler SOS services.
This function initializes globals, sets up logging, starts UDP servers for user events and log events, and initializes various metrics collection services based on configuration.
- getAppNames() ⇒
void Retrieves application names from the Qlik Repository Service (QRS) API.
This function connects to the Qlik Sense repository database and fetches information about all available applications. It stores the app information (id, name, description) in the global appNames variable for use throughout the Butler SOS application.
- setupAppNamesExtractTimer() ⇒
void Sets up a timer for periodically retrieving app names from the Qlik Repository Service.
This function initializes a timer that calls getAppNames() at regular intervals specified by the Butler-SOS.appNames.extractInterval configuration setting. This ensures that the Butler SOS application always has up-to-date information about Qlik Sense applications.
- verifyConfigFileSchema(configFile) ⇒
Promise.<boolean> Verifies that the config file has the correct format. Use yaml-validator to validate the config file
- verifyAppConfig(cfg) ⇒
Promise.<boolean> Verifies application-specific settings and relationships between configuration settings.
This function performs validation beyond simple schema validation, checking:
- If InfluxDB is enabled, verifies that version is valid (must be 1 or 2)
- Validates server tag configuration:
- All tags defined in serverTagsDefinition must be set for each server
- All tags specified for each server must be present in serverTagsDefinition
- configObfuscate(config) ⇒
object Obfuscates sensitive information in the Butler SOS configuration object.
This function creates a copy of the configuration object and replaces sensitive information with masked strings to prevent leaking sensitive data when displaying the configuration through the web interface. It typically keeps a small prefix of the original value (e.g., first 3-10 characters) and replaces the rest with asterisks.
Obfuscated fields include:
- Server hostnames and IP addresses
- API keys and passwords
- Certificate paths and passphrases
- MQTT topics
- InfluxDB credentials and parameters
- Headers containing authentication information
- Application IDs and names
- setupConfigVisServer([logger], [config]) ⇒
Promise.<void> Sets up and starts a web server for visualizing Butler SOS configuration.
This function creates a Fastify server that serves a web interface where users can view the current Butler SOS configuration in a more readable format. It includes:
- Rate limiting to prevent abuse
- Optional obfuscation of sensitive configuration values
- Serving static files for the web interface
- Rendering the configuration as both JSON and YAML
- getCertificates(options) ⇒
object Loads TLS certificates from the filesystem based on the provided options.
- getHealthStatsFromSense(serverName, host, tags, headers) ⇒
void Retrieves health statistics from Qlik Sense server via the engine healthcheck API.
This function makes an HTTPS request to the Sense engine healthcheck API and distributes the data to configured destinations (MQTT, InfluxDB, New Relic, Prometheus).
- setupHealthMetricsTimer() ⇒
void Sets up a timer that periodically collects health metrics from all configured Sense servers.
This function creates an interval that runs every pollingInterval milliseconds (as defined in config) and calls getHealthStatsFromSense for each server in the serverList global variable.
- callRemoteURL(remoteURL, logger) ⇒
void Sends a heartbeat GET request to a remote URL.
- setupHeartbeatTimer(config, logger) ⇒
void Sets up a scheduled timer for sending heartbeat requests to a remote URL.
This function configures a scheduled timer based on the frequency specified in the configuration. It also performs an initial heartbeat request immediately.
- categoriseLogEvent(logLevel, logMessage) ⇒
object Categorizes log events based on configured rules.
This function analyzes log events from Qlik Sense services and categorizes them based on matching rules defined in the configuration. Rules can match on log level and message content using different filters (starts with, ends with, contains). Rules can also specify if a matched log event should be dropped.
The function returns an object with two properties:
- category: An array of objects, each representing a category. Each category object has two properties: name and value.
- actionTaken: A string indicating the action taken on the log event. Possible values are 'categorised' and 'dropped'.
If no rule matches, then the function uses the default category (if enabled in the config file) and sets actionTaken to 'categorised'.
If an error occurs while processing the log event, then the function logs an error message and returns null.
- getFormattedTime(serverStarted) ⇒
string Calculates and formats the uptime of a Qlik Sense engine.
This function takes the server start time from the engine healthcheck API and calculates how long the server has been running, returning a formatted string.
- postHealthMetricsToInfluxdb(serverName, host, body, serverTags) ⇒
Promise.<void> Posts health metrics data from Qlik Sense to InfluxDB.
This function processes health data from the Sense engine's healthcheck API and formats it for storage in InfluxDB. It handles various metrics including:
- CPU usage
- Memory usage
- Cache metrics
- Active/loaded/in-memory apps
- Session counts
- User counts
- storeLoadedDoc(docID) ⇒
Promise Stores a loaded app name in memory.
- storeInMemoryDoc(docID) ⇒
Promise.<void> Stores a document ID in either the sessionAppNamesInMemory or appNamesInMemory arrays.
- postProxySessionsToInfluxdb(userSessions) ⇒
Promise.<void> Posts proxy sessions data to InfluxDB.
This function takes user session data from Qlik Sense proxy and formats it for storage in InfluxDB. It handles different versions of InfluxDB (1.x and 2.x) and includes error handling with detailed logging.
- postButlerSOSMemoryUsageToInfluxdb(memory) ⇒
Promise.<void> Posts Butler SOS memory usage metrics to InfluxDB.
This function captures memory usage metrics from the Butler SOS process itself and stores them in InfluxDB. It handles both InfluxDB v1 and v2 formats.
- postUserEventToInfluxdb(msg) ⇒
Promise.<void> Posts a user event to InfluxDB.
- postLogEventToInfluxdb(msg)
Posts a log event to InfluxDB
- storeEventCountInfluxDB()
This function retrieves arrays of log and user events, and stores the data in InfluxDB. If the InfluxDB version is 1.x, it uses the v1 API to write data points for each event. If the InfluxDB version is 2.x, it uses the v2 API to write data points for each event. Static tags from the configuration file are added to each data point. The function logs messages at various stages to provide debugging and status information. No data is stored if there are no events present.
- storeRejectedEventCountInfluxDB()
This function reads an array of rejected log events from the
rejectedEventsobject, and stores the data in InfluxDB. The data is written to a measurement named after theButler-SOS.qlikSenseEvents.rejectedEventCount.influxdb.measurementNameconfig setting. The function uses the InfluxDB v1 or v2 API depending on theButler-SOS.influxdbConfig.versionconfig setting.- postHealthToMQTT(_host, serverName, body) ⇒
void Posts health metrics from Qlik Sense engine healthcheck API to MQTT.
This function publishes various metrics (memory usage, CPU usage, sessions, cache, etc.) to MQTT topics based on the configuration in Butler-SOS.mqttConfig.
- postUserSessionsToMQTT(host, virtualProxy, body) ⇒
void Posts user session information to MQTT.
This function publishes information about user sessions to MQTT topics based on the configuration in Butler-SOS.mqttConfig.
- postUserEventToMQTT(msg) ⇒
void Posts user events from Qlik Sense to MQTT.
This function processes user events (session start/stop, connection open/close) and publishes them to configured MQTT topics. It supports both general event topics and specific topics for different event types.
- postLogEventToMQTT(msg) ⇒
void Posts log events from Qlik Sense to MQTT.
This function processes log events from various Qlik Sense services and publishes them to configured MQTT topics. It supports both generic topics and specific topics for different log levels.
- getFormattedTime(serverStarted) ⇒
string Calculates and formats the uptime of a Qlik Sense engine.
This function takes the server start time from the engine healthcheck API and calculates how long the server has been running, returning a formatted string.
- postHealthMetricsToNewRelic(_host, body, tags) ⇒
Promise.<void> Posts health metrics data from Qlik Sense to New Relic.
This function processes health data from the Sense engine's healthcheck API and formats it for posting to New Relic. It handles various metrics including:
- CPU usage
- Memory usage
- Cache metrics
- Active/loaded/in-memory apps
- Session counts
- User counts
- postProxySessionsToNewRelic(userSessions) ⇒
Promise.<void> Posts user session metrics data from Qlik Sense to New Relic.
This function processes user session data from the Sense Proxy API and formats it for posting to New Relic. It includes session counts and attributes such as virtual proxy and host information.
- postButlerSOSUptimeToNewRelic(fields) ⇒
Promise.<void> Posts Butler SOS uptime data to New Relic.
This function processes memory usage data from Butler SOS and formats it for posting to New Relic.
- postUserEventToNewRelic(msg) ⇒
Promise.<void> Posts a user event to New Relic.
- sendNRLogEventYesNo(sourceService, sourceLogLevel) ⇒
boolean Checks if a log event from a given Qlik Sense service should be sent to New Relic.
This function checks the Butler SOS configuration to determine if a log event from a given Qlik Sense service should be sent to New Relic based on the log level and the service name.
- postLogEventToNewRelic(msg) ⇒
Promise.<void> Posts a log event to New Relic.
- setupPromClient(promServer, promPort, promHost) ⇒
Promise.<void> Sets up the Prometheus client and metrics endpoints.
This function initializes all Prometheus metrics gauges for Butler SOS and starts an HTTP server that exposes these metrics.
- saveHealthMetricsToPrometheus(host, data, labels) ⇒
void Stores health metrics data from Qlik Sense in Prometheus gauges.
This function takes the health data received from the Sense engine's health check API and populates the Prometheus gauges with appropriate values, including app metrics, cache metrics, CPU usage, memory usage, session counts, and user counts.
- saveUserSessionMetricsToPrometheus(userSessionsData) ⇒
void Stores user session metrics data in Prometheus gauges.
This function takes the user session data collected from Sense Proxy API and populates the Prometheus gauges with appropriate values.
- getCertificates(options) ⇒
object Loads TLS certificates from the filesystem based on the provided options.
- prepUserSessionMetrics(serverName, host, virtualProxy, body, tags) ⇒
Promise.<object> Prepares user session metrics data for storage/forwarding to various destinations.
This function processes raw session data from Qlik Sense and formats it into structures suitable for InfluxDB, Prometheus, and New Relic.
- getProxySessionStatsFromSense(serverName, host, virtualProxy, influxTags) ⇒
Promise.<void> Retrieves user session statistics from Qlik Sense Proxy Service.
This function makes an API call to the Qlik Sense Proxy API to get information about active user sessions. It then processes this data and sends it to configured destinations (MQTT, InfluxDB, New Relic, Prometheus).
- setupUserSessionsTimer() ⇒
void Sets up a timer to periodically retrieve user session information from Qlik Sense.
This function configures a periodic task that polls all configured Sense servers and their virtual proxies for user session information. The gathered data is then processed and sent to the configured destinations.
- getServerHeaders(server) ⇒
object|Array Extracts HTTP headers from a server configuration object.
This function processes a server configuration object and extracts any custom HTTP headers defined in the server's headers property. These headers can be used when making API requests to the server.
- getServerTags(logger, server) ⇒
object|Array Extracts tag values from a server configuration object.
This function processes a server configuration object and extracts tags that can be used to tag metrics in time series databases or monitoring systems. It always includes host, server_name, and server_description tags, plus any custom tags defined in the server's serverTags property.
- serviceUptimeStart() ⇒
void Starts monitoring and reporting of Butler SOS service uptime and memory usage.
This function sets up a timer to periodically log Butler SOS uptime and memory usage statistics. It also optionally sends this data to InfluxDB and/or New Relic for long-term storage and analysis. The function uses the frequency and log level settings from the Butler SOS config file.
Data tracked includes:
- Uptime duration (formatted as months, days, hours, minutes, seconds)
- Heap memory usage (used and total)
- External (off-heap) memory
- Total process memory allocation
- setupAnonUsageReportTimer([logger], [hostInfo]) ⇒
void Sets up a timer to periodically send anonymous usage telemetry.
This function initializes the PostHog client and configures a timer to send anonymous telemetry data every 12 hours. It also sends an initial telemetry report immediately upon setup.
- udpInitLogEventServer() ⇒
void Initializes the UDP server for handling Qlik Sense log events.
This function sets up event handlers for the UDP server that listens for log events from Qlik Sense services (such as engine, proxy, repository, and scheduler services).
- udpInitUserActivityServer() ⇒
void Initializes the UDP server for handling Qlik Sense user activity events.
This function sets up event handlers for the UDP server that listens for user activity events from Qlik Sense (such as session start/stop and connection open/close events).
- processAppSpecificFilters(eventData, appSpecificFilters) ⇒
boolean Processes filters for app-specific monitoring configuration
- processAllAppsFilters(eventData, allAppsFilters) ⇒
boolean Processes filters for all-apps monitoring configuration
- processObjectIdFilters(objectConfig, eventObjectId) ⇒
boolean Process object ID filters
- processMethodFilters(methodConfig, eventMethod) ⇒
boolean Process method filters
- processEngineEvent(msg) ⇒
Object Process engine log events
Message parts for log messages from engine service: 0: Message type. Always /qseow-engine/ 1: Row number 2: ISO8601 formatted timestamp. Example: 20211109T153726.028+0200 3: Local timezone timestamp. Example: 2021-11-09 15:37:26,028 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. 9: Proxy session ID (uuid) 10: QSEoW user directory associated with the event 11: QSEoW user id associated with the event 12: Engine timestamp (ISO8601 date) 13: Process ID (uuid) 14: Engine exe version 15: Server started (ISO8601 date) 16: Entry type 17: Session ID (uuid) 18: App ID (uuid)
- processProxyEvent(msg) ⇒
object Process proxy log events
Message parts for log messages from proxy service: 0: Message type. Always /qseow-proxy/ 1: Row number 2: ISO8601 formatted timestamp. Example: 20211109T153726.028+0200 3: Local timezone timestamp. Example: 2021-11-09 15:37:26,028 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: Service.Repository.Repository.Core.Status.ServiceStatusWorker 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. Ex: Method: 'SendRimQrsStatusRequest'. Failed to retrieve service status from 'http://pro2-win2.lab.ptarmiganlabs.net:4444/status/'. Server host 'pro2-win2.lab.ptarmiganlabs.net'. Error message: 'Unable to connect to the remote server' 9: Exception message. Empty unless an exception/fault occured in QSEoW. 10: QSEoW user directory associated with the event 11: QSEoW user id associated with the event 12: Command carried out when log event occured 13: Result code for command 14: Origin of log event 15: Context where the log event occured
- processQixPerfEvent(msg) ⇒
object|null Process QIX performance log events
Message parts for log messages with Qix performance information: 0: Message type. Always /qseow-qix-perf/ 1: Row number. Ex: 14 2: ISO8601 formatted timestamp. Example: 20211109T193744.331+0100 3: Local timezone timestamp. Example: 2021-11-09 19:37:44,331 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: System.Scheduler.Scheduler.Slave.Tasks.ReloadTask 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Proxy session ID. Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 9: User directory of the user associated with the event. Ex: LAB 10: User ID of the user associated with the event. Ex: goran 11: Engine timestamp. Example: 2021-11-09T19:37:44.331+01:00 12: Session ID. Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 13: Document ID (=app ID). Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 14: Request ID. Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 15: Method. Ex: Global::OpenApp, Doc::GetAppLayout, GenericObject::GetLayout 16: Process time in milliseconds. Ex: 123 17: Work time in milliseconds. Ex: 123 18: Lock time in milliseconds. Ex: 123 19: Validate time in milliseconds. Ex: 123 20: Traverse time in milliseconds. Ex: 123 21: Handle. Ex: -1, 123 22: Object ID. Ex: df68e14d-1ed0-47c9-bcb6-b37a900441d8, , rwPjBk 23: Net RAM. Ex: 123456 bytes 24: Peak RAM. Ex: 123456 byets 25: Object type. Ex: , AppPropsList, SheetList, StoryList, VariableList, linechart, barchart, map, listbox, CurrentSelection
- processRepositoryEvent(msg) ⇒
Object Process repository log events
Message parts for log messages from repository service: 0: Message type. Always /qseow-repository/ 1: Row number 2: ISO8601 formatted timestamp. Example: 20211109T153726.028+0200 3: Local timezone timestamp. Example: 2021-11-09 15:37:26,028 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: Service.Repository.Repository.Core.Status.ServiceStatusWorker 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. Ex: Method: 'SendRimQrsStatusRequest'. Failed to retrieve service status from 'http://pro2-win2.lab.ptarmiganlabs.net:4444/status/'. Server host 'pro2-win2.lab.ptarmiganlabs.net'. Error message: 'Unable to connect to the remote server' 9: Exception message. Empty unless an exception/fault occured in QSEoW. 10: QSEoW user directory associated with the event. Ex: INTERNAL 11: QSEoW user id associated with the event. Ex: System 12: Command carried out when log event occured. Ex: Check service status 13: Result code for command. Ex: 500 14: Origin of log event. Ex: Not available 15: Context where the log event occured. Ex: /qps/servicestatusworker
- processSchedulerEvent(msg) ⇒
object Process scheduler log events
Message parts for log messages from scheduler service: 0: Message type. Always /qseow-scheduler/ 1: Row number. Ex: 14 2: ISO8601 formatted timestamp. Example: 20211109T193744.331+0100 3: Local timezone timestamp. Example: 2021-11-09 19:37:44,331 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: System.Scheduler.Scheduler.Slave.Tasks.ReloadTask 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. Ex: Message from ReloadProvider: Reload failed in Engine. Check engine or script logs. 9: Exception message. Empty unless an exception/fault occured in QSEoW. 10: QSEoW user directory of the user associated with the event. Note: For some log events this field is empty. Field #14 is then populated instead. Ex: LAB 11: QSEoW user id of the user associated with the event. Note: For some log events this field is empty. Field #14 is then populated instead. Ex: goran 12: QSEoW directory and userID associated with the event. Note: For some log events this field is empty. Fields #12 and #13 are then populated instead. Ex: LAB\goran 13: Task name associated with the event. Ex: Manually triggered reload of Test failing reloads 2 14: App name associated with the event. Ex: Test failing reloads 2 15: Task ID associated with the event. Ex: dec2a02a-1680-44ef-8dc2-e2bfb180af87 16: App ID associated with the event. Ex: e7af59a0-c243-480d-9571-08727551a66f 17: Execution ID associated with the event. Ex: 4831c6a5-34f6-45bb-9d40-73a6e6992670
- listeningEventHandler(_message, _remote) ⇒
void Handler for UDP server startup event for log events.
This function is called when the UDP server for log events starts listening. It logs information about the server's address and port.
- messageEventHandler(message, _remote) ⇒
Promise.<void> Handler for UDP messages containing Qlik Sense log events.
This function processes incoming UDP messages from Qlik Sense Enterprise on Windows (QSEoW) log events. It supports different log sources:
- qseow-engine: Engine service logs
- qseow-proxy: Proxy service logs
- qseow-repository: Repository service logs
- qseow-scheduler: Scheduler service logs
- qseow-qix-perf: QIX performance logs
Each log event type is processed by a specialized handler function, then categorized (if enabled), and finally forwarded to configured destinations (MQTT, InfluxDB, New Relic).
- formatUserFields(msgObj) ⇒
void Formats and normalizes user directory and user ID fields in log events.
This function ensures consistent representation of user information across different log event sources by either combining separate user directory and ID fields into a full user name, or splitting a full user name into its component parts.
- listeningEventHandler(_message, _remote) ⇒
void Handler for UDP server startup event for user events.
This function is called when the UDP server for user events starts listening. It logs information about the server's address and port.
- messageEventHandler(message, _remote) ⇒
Promise.<void> Handler for UDP messages relating to user events from Qlik Sense Proxy service.
This function processes incoming UDP messages containing user activity information, parses the message format, extracts relevant information such as user, app, browser details, and forwards the processed data to configured destinations (MQTT, InfluxDB, New Relic).
Message format expected:
- Field 0: Message type (/qseow-proxy-connection/ or /qseow-proxy-session/)
- Field 1: Host
- Field 2: Command (Start session, Stop session, Open connection, Close connection)
- Field 3: User directory
- Field 4: User ID
- Field 5: Origin
- Field 6: Context
- Field 7: Message (may contain UserAgent information)
- setupUdpEventsStorage([callbackForTest]) ⇒
number|undefined Sets up periodic storage of UDP events statistics to InfluxDB.
This function creates a timer that periodically:
- Stores event counts (log and user events) to InfluxDB
- Stores rejected event counts to InfluxDB
- Clears event counters after they've been stored
import-meta-url
Utility module to provide a compatible import.meta.url equivalent in CommonJS modules.
This module creates a URL object that represents the current file's path, which can be used in a similar way to import.meta.url in ES modules. This is necessary for CommonJS modules that need file path resolution capabilities similar to those available in ES modules.
Settings
Kind: global class
- Settings
- new Settings()
- instance
- .init() ⇒
Object - .initInfluxDB()
- .initHostInfo() ⇒
Object|null
- .init() ⇒
- static
- .checkFileExistsSync(filepath) ⇒
boolean - .sleep(ms) ⇒
Promise - .isRunningInDocker() ⇒
boolean
- .checkFileExistsSync(filepath) ⇒
new Settings()
Creates a new Settings instance or returns the existing singleton instance. Implements the singleton pattern for global application settings.
settings.init() ⇒ Object
Initializes the Settings object with configuration from the environment and config files. Sets up logging, database connections, MQTT clients, and other application services.
Kind: instance method of Settings
Returns: Object - The singleton instance of the Settings class after initialization
settings.initInfluxDB()
Initializes the InfluxDB connection based on configuration settings. Sets up databases, retention policies, and write APIs depending on InfluxDB version.
Kind: instance method of Settings
settings.initHostInfo() ⇒ Object | null
Gathers and returns information about the host system where Butler SOS is running. Includes OS details, network info, hardware details, and a unique ID.
Kind: instance method of Settings
Returns: Object | null - Object containing host information or null if an error occurs
Settings.checkFileExistsSync(filepath) ⇒ boolean
Checks if a file exists at the specified file path.
Kind: static method of Settings
Returns: boolean - True if the file exists, false otherwise
| Param | Type | Description |
|---|---|---|
| filepath | string |
Path to the file to check |
Settings.sleep(ms) ⇒ Promise
Creates a Promise that resolves after a specified time in milliseconds. Used for implementing delays in asynchronous code.
Kind: static method of Settings
Returns: Promise - A promise that resolves after the specified delay
| Param | Type | Description |
|---|---|---|
| ms | number |
The number of milliseconds to sleep |
Settings.isRunningInDocker() ⇒ boolean
Detects if Butler SOS is running inside a Docker container.
Kind: static method of Settings
Returns: boolean - True if running in Docker, false otherwise
requestHealth
Creates and executes an HTTP request to check if the application is healthy. Used for Docker health checks to determine container health status. Exits with code 0 if health check succeeds, 1 otherwise.
confifgFileSchema : object
Schema definition for Butler SOS configuration file validation.
This schema is used with AJV (Another JSON Validator) to validate the structure and content of the Butler SOS YAML configuration file. It defines all possible configuration options, their data types, validation rules, and which options are required.
The schema includes validation for:
- General application settings (logging, telemetry, etc.)
- Server connection details
- Integration configurations (InfluxDB, MQTT, etc.)
- User event and log event handling
- Monitoring options and filters
- Prometheus metrics
- Third-party tool credentials
callRemoteURL ⇒ void
Sends anonymous telemetry data to PostHog.
This function collects information about the Butler SOS instance, its environment, and which features are enabled/disabled. This data helps the developers understand how Butler SOS is being used and prioritize development efforts accordingly.
The telemetry includes:
- System information (OS, architecture, Node.js version)
- Enabled/disabled features
- Configuration settings (without sensitive information)
- Whether the app is running in Docker
No personally identifiable information or sensitive configuration data is collected.
isoDateRegex : RegExp
Regular expression that matches ISO8601 date format strings. Matches patterns like "2021-11-09T15:37:26.028+0200".
uuidRegex : RegExp
Regular expression that matches UUID format strings. Matches standard UUID patterns like "550e8400-e29b-41d4-a716-446655440000".
sleep(ms) ⇒ Promise.<void>
Delays execution for the specified amount of time.
Kind: global function
Returns: Promise.<void> - A promise that resolves after the specified time has elapsed.
| Param | Type | Description |
|---|---|---|
| ms | number |
The number of milliseconds to sleep. |
mainScript() ⇒ Promise.<void>
Main application entry point that initializes and starts all Butler SOS services.
This function initializes globals, sets up logging, starts UDP servers for user events and log events, and initializes various metrics collection services based on configuration.
Kind: global function
Returns: Promise.<void> - A promise that resolves when initialization is complete.
mainScript~sleepLocal(ms) ⇒ Promise.<void>
Helper function for sleeping/delaying within the mainScript function.
Kind: inner method of mainScript
Returns: Promise.<void> - A promise that resolves after the specified time has elapsed.
| Param | Type | Description |
|---|---|---|
| ms | number |
The number of milliseconds to sleep. |
getAppNames() ⇒ void
Retrieves application names from the Qlik Repository Service (QRS) API.
This function connects to the Qlik Sense repository database and fetches information about all available applications. It stores the app information (id, name, description) in the global appNames variable for use throughout the Butler SOS application.
setupAppNamesExtractTimer() ⇒ void
Sets up a timer for periodically retrieving app names from the Qlik Repository Service.
This function initializes a timer that calls getAppNames() at regular intervals specified by the Butler-SOS.appNames.extractInterval configuration setting. This ensures that the Butler SOS application always has up-to-date information about Qlik Sense applications.
verifyConfigFileSchema(configFile) ⇒ Promise.<boolean>
Verifies that the config file has the correct format. Use yaml-validator to validate the config file
Kind: global function
Returns: Promise.<boolean> - true if the config file is valid, false otherwise
| Param | Type | Description |
|---|---|---|
| configFile | string |
path to the config file to verify |
verifyAppConfig(cfg) ⇒ Promise.<boolean>
Verifies application-specific settings and relationships between configuration settings.
This function performs validation beyond simple schema validation, checking:
- If InfluxDB is enabled, verifies that version is valid (must be 1 or 2)
- Validates server tag configuration:
- All tags defined in serverTagsDefinition must be set for each server
- All tags specified for each server must be present in serverTagsDefinition
Kind: global function
Returns: Promise.<boolean> - A promise that resolves to true if all checks pass, false otherwise
| Param | Type | Description |
|---|---|---|
| cfg | object |
The configuration object to verify |
configObfuscate(config) ⇒ object
Obfuscates sensitive information in the Butler SOS configuration object.
This function creates a copy of the configuration object and replaces sensitive information with masked strings to prevent leaking sensitive data when displaying the configuration through the web interface. It typically keeps a small prefix of the original value (e.g., first 3-10 characters) and replaces the rest with asterisks.
Obfuscated fields include:
- Server hostnames and IP addresses
- API keys and passwords
- Certificate paths and passphrases
- MQTT topics
- InfluxDB credentials and parameters
- Headers containing authentication information
- Application IDs and names
Kind: global function
Returns: object - A new configuration object with sensitive information masked
Throws:
ErrorIf there's an error during the obfuscation process
| Param | Type | Description |
|---|---|---|
| config | object |
The original configuration object to obfuscate |
setupConfigVisServer([logger], [config]) ⇒ Promise.<void>
Sets up and starts a web server for visualizing Butler SOS configuration.
This function creates a Fastify server that serves a web interface where users can view the current Butler SOS configuration in a more readable format. It includes:
- Rate limiting to prevent abuse
- Optional obfuscation of sensitive configuration values
- Serving static files for the web interface
- Rendering the configuration as both JSON and YAML
Kind: global function
Returns: Promise.<void> - A promise that resolves when the server is set up
Throws:
ErrorIf there's an error setting up the server
| Param | Type | Description |
|---|---|---|
| [logger] | object |
Optional logger object (not used in this function) |
| [config] | object |
Optional configuration object (not used in this function) |
getCertificates(options) ⇒ object
Loads TLS certificates from the filesystem based on the provided options.
Kind: global function
Returns: object - Object containing cert, key, and ca properties with certificate contents
| Param | Type | Description |
|---|---|---|
| options | object |
Certificate options |
| options.Certificate | string |
Path to the client certificate file |
| options.CertificateKey | string |
Path to the client certificate key file |
| options.CertificateCA | string |
Path to the certificate authority file |
| [options.CertificatePassphrase] | string |
Optional passphrase for the certificate |
getHealthStatsFromSense(serverName, host, tags, headers) ⇒ void
Retrieves health statistics from Qlik Sense server via the engine healthcheck API.
This function makes an HTTPS request to the Sense engine healthcheck API and distributes the data to configured destinations (MQTT, InfluxDB, New Relic, Prometheus).
Kind: global function
| Param | Type | Description |
|---|---|---|
| serverName | string |
The name of the server as defined in the config. |
| host | string |
The hostname or IP address of the Sense server. |
| tags | object |
Tags/metadata to associate with the server metrics. |
| headers | object | null |
Additional headers to include in the request. |
setupHealthMetricsTimer() ⇒ void
Sets up a timer that periodically collects health metrics from all configured Sense servers.
This function creates an interval that runs every pollingInterval milliseconds (as defined in config) and calls getHealthStatsFromSense for each server in the serverList global variable.
callRemoteURL(remoteURL, logger) ⇒ void
Sends a heartbeat GET request to a remote URL.
Kind: global function
| Param | Type | Description |
|---|---|---|
| remoteURL | string |
The URL to send the heartbeat request to |
| logger | object |
Logger object for logging success or errors |
setupHeartbeatTimer(config, logger) ⇒ void
Sets up a scheduled timer for sending heartbeat requests to a remote URL.
This function configures a scheduled timer based on the frequency specified in the configuration. It also performs an initial heartbeat request immediately.
Kind: global function
| Param | Type | Description |
|---|---|---|
| config | object |
Configuration object with heartbeat settings |
| logger | object |
Logger object for logging debug info and errors |
categoriseLogEvent(logLevel, logMessage) ⇒ object
Categorizes log events based on configured rules.
This function analyzes log events from Qlik Sense services and categorizes them based on matching rules defined in the configuration. Rules can match on log level and message content using different filters (starts with, ends with, contains). Rules can also specify if a matched log event should be dropped.
The function returns an object with two properties:
- category: An array of objects, each representing a category. Each category object has two properties: name and value.
- actionTaken: A string indicating the action taken on the log event. Possible values are 'categorised' and 'dropped'.
If no rule matches, then the function uses the default category (if enabled in the config file) and sets actionTaken to 'categorised'.
If an error occurs while processing the log event, then the function logs an error message and returns null.
Kind: global function
Returns: object - An object with category and actionTaken properties
| Param | Type | Description |
|---|---|---|
| logLevel | string |
The log level of the log event |
| logMessage | string |
The log message of the log event |
getFormattedTime(serverStarted) ⇒ string
Calculates and formats the uptime of a Qlik Sense engine.
This function takes the server start time from the engine healthcheck API and calculates how long the server has been running, returning a formatted string.
Kind: global function
Returns: string - A formatted string representing uptime (e.g. "5 days, 3h 45m 12s")
| Param | Type | Description |
|---|---|---|
| serverStarted | string |
The server start time in format "YYYYMMDDThhmmss" |
postHealthMetricsToInfluxdb(serverName, host, body, serverTags) ⇒ Promise.<void>
Posts health metrics data from Qlik Sense to InfluxDB.
This function processes health data from the Sense engine's healthcheck API and formats it for storage in InfluxDB. It handles various metrics including:
- CPU usage
- Memory usage
- Cache metrics
- Active/loaded/in-memory apps
- Session counts
- User counts
Kind: global function
Returns: Promise.<void> - Promise that resolves when data has been posted to InfluxDB
| Param | Type | Description |
|---|---|---|
| serverName | string |
The name of the Qlik Sense server |
| host | string |
The hostname or IP of the Qlik Sense server |
| body | object |
The health metrics data from Sense engine healthcheck API |
| serverTags | object |
Tags to associate with the metrics |
postHealthMetricsToInfluxdb~storeActivedDoc(docID) ⇒ Promise.<void>
Stores a document ID in either the sessionAppNamesActive or appNamesActive arrays
Kind: inner method of postHealthMetricsToInfluxdb
Returns: Promise.<void> - Promise that resolves when the document ID has been processed
| Param | Type | Description |
|---|---|---|
| docID | string |
The ID of the document |
storeLoadedDoc(docID) ⇒ Promise
Stores a loaded app name in memory.
Kind: global function
Returns: Promise - - Resolves when the docID has been stored.
| Param | Type | Description |
|---|---|---|
| docID | string |
The ID of the app to store. |
storeInMemoryDoc(docID) ⇒ Promise.<void>
Stores a document ID in either the sessionAppNamesInMemory or appNamesInMemory arrays.
Kind: global function
Returns: Promise.<void> - Promise that resolves when the document ID has been processed.
| Param | Type | Description |
|---|---|---|
| docID | string |
The ID of the document to store. |
postProxySessionsToInfluxdb(userSessions) ⇒ Promise.<void>
Posts proxy sessions data to InfluxDB.
This function takes user session data from Qlik Sense proxy and formats it for storage in InfluxDB. It handles different versions of InfluxDB (1.x and 2.x) and includes error handling with detailed logging.
Kind: global function
Returns: Promise.<void> - Promise that resolves when data has been posted to InfluxDB
| Param | Type | Description |
|---|---|---|
| userSessions | object |
User session data containing information about active sessions |
| userSessions.host | string |
The hostname of the server |
| userSessions.virtualProxy | string |
The virtual proxy name |
| userSessions.datapointInfluxdb | Array.<object> |
Data points formatted for InfluxDB |
| [userSessions.serverName] | string |
Server name (for InfluxDB v2) |
| [userSessions.sessionCount] | number |
Number of sessions |
| [userSessions.uniqueUserList] | Array.<string> |
List of unique users |
postButlerSOSMemoryUsageToInfluxdb(memory) ⇒ Promise.<void>
Posts Butler SOS memory usage metrics to InfluxDB.
This function captures memory usage metrics from the Butler SOS process itself and stores them in InfluxDB. It handles both InfluxDB v1 and v2 formats.
Kind: global function
Returns: Promise.<void> - Promise that resolves when data has been posted to InfluxDB
| Param | Type | Description |
|---|---|---|
| memory | object |
Memory usage data object |
| memory.instanceTag | string |
Instance identifier tag |
| memory.heapUsedMByte | number |
Heap used in MB |
| memory.heapTotalMByte | number |
Total heap size in MB |
| memory.externalMemoryMByte | number |
External memory usage in MB |
| memory.processMemoryMByte | number |
Process memory usage in MB |
postUserEventToInfluxdb(msg) ⇒ Promise.<void>
Posts a user event to InfluxDB.
Kind: global function
Returns: Promise.<void> - - A promise that resolves when the event has been posted to InfluxDB.
| Param | Type | Description |
|---|---|---|
| msg | object |
The event to be posted to InfluxDB. The object should contain the following properties: - host: The hostname of the Qlik Sense server that the user event originated from. - command: The command (e.g. OpenApp, CreateApp, etc.) that the user event corresponds to. - user_directory: The user directory of the user who triggered the event. - user_id: The user ID of the user who triggered the event. - origin: The origin of the event (e.g. Qlik Sense, QlikView, etc.). - appId: The ID of the app that the event corresponds to (if applicable). - appName: The name of the app that the event corresponds to (if applicable). - ua: An object containing user agent information (if available). The object should contain the following properties: - browser: An object containing information about the user's browser (if available). The object should contain the following properties: - name: The name of the browser. - major: The major version of the browser. - os: An object containing information about the user's OS (if available). The object should contain the following properties: - name: The name of the OS. - version: The version of the OS. |
postLogEventToInfluxdb(msg)
Posts a log event to InfluxDB
Kind: global function
| Param | Type | Description |
|---|---|---|
| msg | object |
Log event from Butler SOS |
storeEventCountInfluxDB()
This function retrieves arrays of log and user events, and stores the data in InfluxDB. If the InfluxDB version is 1.x, it uses the v1 API to write data points for each event. If the InfluxDB version is 2.x, it uses the v2 API to write data points for each event. Static tags from the configuration file are added to each data point. The function logs messages at various stages to provide debugging and status information. No data is stored if there are no events present.
Kind: global function
Throws:
ErrorLogs an error message if unable to write data to InfluxDB.
storeRejectedEventCountInfluxDB()
This function reads an array of rejected log events from the rejectedEvents object,
and stores the data in InfluxDB. The data is written to a measurement named after
the Butler-SOS.qlikSenseEvents.rejectedEventCount.influxdb.measurementName config setting.
The function uses the InfluxDB v1 or v2 API depending on the Butler-SOS.influxdbConfig.version
config setting.
Kind: global function
Throws:
ErrorError if unable to get write API or write data to InfluxDB
postHealthToMQTT(_host, serverName, body) ⇒ void
Posts health metrics from Qlik Sense engine healthcheck API to MQTT.
This function publishes various metrics (memory usage, CPU usage, sessions, cache, etc.) to MQTT topics based on the configuration in Butler-SOS.mqttConfig.
Kind: global function
| Param | Type | Description |
|---|---|---|
| _host | string |
The host name or IP (not used) |
| serverName | string |
The name of the server, used in MQTT topic path |
| body | object |
The health metrics data from Sense engine healthcheck API |
postUserSessionsToMQTT(host, virtualProxy, body) ⇒ void
Posts user session information to MQTT.
This function publishes information about user sessions to MQTT topics based on the configuration in Butler-SOS.mqttConfig.
Kind: global function
| Param | Type | Description |
|---|---|---|
| host | string |
The host name of the Qlik Sense server |
| virtualProxy | string |
The virtual proxy prefix |
| body | string |
JSON string containing user session information |
postUserEventToMQTT(msg) ⇒ void
Posts user events from Qlik Sense to MQTT.
This function processes user events (session start/stop, connection open/close) and publishes them to configured MQTT topics. It supports both general event topics and specific topics for different event types.
Kind: global function
| Param | Type | Description |
|---|---|---|
| msg | object |
The user event message object |
| msg.messageType | string |
The type of message |
| msg.host | string |
The host name of the Qlik Sense server |
| msg.command | string |
The command (Start session, Stop session, etc.) |
| msg.user_directory | string |
The user directory |
| msg.user_id | string |
The user ID |
| msg.origin | string |
The origin of the event |
| msg.context | string |
The context of the event |
| msg.message | string |
The message content |
| [msg.appId] | string |
Optional app ID |
| [msg.appName] | string |
Optional app name |
| [msg.ua] | object |
Optional user agent information |
postLogEventToMQTT(msg) ⇒ void
Posts log events from Qlik Sense to MQTT.
This function processes log events from various Qlik Sense services and publishes them to configured MQTT topics. It supports both generic topics and specific topics for different log levels.
Kind: global function
| Param | Type | Description |
|---|---|---|
| msg | object |
The log event message object |
| msg.source | string |
The source of the log event |
| msg.level | string |
The log level (e.g., ERROR, WARN, FATAL) |
| msg.message | string |
The log message content |
| [msg.timestamp] | string |
The timestamp of the log event |
| [msg.hostname] | string |
The hostname where the log event occurred |
getFormattedTime(serverStarted) ⇒ string
Calculates and formats the uptime of a Qlik Sense engine.
This function takes the server start time from the engine healthcheck API and calculates how long the server has been running, returning a formatted string.
Kind: global function
Returns: string - A formatted string representing uptime (e.g. "5 days, 3h 45m 12s")
| Param | Type | Description |
|---|---|---|
| serverStarted | string |
The server start time in format "YYYYMMDDThhmmss" |
postHealthMetricsToNewRelic(_host, body, tags) ⇒ Promise.<void>
Posts health metrics data from Qlik Sense to New Relic.
This function processes health data from the Sense engine's healthcheck API and formats it for posting to New Relic. It handles various metrics including:
- CPU usage
- Memory usage
- Cache metrics
- Active/loaded/in-memory apps
- Session counts
- User counts
Kind: global function
Returns: Promise.<void> - Promise that resolves when data has been posted to New Relic
| Param | Type | Description |
|---|---|---|
| _host | string |
The hostname or IP of the Qlik Sense server (unused parameter) |
| body | object |
The health metrics data from Sense engine healthcheck API |
| tags | object |
Tags to associate with the metrics |
postProxySessionsToNewRelic(userSessions) ⇒ Promise.<void>
Posts user session metrics data from Qlik Sense to New Relic.
This function processes user session data from the Sense Proxy API and formats it for posting to New Relic. It includes session counts and attributes such as virtual proxy and host information.
Kind: global function
Returns: Promise.<void> - Promise that resolves when data has been posted to New Relic
| Param | Type | Description |
|---|---|---|
| userSessions | object |
Object containing user session metrics data |
| userSessions.serverName | string |
Name of the server |
| userSessions.host | string |
Hostname of the server |
| userSessions.virtualProxy | string |
Virtual proxy prefix |
| userSessions.datapointNewRelic | object |
Data formatted for New Relic |
| userSessions.tags | object |
Tags associated with the metrics |
postButlerSOSUptimeToNewRelic(fields) ⇒ Promise.<void>
Posts Butler SOS uptime data to New Relic.
This function processes memory usage data from Butler SOS and formats it for posting to New Relic.
Kind: global function
Returns: Promise.<void> - Promise that resolves when data has been posted to New Relic
| Param | Type | Description |
|---|---|---|
| fields | object |
Fields to post to New Relic |
| fields.intervalMillisec | number |
Interval in milliseconds between posting data to New Relic |
| fields.heapUsed | number |
Used heap memory in bytes |
| fields.heapTotal | number |
Total heap memory in bytes |
| fields.externalMemory | number |
External memory usage in bytes |
| fields.processMemory | number |
Process memory usage in bytes |
| fields.uptimeMilliSec | number |
Uptime of Butler SOS in milliseconds |
postUserEventToNewRelic(msg) ⇒ Promise.<void>
Posts a user event to New Relic.
Kind: global function
Returns: Promise.<void> - Promise that resolves when data has been posted to New Relic
| Param | Type | Description |
|---|---|---|
| msg | object |
User event from Qlik Sense, Butler-SOS or other sources. |
sendNRLogEventYesNo(sourceService, sourceLogLevel) ⇒ boolean
Checks if a log event from a given Qlik Sense service should be sent to New Relic.
This function checks the Butler SOS configuration to determine if a log event from a given Qlik Sense service should be sent to New Relic based on the log level and the service name.
Kind: global function
Returns: boolean - True if the log event should be sent to New Relic, false otherwise
| Param | Type | Description |
|---|---|---|
| sourceService | string |
The name of the Qlik Sense service that generated the log event |
| sourceLogLevel | string |
The log level of the log event |
postLogEventToNewRelic(msg) ⇒ Promise.<void>
Posts a log event to New Relic.
Kind: global function
| Param | Type | Description |
|---|---|---|
| msg | object |
Log event from Qlik Sense, Butler-SOS or other sources. |
setupPromClient(promServer, promPort, promHost) ⇒ Promise.<void>
Sets up the Prometheus client and metrics endpoints.
This function initializes all Prometheus metrics gauges for Butler SOS and starts an HTTP server that exposes these metrics.
Kind: global function
Returns: Promise.<void> - A promise that resolves when the setup is complete
| Param | Type | Description |
|---|---|---|
| promServer | object |
The Fastify server instance for the metrics endpoint |
| promPort | number |
The port number for the metrics endpoint |
| promHost | string |
The host to bind the metrics endpoint to |
saveHealthMetricsToPrometheus(host, data, labels) ⇒ void
Stores health metrics data from Qlik Sense in Prometheus gauges.
This function takes the health data received from the Sense engine's health check API and populates the Prometheus gauges with appropriate values, including app metrics, cache metrics, CPU usage, memory usage, session counts, and user counts.
Kind: global function
| Param | Type | Description |
|---|---|---|
| host | string |
The hostname or IP address of the Sense server |
| data | object |
The health metrics data from Sense engine healthcheck API |
| labels | object |
Labels to associate with the metrics |
saveUserSessionMetricsToPrometheus(userSessionsData) ⇒ void
Stores user session metrics data in Prometheus gauges.
This function takes the user session data collected from Sense Proxy API and populates the Prometheus gauges with appropriate values.
Kind: global function
| Param | Type | Description |
|---|---|---|
| userSessionsData | object |
Object containing user session metrics |
| userSessionsData.host | string |
The hostname of the Sense server |
| userSessionsData.virtualProxy | string |
The virtual proxy name |
| userSessionsData.datapointPrometheus | object |
The metrics data formatted for Prometheus |
| userSessionsData.tags | object |
Tags to associate with the metrics |
getCertificates(options) ⇒ object
Loads TLS certificates from the filesystem based on the provided options.
Kind: global function
Returns: object - Object containing cert, key, and ca properties with certificate contents
| Param | Type | Description |
|---|---|---|
| options | object |
Certificate options |
| options.Certificate | string |
Path to the client certificate file |
| options.CertificateKey | string |
Path to the client certificate key file |
| options.CertificateCA | string |
Path to the certificate authority file |
prepUserSessionMetrics(serverName, host, virtualProxy, body, tags) ⇒ Promise.<object>
Prepares user session metrics data for storage/forwarding to various destinations.
This function processes raw session data from Qlik Sense and formats it into structures suitable for InfluxDB, Prometheus, and New Relic.
Kind: global function
Returns: Promise.<object> - Promise resolving to an object containing formatted metrics data
| Param | Type | Description |
|---|---|---|
| serverName | string |
Name of the server |
| host | string |
Host name or IP of the server |
| virtualProxy | string |
Virtual proxy prefix |
| body | Array |
Array of session objects from Qlik Sense |
| tags | object |
Tags to associate with the metrics |
getProxySessionStatsFromSense(serverName, host, virtualProxy, influxTags) ⇒ Promise.<void>
Retrieves user session statistics from Qlik Sense Proxy Service.
This function makes an API call to the Qlik Sense Proxy API to get information about active user sessions. It then processes this data and sends it to configured destinations (MQTT, InfluxDB, New Relic, Prometheus).
Kind: global function
Returns: Promise.<void> - Promise that resolves when the operation is complete
| Param | Type | Description |
|---|---|---|
| serverName | string |
Name of the Qlik Sense server |
| host | string |
Host name or IP of the Qlik Sense server |
| virtualProxy | string |
Virtual proxy prefix |
| influxTags | object |
Tags to associate with metrics in InfluxDB |
setupUserSessionsTimer() ⇒ void
Sets up a timer to periodically retrieve user session information from Qlik Sense.
This function configures a periodic task that polls all configured Sense servers and their virtual proxies for user session information. The gathered data is then processed and sent to the configured destinations.
getServerHeaders(server) ⇒ object | Array
Extracts HTTP headers from a server configuration object.
This function processes a server configuration object and extracts any custom HTTP headers defined in the server's headers property. These headers can be used when making API requests to the server.
Kind: global function
Returns: object | Array - Object with all headers if successful, empty array on error
| Param | Type | Description |
|---|---|---|
| server | object |
Server configuration object |
| server.serverName | string |
Name of the server |
| [server.headers] | object |
Optional HTTP headers to use with this server |
getServerTags(logger, server) ⇒ object | Array
Extracts tag values from a server configuration object.
This function processes a server configuration object and extracts tags that can be used to tag metrics in time series databases or monitoring systems. It always includes host, server_name, and server_description tags, plus any custom tags defined in the server's serverTags property.
Kind: global function
Returns: object | Array - Object with all tags if successful, empty array on error
| Param | Type | Description |
|---|---|---|
| logger | object |
Logger object for logging debug and error information |
| server | object |
Server configuration object |
| server.host | string |
Hostname of the server (may include port) |
| server.serverName | string |
Name of the server |
| server.serverDescription | string |
Description of the server |
| [server.serverTags] | object |
Optional additional tags for the server |
serviceUptimeStart() ⇒ void
Starts monitoring and reporting of Butler SOS service uptime and memory usage.
This function sets up a timer to periodically log Butler SOS uptime and memory usage statistics. It also optionally sends this data to InfluxDB and/or New Relic for long-term storage and analysis. The function uses the frequency and log level settings from the Butler SOS config file.
Data tracked includes:
- Uptime duration (formatted as months, days, hours, minutes, seconds)
- Heap memory usage (used and total)
- External (off-heap) memory
- Total process memory allocation
setupAnonUsageReportTimer([logger], [hostInfo]) ⇒ void
Sets up a timer to periodically send anonymous usage telemetry.
This function initializes the PostHog client and configures a timer to send anonymous telemetry data every 12 hours. It also sends an initial telemetry report immediately upon setup.
Kind: global function
| Param | Type | Description |
|---|---|---|
| [logger] | object |
Optional logger object (not used in the function) |
| [hostInfo] | object |
Optional host information (not used in the function) |
udpInitLogEventServer() ⇒ void
Initializes the UDP server for handling Qlik Sense log events.
This function sets up event handlers for the UDP server that listens for log events from Qlik Sense services (such as engine, proxy, repository, and scheduler services).
udpInitUserActivityServer() ⇒ void
Initializes the UDP server for handling Qlik Sense user activity events.
This function sets up event handlers for the UDP server that listens for user activity events from Qlik Sense (such as session start/stop and connection open/close events).
processAppSpecificFilters(eventData, appSpecificFilters) ⇒ boolean
Processes filters for app-specific monitoring configuration
Kind: global function
Returns: boolean - True if the event matches app-specific filters
| Param | Type | Description |
|---|---|---|
| eventData | object |
The event data |
| appSpecificFilters | Array |
The app specific filter configuration |
processAllAppsFilters(eventData, allAppsFilters) ⇒ boolean
Processes filters for all-apps monitoring configuration
Kind: global function
Returns: boolean - True if the event matches all-apps filters
| Param | Type | Description |
|---|---|---|
| eventData | object |
The event data |
| allAppsFilters | Object |
The all-apps filter configuration |
processObjectIdFilters(objectConfig, eventObjectId) ⇒ boolean
Process object ID filters
Kind: global function
Returns: boolean - True if the event passes the filter
| Param | Type | Description |
|---|---|---|
| objectConfig | object |
The object filter configuration |
| eventObjectId | string |
The object ID from the event |
processMethodFilters(methodConfig, eventMethod) ⇒ boolean
Process method filters
Kind: global function
Returns: boolean - True if the event passes the filter
| Param | Type | Description |
|---|---|---|
| methodConfig | object |
The method filter configuration |
| eventMethod | string |
The method from the event |
processEngineEvent(msg) ⇒ Object
Process engine log events
Message parts for log messages from engine service: 0: Message type. Always /qseow-engine/ 1: Row number 2: ISO8601 formatted timestamp. Example: 20211109T153726.028+0200 3: Local timezone timestamp. Example: 2021-11-09 15:37:26,028 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. 9: Proxy session ID (uuid) 10: QSEoW user directory associated with the event 11: QSEoW user id associated with the event 12: Engine timestamp (ISO8601 date) 13: Process ID (uuid) 14: Engine exe version 15: Server started (ISO8601 date) 16: Entry type 17: Session ID (uuid) 18: App ID (uuid)
Kind: global function
Returns: Object - Processed message object
| Param | Type | Description |
|---|---|---|
| msg | Array |
The message parts |
processProxyEvent(msg) ⇒ object
Process proxy log events
Message parts for log messages from proxy service: 0: Message type. Always /qseow-proxy/ 1: Row number 2: ISO8601 formatted timestamp. Example: 20211109T153726.028+0200 3: Local timezone timestamp. Example: 2021-11-09 15:37:26,028 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: Service.Repository.Repository.Core.Status.ServiceStatusWorker 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. Ex: Method: 'SendRimQrsStatusRequest'. Failed to retrieve service status from 'http://pro2-win2.lab.ptarmiganlabs.net:4444/status/'. Server host 'pro2-win2.lab.ptarmiganlabs.net'. Error message: 'Unable to connect to the remote server' 9: Exception message. Empty unless an exception/fault occured in QSEoW. 10: QSEoW user directory associated with the event 11: QSEoW user id associated with the event 12: Command carried out when log event occured 13: Result code for command 14: Origin of log event 15: Context where the log event occured
Kind: global function
Returns: object - Processed message object
| Param | Type | Description |
|---|---|---|
| msg | Array |
The message parts |
processQixPerfEvent(msg) ⇒ object | null
Process QIX performance log events
Message parts for log messages with Qix performance information: 0: Message type. Always /qseow-qix-perf/ 1: Row number. Ex: 14 2: ISO8601 formatted timestamp. Example: 20211109T193744.331+0100 3: Local timezone timestamp. Example: 2021-11-09 19:37:44,331 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: System.Scheduler.Scheduler.Slave.Tasks.ReloadTask 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Proxy session ID. Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 9: User directory of the user associated with the event. Ex: LAB 10: User ID of the user associated with the event. Ex: goran 11: Engine timestamp. Example: 2021-11-09T19:37:44.331+01:00 12: Session ID. Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 13: Document ID (=app ID). Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 14: Request ID. Ex: 3b3b3b3b-3b3b-3b3b-3b3b-3b3b3b3b3b3b 15: Method. Ex: Global::OpenApp, Doc::GetAppLayout, GenericObject::GetLayout 16: Process time in milliseconds. Ex: 123 17: Work time in milliseconds. Ex: 123 18: Lock time in milliseconds. Ex: 123 19: Validate time in milliseconds. Ex: 123 20: Traverse time in milliseconds. Ex: 123 21: Handle. Ex: -1, 123 22: Object ID. Ex: df68e14d-1ed0-47c9-bcb6-b37a900441d8, , rwPjBk 23: Net RAM. Ex: 123456 bytes 24: Peak RAM. Ex: 123456 byets 25: Object type. Ex: , AppPropsList, SheetList, StoryList, VariableList, linechart, barchart, map, listbox, CurrentSelection
Kind: global function
Returns: object | null - Processed message object or null if event should be skipped
| Param | Type | Description |
|---|---|---|
| msg | Array |
The message parts |
processRepositoryEvent(msg) ⇒ Object
Process repository log events
Message parts for log messages from repository service: 0: Message type. Always /qseow-repository/ 1: Row number 2: ISO8601 formatted timestamp. Example: 20211109T153726.028+0200 3: Local timezone timestamp. Example: 2021-11-09 15:37:26,028 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: Service.Repository.Repository.Core.Status.ServiceStatusWorker 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. Ex: Method: 'SendRimQrsStatusRequest'. Failed to retrieve service status from 'http://pro2-win2.lab.ptarmiganlabs.net:4444/status/'. Server host 'pro2-win2.lab.ptarmiganlabs.net'. Error message: 'Unable to connect to the remote server' 9: Exception message. Empty unless an exception/fault occured in QSEoW. 10: QSEoW user directory associated with the event. Ex: INTERNAL 11: QSEoW user id associated with the event. Ex: System 12: Command carried out when log event occured. Ex: Check service status 13: Result code for command. Ex: 500 14: Origin of log event. Ex: Not available 15: Context where the log event occured. Ex: /qps/servicestatusworker
Kind: global function
Returns: Object - Processed message object
| Param | Type | Description |
|---|---|---|
| msg | Array |
The message parts |
processSchedulerEvent(msg) ⇒ object
Process scheduler log events
Message parts for log messages from scheduler service: 0: Message type. Always /qseow-scheduler/ 1: Row number. Ex: 14 2: ISO8601 formatted timestamp. Example: 20211109T193744.331+0100 3: Local timezone timestamp. Example: 2021-11-09 19:37:44,331 4: Log level. Possible values are: WARN, ERROR, FATAL 5: Hostname where the log event occured 6: QSEoW subsystem where log event occured. Example: System.Scheduler.Scheduler.Slave.Tasks.ReloadTask 7: Windows username running the originating QSEoW service. Ex: COMPANYNAME\qlikservice 8: Message. Can contain single quotes and semicolon - handle with care. Ex: Message from ReloadProvider: Reload failed in Engine. Check engine or script logs. 9: Exception message. Empty unless an exception/fault occured in QSEoW. 10: QSEoW user directory of the user associated with the event. Note: For some log events this field is empty. Field #14 is then populated instead. Ex: LAB 11: QSEoW user id of the user associated with the event. Note: For some log events this field is empty. Field #14 is then populated instead. Ex: goran 12: QSEoW directory and userID associated with the event. Note: For some log events this field is empty. Fields #12 and #13 are then populated instead. Ex: LAB\goran 13: Task name associated with the event. Ex: Manually triggered reload of Test failing reloads 2 14: App name associated with the event. Ex: Test failing reloads 2 15: Task ID associated with the event. Ex: dec2a02a-1680-44ef-8dc2-e2bfb180af87 16: App ID associated with the event. Ex: e7af59a0-c243-480d-9571-08727551a66f 17: Execution ID associated with the event. Ex: 4831c6a5-34f6-45bb-9d40-73a6e6992670
Kind: global function
Returns: object - Processed message object
| Param | Type | Description |
|---|---|---|
| msg | Array |
The message parts |
listeningEventHandler(_message, _remote) ⇒ void
Handler for UDP server startup event for log events.
This function is called when the UDP server for log events starts listening. It logs information about the server's address and port.
Kind: global function
| Param | Type | Description |
|---|---|---|
| _message | * |
The message received (unused in this handler) |
| _remote | * |
Information about the remote sender (unused in this handler) |
messageEventHandler(message, _remote) ⇒ Promise.<void>
Handler for UDP messages containing Qlik Sense log events.
This function processes incoming UDP messages from Qlik Sense Enterprise on Windows (QSEoW) log events. It supports different log sources:
- qseow-engine: Engine service logs
- qseow-proxy: Proxy service logs
- qseow-repository: Repository service logs
- qseow-scheduler: Scheduler service logs
- qseow-qix-perf: QIX performance logs
Each log event type is processed by a specialized handler function, then categorized (if enabled), and finally forwarded to configured destinations (MQTT, InfluxDB, New Relic).
Kind: global function
Returns: Promise.<void> - A promise that resolves when processing is complete
| Param | Type | Description |
|---|---|---|
| message | Buffer |
The raw UDP message buffer containing the log event |
| _remote | object |
Information about the remote sender (unused in this handler) |
formatUserFields(msgObj) ⇒ void
Formats and normalizes user directory and user ID fields in log events.
This function ensures consistent representation of user information across different log event sources by either combining separate user directory and ID fields into a full user name, or splitting a full user name into its component parts.
Kind: global function
Returns: void - - The function updates the provided object directly
| Param | Type | Description |
|---|---|---|
| msgObj | object |
The message object to update |
| [msgObj.user_directory] | string |
The user directory component |
| [msgObj.user_id] | string |
The user ID component |
| [msgObj.user_full] | string |
The combined user name in "directory\id" format |
listeningEventHandler(_message, _remote) ⇒ void
Handler for UDP server startup event for user events.
This function is called when the UDP server for user events starts listening. It logs information about the server's address and port.
Kind: global function
| Param | Type | Description |
|---|---|---|
| _message | * |
The message received (unused in this handler) |
| _remote | * |
Information about the remote sender (unused in this handler) |
messageEventHandler(message, _remote) ⇒ Promise.<void>
Handler for UDP messages relating to user events from Qlik Sense Proxy service.
This function processes incoming UDP messages containing user activity information, parses the message format, extracts relevant information such as user, app, browser details, and forwards the processed data to configured destinations (MQTT, InfluxDB, New Relic).
Message format expected:
- Field 0: Message type (/qseow-proxy-connection/ or /qseow-proxy-session/)
- Field 1: Host
- Field 2: Command (Start session, Stop session, Open connection, Close connection)
- Field 3: User directory
- Field 4: User ID
- Field 5: Origin
- Field 6: Context
- Field 7: Message (may contain UserAgent information)
Kind: global function
Returns: Promise.<void> - A promise that resolves when processing is complete
| Param | Type | Description |
|---|---|---|
| message | Buffer |
The raw UDP message buffer |
| _remote | object |
Information about the remote sender (unused) |
setupUdpEventsStorage([callbackForTest]) ⇒ number | undefined
Sets up periodic storage of UDP events statistics to InfluxDB.
This function creates a timer that periodically:
- Stores event counts (log and user events) to InfluxDB
- Stores rejected event counts to InfluxDB
- Clears event counters after they've been stored
Kind: global function
Returns: number | undefined - The interval ID if the timer was set up, or undefined if disabled
| Param | Type | Description |
|---|---|---|
| [callbackForTest] | function |
Optional callback function used for testing |