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.

Custom trends installed from Library

Nexthink offers a set of preconfigured custom trends that you can manually install from Nexthink Library. Go to the Nexthink Library module within your Nexthink instance to install, manage, and update predefined custom trends.

Refer to Nexthink Library documentation for more information.

New custom trends

Creating a custom trend from scratch lets you view desired data according to your needs and use cases.

Refer to Creating a custom trend for more information.

Accessing the Custom trends page

1. Select Administration from the main menu.

2. 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.

• Manage 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

To import custom trends—in JSON—from your local device:

1. Click the Import button in the top-right corner of the Administration > Custom trends page.

2. Choose or drag multiple JSON files from your hard drive to import them into the system.

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.

Open the Tags right-side panel to:

• Search for a specific tag at the top of the panel.

• Select one or more tags to filter the custom trends table.

To add one or more tags to custom trends, from the Administration > Custom trends page:

1. Hover over a custom trend to display the action menu and choose Manage tags.

2. From the Manage tags pop-up you can:

   • Type in a new tag or choose an existing one to add it to the custom trend.

   • Open the action menu of a specific tag item to Delete tag or change the tag color.

     • Deleting a tag only removes it from the custom trend it is associated with.

3. Alternatively, select multiple custom trends to Manage tags in bulks.

Creating a custom trend

To create a new custom trend:

1. Click on the New custom trend button in the top-right corner of the Custom trend page.

2. Enter the Name and Description on the custom trend configuration page.

3. If needed, adjust the Query ID, the unique identifier for NQL.

4. Enter an optional Description to help others understand the meaning and purpose of this trend data.

5. 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 for event collections is during the past 1d. You can include object collections without specifying any time interval.

• Nexthink does not allow the where clause when applied to the result of a compute clause.

• 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, enums or booleans).

• The system does not allow the as(), sort, limit, summarize, countif(), sumif(), or with keywords.

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.

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.

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 a custom trend, you can query the new trend data with NQL. Initially, the query only returns data from the three days prior to the day the custom trend definition was saved. This allows you to verify if the custom trend you configured returns the data in the expected format.

The initial data computed from the three previous days, will only include the device context information from the current day.

The system saves additional snapshots nightly. Snapshots include events occurring from midnight of the preceding day to midnight of the computation day, in the customer timezone.

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

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

Saving metrics and properties in the trend using the | list clause creates a new field within the custom trend table. The system constructs the new field name by following the rules below:

Field used in custom trend definition query	Field name in custom trend table	Rule description
nb_crashes	nb_crashes	Custom metrics from the query, such as nb_crashes in the example above, remain unchanged.
hardware.manufacturer	hardware_manufacturer	Periods . are replaced with underscores _.
device.#custom_field	device__custom_field	Non-leading hashes # are replaced with underscores _.
#custom_field	#custom_field	Leading hashes # remain in the custom trend field name.
device.last_seen.time_elapsed()	device_last_seen_time_elapsed	Function brackets () are omitted.

In the example above, using hardware.manufacturer field from the devices table in a | list clause of a custom trend definition creates a new field named hardware_manufacturer in the custom trend table.

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:

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.

Trend associations

Trend tables are associated with devices table. When retrieving trend data, you can utilize these association to include the device properties in your query. However, these properties will be only available as long as they are stored in the original table. Refer to Data resolution and retention page for more information.

While custom trend fields, such as hardware_manufacturer, have a retention spanning up to 13 months, the properties of the associated devices are available as long as the device is registered in the system. If you delete or anonymize the device or if the device has been inactive for over 30 days, the query will return "-" since the device properties are not saved directly in the trend. This does not apply to the device context information that custom trends save by default which is also retained for 13 months (see Writing NQL queries for custom trends on this page).

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.

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.

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:

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:

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:

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.

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.

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.

Troubleshooting snapshot failures

Investigating custom trend logs

Snapshot computations may fail for various reasons—for example, if the custom trend NQL query definition is incorrect due to changes in the dynamic data model, such as custom fields or organization structure, or if the system experienced a temporary failure. Failures may result in incomplete custom trend data. Understanding these failures is crucial for quickly resolving issues and creating visibility into possible problems with the data displayed on the dashboards.

The system saves each custom trend computation with details such as computation time, status and custom trend NQL ID in the platform.custom_trends_logs table. Use the following NQL query to investigate the cause of specific custom trend computation failures:

platform.custom_trends_logs during past 30d
| where status = failure
| where details.nql_id ="#my_custom_trend_ID"
| list custom_trends_log.time, 
       custom_trends_log.status, 
       details.description, 
       details.n_retries, 
       details.nql_id

Nexthink recommends configuring a monitor that detects all custom trend failures to help you stay informed and react quickly. Use the following monitor NQL query and settings:

platform.custom_trends_logs during past 24h
| where status = failure
| summarize failing_computations = count() by details.nql_id

Refer to the Creating custom monitors page for more information.

Trend backfill

Nexthink uses a mechanism to prevent custom trend data gaps caused by unforeseen technical breakdowns. If the system fails to compute and save the snapshot from a particular day, during the next daily computation, it attempts to compute the missing data before computing the current snapshot. The mechanism can restore data from up to the past three days, giving you additional time to address the issue and maintain trend continuity on your dashboard.

The data computed from the previous days, will only include the device context information from the current day.

Permissions

• You can create custom trends in the Nexthink web interface if your user role has the Manage all custom trend data permission enabled.

• You can access the platform.custom_trends_logs table if your user role has the View platform logs in NQL permission enabled.

Refer to the Roles documentation for more information.