<commit_before># Agents

Each agent is configured to collect and report a specific set of metrics. Each
agent has a configuration section that defines its type, path, collection
interval, whether it's enabled or not, and various other settings. This document
lists the types of agents available, what metrics they collect, and how to
configure them.

### Common configuration

```json
{
    "type": <the agent type string>,
    "path": <relative or absolute '.' separated path>,
    "interval": <the number of seconds between collections>,
    "enabled": <whether this agent is enabled or not>,
    "settings": <settings structure if required>
}
```

The `type` parameter is the name of the agent type such as `"cpu"`, `"mem"`, etc.

The `path` parameter is either an absolute path, such as `"my.cpu.agent"`, or a relative
path like `".sub.agent"` which will be combined with the base path in the main configuration
(if no basepath is available, the configuration will fail validation). All metrics generated
by this agent will have this path as a prefix.

The `interval` parameter is a numeric number of seconds. It can have decimals. It
may not be <= 0.

The `enabled` parameter is pretty straightforward. If true, the agent will collect
and report metrics.

## `cmd` Agent

The `cmd` agent allows the user to write their own agents in the form of other
scripts and binaries that can be called on the machine. This makes up for the
fact that we cant load client collectors like Diamond does.

For each line in the stdout that contains a relative or absolute metric path
followed by a numeric value, a metric will be generated.

For example:

```
this.line.will -123.125125
.relative.path.example 0
This line won't generate a value
```

The `cmd` agent is the only agent allowed to post metrics with absolute path
names.

## `cpu` Agent

The `cpu` agent simply returns the cpu usage percentage across all of the
individual cores.

For example on a 4 core machine this will generate:

```
.0.cpu_percentage -> 0-100%
.1.cpu_percentage -> 0-100%
.2.cpu_percentage -> 0-100%
.3.cpu_percentage -> 0-100%
```

## `disk` Agent

The `disk` agent provides usage metrics about partitions and IO counter metrics
about physical disks.

TODO add more here

## `mem` Agent

TODO add more here

## `meta` Agent

The `meta` agent reports the share of cpu that the Spoon process is using as well
as the RSS (resident set size) of memory allocated to it.

## `net` Agent

TODO add more here

## `time` Agent

The `time` agent can be used as a testing metric, or when collected between
a large range of machines, can help to reveal NTP issues. It simply returns the
current unix time as number of nanoseconds since January 1, 1970 UTC.

## `uptime` Agent

The `uptime` agent reports the uptime of the machine in seconds.
<commit_msg>small doc adjustments<commit_after># Agents

Each agent is configured to collect and report a specific set of metrics. Each
agent has a configuration section that defines its type, path, collection
interval, whether it's enabled or not, and various other settings. This document
lists the types of agents available, what metrics they collect, and how to
configure them.

### Common configuration

```
{
    "type": <the agent type string>,
    "path": <relative or absolute '.' separated path>,
    "interval": <the number of seconds between collections>,
    "enabled": <whether this agent is enabled or not>,
    "settings": <settings structure if required>
}
```

The `type` parameter is the name of the agent type such as `"cpu"`, `"mem"`, etc.

The `path` parameter is either an absolute path, such as `"my.cpu.agent"`, or a relative
path like `".sub.agent"` which will be combined with the base path in the main configuration
(if no basepath is available, the configuration will fail validation). All metrics generated
by this agent will have this path as a prefix.

The `interval` parameter is a numeric number of seconds. It can have decimals. It
may not be <= 0.

The `enabled` parameter is pretty straightforward. If true, the agent will collect
and report metrics.

The `settings` parameter is only optionally needed for some agents. For all
others it is ignored and can be left out.

## `cmd` Agent

The `cmd` agent allows the user to write their own agents in the form of other
scripts and binaries that can be called on the machine. This makes up for the
fact that we cant load client collectors like Diamond does.

For each line in the stdout that contains a relative or absolute metric path
followed by a numeric value, a metric will be generated.

For example:

```
this.line.will -123.125125
.relative.path.example 0
This line won't generate a value
```

The `cmd` agent is the only agent allowed to post metrics with absolute path
names without being influenced by the base path or agent path.

## `cpu` Agent

The `cpu` agent simply returns the cpu usage percentage across all of the
individual cores.

For example on a 4 core machine this will generate:

```
.0.cpu_percentage -> 0-100%
.1.cpu_percentage -> 0-100%
.2.cpu_percentage -> 0-100%
.3.cpu_percentage -> 0-100%
```

## `disk` Agent

The `disk` agent provides usage metrics about partitions and IO counter metrics
about physical disks.

TODO add more here

## `mem` Agent

TODO add more here

## `meta` Agent

The `meta` agent reports the share of cpu that the Spoon process is using as well
as the RSS (resident set size) of memory allocated to it.

## `net` Agent

TODO add more here

## `time` Agent

The `time` agent can be used as a testing metric, or when collected between
a large range of machines, can help to reveal NTP issues. It simply returns the
current unix time as number of nanoseconds since January 1, 1970 UTC.

## `uptime` Agent

The `uptime` agent reports the uptime of the machine in seconds.

{'fraction_non_alphanumeric': 0.073309241094476, 'fraction_numerical': 0.012734469110308037, 'mean_word_length': 4.058311575282855, 'pattern_counts': {'":': 10, '<': 15, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1144466', 'n_tokens_mistral': 1646, 'n_tokens_neox': 1543, 'n_words': 902}