Documentation

Create custom checks

In the UI, you can create two kinds of checks: threshold and deadman.

Using a Flux task, you can create a custom check that provides a couple advantages:

  • Customize and transform the data you would like to use for the check.
  • Set up custom criteria for your alert (other than threshold and deadman).

Create a task

  1. In the InfluxDB UI, select Tasks in the navigation menu on the left.

  2. Click Create Task.

  3. In the Name field, enter a descriptive name, and then enter how often to run the task in the Every field (for example, 10m). For more detail, such as using cron syntax or including an offset, see Task configuration options.

  4. Enter the Flux script for your custom check, including the monitor.check function.

Use the /api/v2/checks/{checkID}/query API endpoint to see the Flux code for a check built in the UI. This can be useful for constructing custom checks.

Example: Monitor failed tasks

The script below is fairly complex, and can be used as a framework for similar tasks. It does the following:

  • Import the necessary influxdata/influxdb/monitor package, and other packages for data processing.
  • Query the _tasks bucket to retrieve all statuses generated by your check.
  • Set the _level to alert on, for example, crit, warn, info, or ok.
  • Create a check object that specifies an ID, name, and type for the check.
  • Define the ok and crit statuses.
  • Execute the monitor function on the check using the task_data.

Example alert task script

import "strings"
import "regexp"
import "influxdata/influxdb/monitor"
import "influxdata/influxdb/schema"

option task = {name: "Failed Tasks Check", every: 1h, offset: 4m}

task_data = from(bucket: "_tasks")
    |> range(start: -task.every)
    |> filter(fn: (r) => r["_measurement"] == "runs")
    |> filter(fn: (r) => r["_field"] == "logs")
    |> map(fn: (r) => ({r with name: strings.split(v: regexp.findString(r: /option task = \{([^\}]+)/, v: r._value), t: "\\\\\\\"")[1]}))
    |> drop(columns: ["_value", "_start", "_stop"])
    |> group(columns: ["name", "taskID", "status", "_measurement"])
    |> map(fn: (r) => ({r with _value: if r.status == "failed" then 1 else 0}))
    |> last()

check = {
    // 16 characters, alphanumeric
    _check_id: "0000000000000001",
    // Name string
    _check_name: "Failed Tasks Check",
    // Check type (threshold, deadman, or custom)
    _type: "custom",
    tags: {},
}
ok = (r) => r["logs"] == 0
crit = (r) => r["logs"] == 1
messageFn = (r) => "The task: ${r.taskID} - ${r.name} has a status of ${r.status}"

task_data
    |> schema["fieldsAsCols"]()
    |> monitor["check"](data: check, messageFn: messageFn, ok: ok, crit: crit)

Creating a custom check does not send a notification email. For information on how to create notification emails, see Create notification endpoints, Create notification rules, and Send alert email


Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

InfluxDB Cloud powered by TSM