mirror of
https://github.com/ClusterCockpit/cc-specifications.git
synced 2025-03-15 03:15:55 +01:00
134 lines
4.6 KiB
Markdown
134 lines
4.6 KiB
Markdown
# InfluxData line-protocol flavor
|
|
|
|
## Overview
|
|
|
|
ClusterCockpit uses the
|
|
[InfluxData line-protocol](https://docs.influxdata.com/influxdb/v2.1/reference/syntax/line-protocol/)
|
|
for transferring messages between its components. The line-protocol is a
|
|
text-based representation of a metric/event with a value, time and describing
|
|
tags. All metrics/events have the following format (if written to `stdout`):
|
|
|
|
```txt
|
|
<measurement>,<tag set> <field set> <timestamp>
|
|
```
|
|
|
|
Where `<tag set>` and `<field set>` are comma-separated lists of `key=value`
|
|
entries. In a mind-model, think about tags as `indices` in the database for
|
|
faster lookup and the `<field set>` as values.
|
|
|
|
We are using the tag set to add metadata information and the field for the
|
|
payload.
|
|
|
|
**Remark**: In the first iteration, we only sent metrics (number values) but we
|
|
extended the specification to messages with different purposes. The below
|
|
text was changed accordingly. The update is backward-compatible, for metrics
|
|
(number values), nothing has changed.
|
|
|
|
## Message categories
|
|
|
|
There exist the following line line-protocol message flavors:
|
|
|
|
- Metric: The field key is `value`, measurement = metric name
|
|
- Event: The field key is `event`, Events are actionable informations, measurement = event subtype (job, phases, ?? ), Additional tag function=<string>
|
|
- Log message: The field key is `log`. Log messages are purely informational,
|
|
measurement = [ccb, ccms, ccmc, ccem, ccnc], Additional tag loglevel
|
|
- Control message: The field key is `control`, measurement = knob name (rapl, freq, prefetcher, topology, config), Additional tags: method=[get,put]
|
|
|
|
## Messaging
|
|
|
|
ClusterCockpit uses the NATS messaging network, with the option to support other
|
|
messaging frameworks in the future. To distinguish between different message
|
|
types and easily filter the types an application is interested in the following
|
|
subject hierarchy tree is used:
|
|
|
|
```txt
|
|
<cluster name>. |
|
|
--- metrics
|
|
|
|
|
--- events.[job]
|
|
|
|
|
--- log.[ccb, ccms, ccmc, ccem, ccnc]
|
|
|
|
|
--- control.[get,put]
|
|
```
|
|
|
|
## Points generic for all message categories
|
|
|
|
In ClusterCockpit we limit the flexibility of the InfluxData line-protocol
|
|
slightly. The idea is to keep the format usable by different components.
|
|
|
|
Each message is identifiable by the `measurement` (= metric name), the
|
|
`hostname`, the `type` and, if required, a `type-id`.
|
|
|
|
### Mandatory tags per message
|
|
|
|
- `hostname`
|
|
- `type`
|
|
- `node`
|
|
- `socket`
|
|
- `die`
|
|
- `memoryDomain`
|
|
- `llc`
|
|
- `core`
|
|
- `hwthread`
|
|
- `accelerator`
|
|
- `type-id` for further specifying the type like CPU socket or HW Thread identifier
|
|
|
|
Although no `type-id` is required if `type=node`, it is recommended to send `type=node,type-id=0`.
|
|
|
|
#### Optional tags depending on the message
|
|
|
|
In some cases, optional tags are required like `filesystem`, `device` or
|
|
`version`. While you are free to do that, the ClusterCockpit components in the
|
|
stack above will recognize `stype` (= "sub type") and `stype-id`. So
|
|
`filesystem=/homes` should be better specified as
|
|
`stype=filesystem,stype-id=/homes`.
|
|
|
|
### Message types
|
|
|
|
There exist different message types in the ClusterCockpit ecosystem, all
|
|
specified using the InfluxData line-protocol.
|
|
|
|
#### Metrics
|
|
|
|
**Identification:** `value=X` field with `X` being a number
|
|
|
|
While the measurements (metric names) can be chosen freely, there is a basic set
|
|
of measurements which should be present as long as you navigate in the
|
|
ClusterCockpit ecosystem
|
|
|
|
- `flops_sp`: Single-precision floating point rate in `Flops/s`
|
|
- `flops_dp`: Double-precision floating point rate in `Flops/s`
|
|
- `flops_any`: Combined floating point rate in `Flops/s` (often `(flops_dp * 2) + flops_sp`)
|
|
- `cpu_load`: The 1m load of the system (see `/proc/loadavg`)
|
|
- `mem_used`: The amount of memory used by applications (see `/proc/meminfo`)
|
|
- `ipc`: instructions-per-cycle metric
|
|
- `mem_bw`: Main memory bandwidth (read and write) in `MByte/s`
|
|
- `cpu_power`: Power consumption of the whole CPU package
|
|
- `mem_power`: Power consumption of the memory subsystem
|
|
- `clock`: CPU clock in `MHz`
|
|
- ...
|
|
|
|
For the whole list, see [job-data schema](../../datastructures/job-data.schema.json)
|
|
|
|
#### Events
|
|
|
|
**Identification:** `event="X"` field with `"X"` being a string
|
|
The name (measurement) of the event message can further specialize the purpose
|
|
(similar to REST endpoints), e.g. `start_job`, and `stop_job` for events of type
|
|
job.
|
|
|
|
Example start job event:
|
|
TBD
|
|
|
|
#### Controls
|
|
|
|
**Identification:**
|
|
|
|
- `control="X"` field with `"X"` being a string
|
|
- `method` tag is either `GET` or `PUT`
|
|
|
|
#### Logs
|
|
|
|
**Identification:** `log="X"` field with `"X"` being a string
|