Custom trends management

Custom trends extend the standard Nexthink data model, allowing you to save a daily snapshot of the existing data and observe its evolution over time, for up to 13 months.

You can configure up to 200 custom trends.

Accessing the Custom trends page

Select Administration from the main menu.
Click on Custom trends in the Content management section of the navigation panel.

Managing custom trends

The custom trends administration page displays the list of custom trends that have already been defined.

View the total number of custom trends located on the top-left side of the table.
Search for the custom trend by name using a search box located on the top-right side of the page to narrow down the listed results.

Using the custom trend action menu

Hover over a three vertical dot icon of the custom trend to reveal the action menu with the following options:

Edit: View details of the custom trend configuration and change the name, description and the NQL query.
Edit tags: Add or remove the associated tags.
Export: Download and save the custom trend in JSON format.
Delete: Remove the custom trend.

Importing custom trends

Click on Import in the top-right corner of the page.
Choose the JSON file of the custom trend you want to import from your device.

All imported items will be categorized as custom content.

Tagging custom trends

Tagging allows you to efficiently organize custom trends, facilitating quick and easy navigation through your data. Filter the table by typing or selecting Tags from the right-side panel.

To assign, remove or edit tags:

Hover over a custom trend to display the action menu on the right side of the table.
Click Edit tags to open the Tags pop-up.
Type in a new tag name or choose an existing one to add it to the custom trend.
Open the tag’s action menu to remove the tag from the custom trend or change the tag color. Deleting a tag only removes it from the associated custom trend.

Creating a custom trend

To create a new custom trend:

Click on the New custom trend button in the top-right corner of the Custom trend page.
Enter the Name and Description on the custom trend configuration page.
If needed, adjust the Query ID, the unique identifier for NQL.
Enter an optional Description to help others understand the meaning and purpose of this trend data.
Write the NQL query the Nexthink platform executes during the daily snapshot evaluation.

Remember that once you have saved the custom trend, you can no longer change the NQL query and the Query ID value.

Writing NQL queries for custom trends

While writing the query, follow the rules below:

The query must target the devices namespace.
The time interval allowed for devices is during the past 1d. Omit this time interval to target all devices registered in the system.
The query must have a maximum of two include clauses and two compute clauses.
The only time interval allowed after the include clauses is during past 1d.
Nexthink allows the where clause only when followed by conditions on device properties.
The query cannot include personally identifiable information (PII), such as the device name, employee email address, and others.
The query must end with a list clause including a maximum of two metrics (numbers) and a maximum of 5 properties (strings or enums).
The system does not allow the sort, limit, summarize, countif(), sumif(), or with clauses.

The system includes by default some device properties when evaluating the daily snapshots and stores them as part of the context of the device. These include:

operating system platform
operating system name
location (country, state, location type)
organization (entity, custom organization)

Understanding devices included in custom trend data

In the definition of the custom trend you can specify the set of devices based on their activity.

To save snapshots with all the devices registered in the system (which are all the devices that were active in the last 30 days, see Data resolution and retention), omit the time selection for the devices table in the definition of the custom trend.

CODE

devices
| include … during past 1d 
| compute … 
| list …

To save snapshots with the devices that were active during the day the snapshot was taken add during past 1d after devices in the definition of the custom trend.

CODE

devices during past 1d
| include … during past 1d 
| compute … 
| list ….

When you haven’t specified the timeframe for the devices, you may expect slight discrepancies in the results when comparing trend data with operational data from the same period.

Accepting data retention

Select the Data retention checkbox to acknowledge that this trend data will be saved in the system for a period of 13 months.
Click on the Save button to save your new custom trend.

Using custom trends

After saving the custom trend, you can query the new trend data with NQL. Initially, it yields 0 entries until the system saves the first snapshot during the night. Snapshots include events occurring from midnight of the preceding day to midnight of the computation day.

Here is an example of an NQL query used in a custom trend definition:

CODE

devices 
| include execution.crashes past 1d 
| compute nb_crashes = number_of_crashes.sum() 
| list nb_crashes , hardware.manufacturer

The custom trends table looks as follows:

Bucket start	Context	Metric	Property
19/01/2024 00:00:00 AM	context information for device 1	nb_crashes for device 1	hardware_manufacturer for device 1
19/01/2024 00:00:00 AM	context information for device 2	nb_crashes for device 2	hardware_manufacturer for device 2
19/01/2024 00:00:00 AM	context information for device 3	nb_crashes for device 3	hardware_manufacturer for device 3
19/01/2024 00:00:00 AM		….
20/01/2024 00:00:00 AM	context information for device 1	nb_crashes for device 1	hardware_manufacturer for device 1
20/01/2024 00:00:00 AM	context information for device 2	nb_crashes for device 2	hardware_manufacturer for device 2
20/01/2024 00:00:00 AM	context information for device 3	nb_crashes for device 3	hardware_manufacturer for device 3
20/01/2024 00:00:00 AM		…

