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.

    Tasks

  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

  1. import "strings"
  2. import "regexp"
  3. import "influxdata/influxdb/monitor"
  4. import "influxdata/influxdb/schema"
  6. option task = {name: "Failed Tasks Check", every: 1h, offset: 4m}
  8. task_data = from(bucket: "_tasks")
  9.     |> range(start: -task.every)
  10.     |> filter(fn: (r) => r["_measurement"] == "runs")
  11.     |> filter(fn: (r) => r["_field"] == "logs")
  12.     |> map(fn: (r) => ({r with name: strings.split(v: regexp.findString(r: /option task = \{([^\}]+)/, v: r._value), t: "\\\\\\\"")[1]}))
  13.     |> drop(columns: ["_value", "_start", "_stop"])
  14.     |> group(columns: ["name", "taskID", "status", "_measurement"])
  15.     |> map(fn: (r) => ({r with _value: if r.status == "failed" then 1 else 0}))
  16.     |> last()
  18. check = {
  19.     // 16 characters, alphanumeric
  20.     _check_id: "0000000000000001",
  21.     // Name string
  22.     _check_name: "Failed Tasks Check",
  23.     // Check type (threshold, deadman, or custom)
  24.     _type: "custom",
  25.     tags: {},
  26. }
  27. ok = (r) => r["logs"] == 0
  28. crit = (r) => r["logs"] == 1
  29. messageFn = (r) => "The task: ${r.taskID} - ${r.name} has a status of ${r.status}"
  31. task_data
  32.     |> schema["fieldsAsCols"]()
  33.     |> 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

alerts checks tasks Flux