Skip to content

Commit 11e1377

Browse files
awegrzynawegrzyn
authored
Improved README file
* README: formatting * improved README * README: flume added * README: typos corrections
1 parent ccd5853 commit 11e1377

File tree

1 file changed

+57
-63
lines changed

1 file changed

+57
-63
lines changed

‎README.md‎

Lines changed: 57 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
11
# Monitoring
2-
3-
Monitoring module allows to:
4-
+ inject user specific metrics
5-
+ monitor process itself (cpu / memory)
2+
Monitoring module allows to inject user defined metrics and monitor the process itself. It supports multiple backends, protocols and data formats.
63

74
## aliBuild installation
8-
If you don't have [aliBuild](https://alisw.github.io/alibuild/)
5+
Install [aliBuild](https://alisw.github.io/alibuild/) first.
96
~~~
107
pip install alibuild
118
~~~
12-
And then
9+
Then follow instructions below.
1310
~~~
1411
aliBuild init Monitoring@master
1512
aliDoctor Monitoring
@@ -32,8 +29,10 @@ make -j
3229
make install
3330
~~~
3431

32+
See [README](https://github.com/AliceO2Group/Configuration#manual-installation) if you're missing any Configuration dependencies.
33+
3534
### libcurl (optional)
36-
It should be present in your system or available in package manager, otherwise see: https://curl.haxx.se/download.html
35+
It should be present in your system or available in package manager, otherwise go to [curl download page](see: https://curl.haxx.se/download.html).
3736

3837
### ApMon (optional)
3938
~~~
@@ -62,71 +61,68 @@ Metrics consist of 4 parameters: name, value, timestamp and tags.I
6261
| timestamp | chrono::time_point<std::chrono::system_clock> | no | current timestamp |
6362
| tags | vector<Tag> | no | -** |
6463

65-
**Default tag set is generated per process and its attached to each metric:
64+
**Default tag set is process specific and included in each metric:
6665
+ hostname
6766
+ PID
6867
+ process name
6968

70-
See how backends handle tags in *Monitoring backends* section.
69+
See how backends handle tags in [Monitoring backends](#monitoring-backends) section.
7170

7271
## Creating monitring instance
73-
The most recommended way of getting (reference to) monitoring instance is via *MonitoringFactory*.
74-
Before using the factory Configure method must be call providing path to cofiguration file/backend. It should be called only once per process (following calls will not have any effect).
72+
1. The recommended way of getting (reference to) monitoring instance is via *MonitoringFactory*.
73+
Before using the factory *Configure* method must be called providing URI to configuration file or backend. It should be called only once per process (following calls will not have any effect).
7574
```cpp
7675
AliceO2::Monitoring::MonitoringFactory::Configure("file://../Monitoring/examples/SampleConfig.ini");
7776
AliceO2::Monitoring::MonitoringFactory::Get();
7877
```
7978
80-
The second way is getting dedicated instance. It should be used only when different configuration path needs to be passed within the same process.
79+
2. A second way allows to create dedicated monitoring instance. It's useful only when different configuration URI is needed within the same process.
8180
```cpp
8281
Monitoring::Create("file://../Monitoring/examples/SampleConfig.ini");
8382
```
8483

85-
See *Getting started* before writting any code.
86-
87-
## Sending metric
84+
## Sending a metric
8885
Metric can be sent by one of following ways:
89-
+ By creating and moving metric object:
90-
+ *send(Metric&& metric)*.
91-
In addition there are two methods that can be invoked on Metric object:
92-
+ *addTags(std::vector&lt;Tag&gt;&& tags)*
93-
+ *setTimestamp(std::chrono::time_point&lt;std::chrono::system_clock&gt;& timestamp)*
94-
+ By providing all required metric parameters (name and value):
95-
+ *send(T value, std::string name)*
96-
In addition there are two suplementary methods that can be chained:
97-
+ *sendTagged(T value, std::string name, std::vector&lt;Tag&gt;&& tags)*
98-
+ *sendTimed(T value, std::string name, std::chrono::time_point&lt;std::chrono::system_clock&gt;& timestamp)*
99-
100-
See *Getting started* section to learn usage.
86+
1. By creating and moving metric object:
87+
+ `send(Metric&& metric)`
88+
89+
In addition, two additional methods can be chained:
90+
+ `addTags(std::vector<Tag>&& tags)`
91+
+ `setTimestamp(std::chrono::time_point<std::chrono::system_clock>& timestamp)`
92+
93+
2. By providing metric parameters:
94+
+ `send(T value, std::string name)`
95+
+ `sendTagged(T value, std::string name, std::vector<Tag>&& tags)`
96+
+ `sendTimed(T value, std::string name, std::chrono::time_point<std::chrono::system_clock>& timestamp)`
97+
98+
See [Getting started](#getting-started) section to learn more.
10199

102100
## Derived metrics
103-
Library can calculate Derived metrics - use *addDerivedMetric(std::string name, DerivedMetricMode mode)* with one of two available modes:
104-
+ *DerivedMetricMode::RATE* - rate between two following metrics;
105-
+ *DerivedMetricMode::AVERAGE* - average value of all metrics stored in cache;
101+
The module can also calculate derived metrics. To do so, use `addDerivedMetric(std::string name, DerivedMetricMode mode)` with one of two available modes:
102+
+ `DerivedMetricMode::RATE` - rate between two following metrics;
103+
+ `DerivedMetricMode::AVERAGE` - average value of all metrics stored in cache;
106104

107-
Derived metrics are generated as new value arrives.
108-
Derived metric will have suffix added to its name.
105+
Derived metrics are generated each time as new value is passed to the module. Their names are suffixed with derived mode.
109106

110107
## Processes monitoring
111-
To enable process monitoring *ProcessMonitor.enable* flag in configuration file must be set to 1 (see section Configuration file).
112-
The following metrics are generated every N seconds (N can be specified in the config - *ProcessMonitor.interval*):
113-
1. etime - elapsed time since the process was started, in the form [[DD-]hh:]mm:ss
114-
2. pcpu - cpu utilization of the process in "##.#" format. Currently, it is the CPU time used divided by the time the process has been running (cputime/realtime ratio), expressed as a percentage. It will not add up to 100% unless you are lucky
115-
3. pmem - ratio of the process's resident set size to the physical memory on the machine, expressed as a percentage
116-
4. bytesReceived - the total number of bytes of data received by the process (per interface)
117-
5. bytesTransmitted - the total number of bytes of data transmitted by the process (per interface)
108+
To enable process monitoring *ProcessMonitor.enable* flag in configuration file must be set to 1 - see [Configuration file](#configuration-file) section. The following metrics are generated every N seconds (N can be specified in the config - *ProcessMonitor.interval*):
109+
+ **etime** - elapsed time since the process was started, in the form [[DD-]hh:]mm:ss
110+
+ **pcpu** - cpu utilization of the process in "##.#" format. Currently, it is the CPU time used divided by the time the process has been running (cputime/realtime ratio), expressed as a percentage. It will not add up to 100% unless you are lucky
111+
+ **pmem** - ratio of the process's resident set size to the physical memory on the machine, expressed as a percentage
112+
+ **bytesReceived** - the total number of bytes of data received by the process (per interface)
113+
+ **bytesTransmitted** - the total number of bytes of data transmitted by the process (per interface).
118114

119115
## Monitoring backends
120-
Metrics are pushed to one or multiple backends. The library currently supports three backends - see table below. Enabling/Disabling backends is done via configuration file.
116+
Metrics are pushed to one or multiple backends. The module currently supports three backends - see table below. Enabling/Disabling backends is done via configuration file.
121117

122118
| Backend name | Description | Transport | Client-side requirements | Handling tags |
123119
| ---------------- |:------------------------------:|:----------------------------:|:--------------------------:| --------------:|
124-
| InfluxDB | InfluxDB time series database | HTTP / UDP | cURL / boost asio | Supported by the backend |
120+
| InfluxDB | InfluxDB time series database | HTTP / UDP (InfluxDB Line Protocol) | cURL / boost asio | Supported by InfluxDB Line Protocol |
125121
| ApMonBackend | MonALISA Serivce | UDP | ApMon | Default tags concatenated with entity; Metric tags concatenated with name |
126-
| InfoLoggerBackned| O2 Logging module | - | - | Displayed in the end |
127-
| Flume | Collects, aggragate monitoring data | HTTP/JSON | cURL | In header (Flume Event) |
122+
| InfoLoggerBackned| O2 Logging module | - | (as log message) | Added to the end of message |
123+
| Flume | Collects, aggragate monitoring data | UDP (JSON) | boost asio | In Flume Event header |
128124

129-
Instruction how to install and configure server-sides backends are available in *Server-side backend installation and configuration* chapter.
125+
Instruction how to install and configure server-sides backends are available in [Server-side backend installation and configuration](#server-side-backend-installation-and-configuration) section.
130126

131127
## Configuration file
132128
+ AppMon
@@ -146,14 +142,14 @@ Instruction how to install and configure server-sides backends are available in
146142
+ hostname
147143
+ ProcessMonitor
148144
+ enable - enable process monitor
149-
+ interval - updates interval
145+
+ interval - updates interval[]
150146
+ DerivedMetrics
151147
+ maxCacheSize - maximum size of vector
152148

153-
See sample in examples/SampleConfig.ini
149+
See sample in [examples/config-default.ini](https://github.com/awegrzyn/Monitoring/blob/master/examples/config-default.ini).
154150

155151
## Getting started
156-
Examples are available in *example* directory.
152+
Examples are available in [example](https://github.com/awegrzyn/Monitoring/tree/master/examples) directory.
157153

158154
### Sending user defined metric - examples/1-Basic.cxx
159155
```cpp
@@ -189,7 +185,7 @@ Monitoring::Get().send(Metric{10, "myMetric"}.addTags({{"tag1", "value1"}, {"tag
189185
```
190186

191187
### Sending metric with user defined timestamp - examples/3-UserDefinedTimestamp.cxx
192-
By default timestamp is set by the library, but user can overwrite it manually.
188+
By default timestamp is set by the module, but user can overwrite it manually.
193189
```cpp
194190
// configure monitoring (only once per process), pass configuration path as parameter
195191
Monitoring::Configure("file:///home/awegrzyn/hackathon/Monitoring/examples/SampleConfig.ini");
@@ -213,7 +209,7 @@ Monitoring::Get().send(Metric{40, "myCrazyMetric"}.setTimestamp(timestamp));
213209
```
214210
215211
### Derived metrics - examples/4-RateDerivedMetric.cxx
216-
The Library can calculate derived metrics: average value and rate.
212+
The module can calculate derived metrics: average value and rate.
217213
```cpp
218214
// configure monitoring (only once per process), pass configuration path as parameter
219215
Monitoring::Configure("file:///home/awegrzyn/hackathon/Monitoring/examples/SampleConfig.ini");
@@ -246,22 +242,20 @@ collector->send({10, "myMetric"});
246242
247243
## Server-side backend installation and configuration
248244
249-
### MonALISA
250-
##### MonALISA Service
245+
### MonALISA Service
251246
To install and configure the MonALISA service (1 central server):
252-
+ yum install monalisa-service
253-
+ copy config/ml_env to /opt/monalisa-service/Service/CMD/
254-
+ copy config/ml.properties to /opt/monalisa-service/Service/myFarm/
255-
+ copy config/myFarm.conf to /opt/monalisa-service/Service/myFarm/
256-
+ add following line to iptables and restart it: -A INPUT -p udp -m state --state NEW -m udp --dport 8884 -m comment --comment "MonALISA UDP packets" -j ACCEPT
257-
+ /sbin/service MLD start
258-
259-
##### MonALISA Client
260-
To install the MonALISA Client run:
261-
+ yum install monalisa-client
247+
+ `yum install monalisa-service`
248+
+ copy `config/ml_env` to `/opt/monalisa-service/Service/CMD/`
249+
+ copy `config/ml.properties` to `/opt/monalisa-service/Service/myFarm/`
250+
+ copy `config/myFarm.conf` to `/opt/monalisa-service/Service/myFarm/`
251+
+ add following line to iptables and restart it: `-A INPUT -p udp -m state --state NEW -m udp --dport 8884 -m comment --comment "MonALISA UDP packets" -j ACCEPT`
252+
+ `/sbin/service MLD start`
262253
263254
### InfluxDB
264-
Instructions are avaliable here: https://docs.influxdata.com/influxdb/v1.2/introduction/installation/
255+
Instructions are available at [InfluxDB page](https://docs.influxdata.com/influxdb/v1.2/introduction/installation/).
265256
266257
### InfoLogger
267-
There is no installation/configuration procedure needed.
258+
The InfoLogger module is shared library which is linked during compilation time.
259+
260+
### Flume
261+
See [Flume User Guide](https://flume.apache.org/FlumeUserGuide.html) documentation.

0 commit comments

Comments
 (0)