You can query custom trend data in Investigations or create a dashboard widget to monitor the trend on a timeline. The syntax to retrieve custom trend data is as follows:

CODE

custom_trend.<NQL ID>.snapshots ...
...

When configuring a widget, use the NQL ID of an existing custom trend to visually represent the evolution over time of a specific metric.

Line chart configuration using a custom trend

Optimizing the use of Custom trends

To effectively utilize custom trends, it is essential to understand that plotting trend data involves a two-step process: Custom trend configuration and dashboard design (Refer to Managing Live Dashboards for detailed instructions).

It is important to note that you do not necessarily need to create a custom trend for every metric you wish to track. A single custom trend serves as an extension to the NQL data model, allowing you to query long-term data with various combinations of metrics and aggregations.

Consider the following recommendations regarding Custom trends configuration and retrieval:

Apply filters and aggregations at retrieval when possible

We recommend filtering data and applying aggregation on devices during retrieval rather than in the trend definition.

Let’s consider an example where you want to plot the trend line for the number of devices experiencing crashes per hardware manufacturer. There are several strategies possible, but not all of them are optimal.

Suboptimal strategy

A suboptimal strategy would involve creating multiple custom trend definitions, one for each hardware provider, with aggregation on the devices. The following query returns a list of devices indicating 0 when no crashes occurred on a particular device and 1 if at least one crash occurred.

CODE

devices
| where hardware.manufacturer == "my_provider1"
| include execution.crashes past 1d
| compute nb_devices = device.count()
| list nb_devices

When retrieving the custom trend data, no filters are required.

CODE

custom_trend.#name.snapshots during past 300d
| summarize my_provider1_with_crashes = nb_devices.sum() by 1d

Optimal strategy

In the optimal strategy, create one custom trend definition, snapshotting the number of crashes as a metric and the hardware manufacturer as a property:

CODE

devices
| include execution.crashes past 1d
| compute nb_crashes = number_of_crashes.sum()
| list nb_crashes , hardware.manufacturer

When retrieving the custom trend data:

Filter devices with at least one crash and relevant hardware provider:

CODE

custom_trend.#name.snapshots during past 300d
| where nb_crashes > 0
| where hardware_manufacturer == "my_provider1"
| summarize my_provider1_with_crashes = count() by 1d

Alternatively, use conditional aggregation to summarize only devices with at least one crash and add additional grouping by hardware provider:

CODE

custom_trend.#execution_crashes.snapshots during past 300d
| summarize
fraction_with_crashes_per_manifacturer = countif(nb_crashes > 0) / count()
by 1d, hardware_manufacturer

Use double aggregations thoughtfully

Custom trends enable you to incorporate aggregations within your custom trend definition. You can also perform additional aggregations on trend data during retrieval. It is important to note, however, that snapshots lose the information about the aggregation that was used in the definition (with the exception when using count() on the unique objects, such as users).

Let’s consider the following example. The NQL in the custom trend definition creates a snapshot that includes the average boot duration for each device during a given day.

CODE

devices during past 1d
| include device_performance.boots during past 1d
| compute boot_duration = duration.avg()

When retrieving the data you may compute the average of your daily snapshot across all devices.

CODE

custom_trend.#name.snapshots
| summarize c1 = boot_duration.avg() by 1d

In this case, the result returned by the avg() aggregation will simply be the sum of the average values for each device, divided by the number of devices with a boot.

Use device.count() instead of metrics with Boolean values

Trends do not support metrics with a Boolean data type. For example, the following trend definition would generate an error upon saving the custom trend:

CODE

devices during past 1d
| include execution.crashes during past 1d
| compute has_crash_on_start = crash_on_start.last()
| list has_crash_on_start

To monitor a Boolean metric, filter for the true values and create a metric with device.count(). This custom trend would save '1' for the true values and '0' for the false values.

CODE

devices during past 1d
| include execution.crashes during past 1d
| where crash_on_start == true
| compute crash_on_start_count = device.count()
| list crash_on_start_count

Refer to Custom trends NQL examples to see more use cases.

Permissions

You can create custom trends in the Nexthink web interface if your user profile has the Manage all custom trend data permission enabled. Refer to the Profiles documentation for more information.