Skip to content

Commit fd1c08b

Browse files
indigo423indigo423
committed
docs: Improve README with examples
Added an example using a local installation and using the docker container image. Signed-off-by: Ronny Trommer <ronny@no42.org>
1 parent 5b0afa3 commit fd1c08b

File tree

2 files changed

+167
-63
lines changed

2 files changed

+167
-63
lines changed

‎README.adoc‎

Lines changed: 0 additions & 63 deletions
This file was deleted.

‎README.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# JRobin to RRDtool Converter
2+
3+
This tool can be used to convert [JRobin](https://sourceforge.net/projects/jrobin/) time series data into [RRDtool](https://oss.oetiker.ch/rrdtool) compatible format.
4+
The tool was build in the [OpenNMS Project](https://www.opennms.com).
5+
6+
> [!IMPORTANT]
7+
> It is not possible to convert from different OpenNMS storage strategies like `storeByGroup` and `storeByForeignSource`.
8+
> Make sure you use the same settings as the origin OpenNMS with JRobin.
9+
> It is also *not* possible to change internal RRD data structure i.e. 'RRA' or 'step'.
10+
> The 'RRA' configuration in JRobin and RRDtool *must* be the same.
11+
12+
## 👮 Requirements
13+
14+
This tool has the following requirements
15+
16+
* Java 17 runtime environment (JRE) as [OpenJDK](https://openjdk.java.net/)
17+
* RRDtool has to be installed
18+
* Build from source requires Java Development Kit (JDK) and [Maven](https://maven.apache.org/download.cgi)
19+
* Make sure `mvn`, `java` and `javac` binary are in your search path
20+
* Verify JRE version with `java -version` and Java compiler version with `javac -version` which should be `17`
21+
22+
> [!IMPORTANT]
23+
> You need enough additional free disk space for the converter, JRobin files are dumped to XML and reimported into RRDtool.
24+
> You may need up to **13 to 16 times** the space of your current JRobin file size.
25+
> This tool does not modify existing JRobin files, anyway make always a backup.
26+
> By default a RRD file directory size with 26 MB will use 340 MB.
27+
> The XML RRD dump files and the JRobin files are still on the disk.
28+
> A user needs to delete these files manually.
29+
30+
## 👩‍🏭 Build from source
31+
32+
The following steps describe how to build the tool from source.
33+
34+
**Step 1:** Checkout the source code
35+
```
36+
git clone https://github.com/opennms-forge/jrobin-to-rrdtool-converter.git
37+
```
38+
39+
**Step 2:** Change directory
40+
```
41+
cd jrobin-to-rrdtool-converter
42+
```
43+
44+
**Step 3:** Compile and assemble runnable jar
45+
```
46+
make
47+
```
48+
49+
**Step 4:** Execute tool as runnable jar
50+
```
51+
cd target
52+
java -jar convertjrb-1.1.0-SNAPSHOT-jar-with-dependencies.jar
53+
```
54+
55+
## 🕹️ Usage
56+
57+
The converter has one argument with the path to OpenNMS JRobin files and has two additional options.
58+
59+
* `-rrdtool`: Location of the `rrdtool` binary which can be located with `which rrdtool`.
60+
If this option is not set the default is set to `/usr/local/bin/rrdtool`.
61+
* `-threads`: Number of threads to convert JRobin files into RRDtool format.
62+
If this option is not set, the default value is `4`.
63+
* `<path/to/jrobin-files>` is the path for the tool to search for existing JRobin files.
64+
65+
The convertion is not destructive for the existing JRobin files.
66+
Subdirectories and file names will be preserved.
67+
68+
> [!IMPORTANT]
69+
> JRobin files are **not** deleted and still exist.
70+
> The exchange XML data has to be manually cleaned up, e.g. `find . -iname $OPENNMS_HOME/share/rrd/*.xml --exec rm -rf {} \;`.
71+
72+
> [!TIP]
73+
> Backup your `/opt/opennms/share/rrd` or `/usr/share/opennms/share/rrd` directory so that you have a way to rollback in case you did a mistake.
74+
75+
## 🚀 Example with a native installation
76+
77+
Here is an example running the tool on the same server as the Horizon Core server with JRobin files in `/opt/opennms/share/rrd`.
78+
If you have a DEB-based installation the default directory is `/usr/share/opennms/share/rrd`.
79+
The directory structure is preserved during the migration.
80+
81+
**Step 1:** Create a directory for the tool
82+
```
83+
sudo mkdir -p /opt/jrb2rrd
84+
```
85+
86+
**Step 2:** Download the tool from the GitHub release
87+
```
88+
cd /opt/jrb2rrd
89+
sudo wget -P /opt/jrb2rrd https://github.com/opennms-forge/jrobin-to-rrdtool-converter/releases/download/v1.1.0/convertjrb-1.1.0.tar.gz
90+
sudo tar -xzf convertjrb-1.1.0.tar.gz
91+
```
92+
93+
**Step 3:** Stop OpenNMS Horizon Core service to prevent writing to JRobin files during the conversion.
94+
95+
```
96+
sudo systemctl stop opennms
97+
```
98+
99+
**Step 4:** Convert the file with the user `opennms`
100+
101+
```
102+
sudo -u opennms java -jar convertjrb-1.1.0-jar-with-dependencies.jar \
103+
-rrdtool /usr/bin/rrdtool \
104+
-threads 8 \
105+
/opt/opennms/share/rrd
106+
```
107+
108+
The RRD files are created in the exact same directory structure as the JRobin files.
109+
110+
**Step 5:** Configure OpenNMS Horizon using RRDTool following the instructions in the OpenNMS Horizon [Timeseries Storage](https://docs.opennms.com/horizon/latest/deployment/time-series-storage/timeseries/rrdtool.html) documentation.
111+
112+
**Step 6:** Start OpenNMS Horizon core
113+
114+
```
115+
sudo systemctl start opennms
116+
```
117+
118+
**Step 7:** Verify in resource graphs for nodes if you have access to historical data.
119+
120+
**Step 8:** Delete JRobin and XML files after successful migration
121+
122+
```
123+
sudo find /opt/opennms/share/rrd -name "*.jrb" -exec rm {} \;
124+
sudo find /opt/opennms/share/rrd -name "*.xml" -exec rm {} \;
125+
```
126+
127+
## 🐳 Example running with Docker
128+
129+
Change into the directory where your JRobin files (*.jrb) are located.
130+
Replace the path `/opt/opennms` with `/usr/share/opennms` if you are on a DEB-based operating system.
131+
132+
> [!TIP]
133+
> Replace OPENNMS_HOME in DEB-based systems with `/usr/share/opennms` and on RPM-based distributions with `/opt/opennms`.
134+
135+
**Step 1:** Stop OpenNMS Horizon Core service to prevent writing to JRobin files during the conversion.
136+
137+
```
138+
sudo systemctl stop opennms
139+
```
140+
141+
**Step 2:** Change into the directory with the RRD files
142+
```
143+
cd /opt/opennms/share/rrd
144+
```
145+
146+
**Step 3:** Run the converter with docker
147+
```
148+
sudo docker run --rm -v "$(pwd):/data" ghcr.io/opennms-forge/jrobin-to-rrdtool-converter:latest
149+
```
150+
151+
> [!TIP]
152+
> If you want to run it with more threads than 4, run it with `docker run --rm -v "$(pwd):/data" ghcr.io/opennms-forge/jrobin-to-rrdtool-converter:latest -threads 8 /data`
153+
154+
**Step 4:** Set the permissions for the OpenNMS user
155+
156+
```
157+
sudo /opt/opennms/bin/fix-permissions
158+
```
159+
160+
**Step 5:** Verify in resource graphs for nodes if you have access to historical data.
161+
162+
**Step 6:** Delete JRobin and XML files after successful migration
163+
164+
```
165+
sudo find /opt/opennms/share/rrd -name "*.jrb" -exec rm {} \;
166+
sudo find /opt/opennms/share/rrd -name "*.xml" -exec rm {} \;
167+
```

0 commit comments

Comments
 (0)