Define agent reporting rules

Reporting rules define how long an agent can go without sending a heartbeat before Telegraf Controller changes its status to Not Reporting. They can also automatically delete agents that haven’t reported in a specified amount of time.

Telegraf Controller requires exactly one default reporting rule. Newly created agents are automatically assigned to the current default reporting rule. On first run, Telegraf Controller creates a default rule with a one-hour not reporting threshold and auto-delete turned off.

Manage reporting rules in the Reporting Rules section of Controller, then assign them to agents from either the agent list or an agent details page.

• How reporting rules work
• Create a reporting rule
• Update a reporting rule
• Delete a reporting rule
• Set a default reporting rule
  • From the reporting rules list
  • From reporting rule details
• Assign a reporting rule to agents
  • From the agent list
  • From an agent details page
• Run a status check

How reporting rules work

A reporting rule has two thresholds, both measured from the agent’s last heartbeat:

• Not reporting threshold: how long an agent can go without a heartbeat before Telegraf Controller marks it Not Reporting.
• Auto-delete threshold (optional): how much longer a Not Reporting agent is kept. Telegraf Controller deletes the agent once its last heartbeat is older than the two thresholds combined.

Telegraf Controller evaluates every rule once a minute. An agent that resumes sending heartbeats returns to its reported status on the next evaluation.

Thresholds are stored as whole seconds from 1 to 2147483647. The web interface accepts durations such as 12h, 7d, or 3h 30m and converts them. The API rejects any other value, including 0, with 400 Bad Request.

Create a reporting rule

1. In Telegraf Controller, go to Reporting Rules.
2. Select Add Rule.
3. Enter the following:
   • Description: Reporting rule description
   • Not Reporting Threshold: The maximum time an agent can go without reporting before Controller assigns the “Not Reporting” status, as a duration such as 12h or 7d.
   • Auto-delete agents: Enable to automatically delete agents that haven’t reported in the defined Auto-delete threshold, counted from the end of the not reporting threshold.
   • Default Rule: Enable to make the rule the default reporting rule. The previous default rule stops being the default.
4. Save the rule.

Update a reporting rule

1. In Reporting Rules, click the More button () of the rule you want to update.
2. Select Edit.
3. Edit the description, not reporting threshold, auto-delete settings, or make the rule the default reporting rule.
4. Save your changes.

Delete a reporting rule

1. In Reporting Rules, click the More button () of the rule you want to delete.
2. Select Delete and confirm.

Set a default reporting rule

Exactly one rule is the default at any time. Making another rule the default moves the default to that rule in one step. You cannot turn Default Rule off on the current default rule; make another rule the default instead. Changing the default does not reassign agents that already have a rule; only agents registered after the change receive the new default.

From the reporting rules list

1. In Reporting Rules, click the More button () of the rule you want to make the default.
2. Select Make Default.

From reporting rule details

1. In Reporting Rules, click the More button () of the rule you want to make the default.
2. Select Edit.
3. Toggle Default Rule to true.
4. Save your changes.

Assign a reporting rule to agents

From the agent list

1. In Agents, select one or more agents.
2. Select Assign Rule.
3. Choose a rule and assign it.

From an agent details page

1. In Agents, click the More button () for an agent and select View Details.
2. In the Reporting Rule section, select Change.
3. Choose a rule and apply it.

Run a status check

Telegraf Controller evaluates reporting rules once a minute. To evaluate them immediately, for example after changing a threshold, select Run status check on the Reporting Rules page.

The same check is available from the API as POST /api/agents/status-check, which requires the agents:write permission.