1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
# Ouroboros metrics
A collection of observability tools for exporting and
visualising metrics collected from Ouroboros.
The exporter pushes metrics to InfluxDB or writes them as InfluxDB
line protocol to a local file, and provides additional visualization
via grafana.
## Requirements:
The influxdb-client Python package is required in both modes. It is
installed automatically via `pip install .`
InfluxDB OSS 2.0, https://docs.influxdata.com/influxdb/v2.0/
(only required when pushing metrics directly to InfluxDB, not
needed for file mode)
## Optional requirements:
Grafana, https://grafana.com/
## Setup
Install and run InfluxDB and create a bucket in influxDB for exporting
Ouroboros metrics, and a token for writing to that bucket. Consult the
InfluxDB documentation on how to do this,
https://docs.influxdata.com/influxdb/v2.0/get-started/#set-up-influxdb.
To use grafana, install and run grafana open source,
https://grafana.com/grafana/download
https://grafana.com/docs/grafana/latest/?pg=graf-resources&plcmt=get-started
Go to the grafana UI (usually http://localhost:3000) and set up
InfluxDB as your datasource:
Go to Configuration -> Datasources -> Add datasource and select InfluxDB
Set "flux" as the Query Language, and
under "InfluxDB Details" set your Organization as in InfluxDB and set
the copy/paste the token for the bucket to the Token field.
To add the Ouroboros dashboard,
select Dashboards -> Manage -> Import
and then either upload the json file from this repository in
dashboards/general.json
or copy the contents of that file to the "Import via panel json"
textbox and click "Load".
## Run the exporter:
Clone this repository.
Create and activate a virtual environment and install the dependencies:
```
python -m venv venv
source venv/bin/activate
pip install .
```
### InfluxDB mode (default)
Edit the config.ini.example file and fill out the InfluxDB
information (token, org). Save it as config.ini.
Run oexport:
```
oexport
```
Extra tags can be added to every metric:
```
oexport --tag env=production --tag region=eu
```
### File mode
Write metrics as InfluxDB line protocol to a local file, without
pushing to a running InfluxDB instance. This requires no InfluxDB
connection and no config.ini:
```
oexport --output-file metrics.lp
```
Tags can be injected in file mode as well:
```
oexport --output-file metrics.lp \
--tag test=oping_unimpaired \
--tag run=20260401_143022
```
The resulting file can be bulk-imported into InfluxDB later:
```
influx write --bucket ouroboros-metrics --file metrics.lp
```
### CLI options
| Flag | Description |
|---------------------|-------------------------------------------------|
| `-i, --interval` | FRCT interval, ms (default: 1000) |
| `--slow-interval` | IPCP/LSDB/DHT/FA/DT interval, ms |
| `-b, --bucket` | InfluxDB bucket (default: ouroboros-metrics) |
| `-o, --output-file` | Write InfluxDB line protocol to a file |
| `-t, --tag` | Extra tag as key=value (repeatable) |
| `-c, --config` | Path to config.ini (default: ./config.ini) |
| `--url` | InfluxDB server URL |
| `--org` | InfluxDB organization |
| `--token` | InfluxDB authentication token |
### Config file
All settings can also be specified in config.ini. CLI flags take
precedence over config file values. See config.ini.example for
details.
| Section | Key | Equivalent CLI flag |
|--------------|------------|---------------------|
| `[influx2]` | `url` | `--url` |
| `[influx2]` | `org` | `--org` |
| `[influx2]` | `token` | `--token` |
| `[exporter]` | `interval` | `--interval` |
| `[exporter]` | `bucket` | `--bucket` |
| `[output]` | `file` | `--output-file` |
| `[output]` | `tags` | `--tag` |
|
