-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
125 lines (83 loc) · 4.78 KB
/
README.Rmd
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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# rrd <img src="man/figures/logo.svg" align="right" height="139" width="139"/>
<!-- badges: start -->
[](https://github.com/andrie/rrd/actions) [](https://cran.r-project.org/package=rrd) [](https://lifecycle.r-lib.org/articles/stages.html) [](https://www.r-pkg.org:443/pkg/rrd) [](https://www.r-pkg.org:443/pkg/rrd) [](https://app.codecov.io/gh/andrie/rrd?branch=main)
<!-- badges: end -->
The `rrd` package allows you to read data from an [RRD](https://oss.oetiker.ch/rrdtool/) Round Robin Database.
## Installation
### System requirements
In order to build the package from source you need [librrd](https://oss.oetiker.ch/rrdtool/doc/librrd.en.html). Installing [RRDtool](https://oss.oetiker.ch/rrdtool/) from your package manager will usually also install the library.
| Platform | Installation |
|-----------------|------------------------------|
| Debian / Ubuntu | `apt-get install librrd-dev` |
| RHEL / CentOS | `yum install rrdtool-devel` |
| Fedora | `yum install rrdtool-devel` |
| Solaris / CSW | Install `rrdtool` |
| OSX | `brew install rrdtool` |
| Windows | Not available |
Note: on OSX you may have to update `xcode`, using `xcode-select --install`.
### Package installation
You can install the stable version of the package from CRAN:
``` r
install.packages("rrd")
```
And the development version from [GitHub](https://github.com/):
``` r
# install.packages("remotes")
remotes::install_github("andrie/rrd")
```
## About RRD and RRDtool <img src="man/figures/rrdtool-logo.png" align="right" height="70"/>
The `rrd` package is a wrapper around `RRDtool`. Internally it uses [librrd](https://oss.oetiker.ch/rrdtool/doc/librrd.en.html) to import the binary data directly into R without exporting it to an intermediate format first.
For an introduction to RRD database, see <https://oss.oetiker.ch/rrdtool/tut/rrd-beginners.en.html>
## Example
The package contains some example RRD files that originated in an instance of RStudio Connect. In this example, you analyze CPU data in the file `cpu-0.rrd`.
Load the package and assign the location of the `cpu-0.rrd` file to a variable:
```{r load}
library(rrd)
rrd_cpu_0 <- system.file("extdata/cpu-0.rrd", package = "rrd")
```
To describe the contents of an RRD file, use `describe_rrd()`:
```{r describe}
describe_rrd(rrd_cpu_0)
```
To read an entire RRD file, i.e. all of the RRA archives, use `read_rrd()`. This returns a list of `tibble` objects:
```{r rrd}
cpu <- read_rrd(rrd_cpu_0)
str(cpu, max.level = 1)
```
Since the resulting object is a list of `tibble`s, you can easily work with individual data frames:
```{r inspect-rrd}
names(cpu)
cpu[[1]]
tail(cpu$AVERAGE60$sys)
```
To read a single RRA archive from an RRD file, use `read_rra()`. To use this function, you must specify several arguments that define the specific data to retrieve. This includes the consolidation function (e.g. "AVERAGE") and time step (e.g. 60), the `end` time. You must also specifiy either the `start` time, or the number of steps, `n_steps`.
In this example, you extract the average for 1 minute periods (`step = 60`), for one entire day (`n_steps = 24 * 60`):
```{r rra}
end_time <- as.POSIXct("2018-05-02") # timestamp with data in example
avg_60 <- read_rra(rrd_cpu_0, cf = "AVERAGE", step = 60, n_steps = 24 * 60,
end = end_time)
avg_60
```
And you can easily plot using your favourite packages:
```{r plot, out.width="90%", fig.height=3, fig.width=8}
library(ggplot2)
ggplot(avg_60, aes(x = timestamp, y = user)) +
geom_line() +
stat_smooth(method = "loess", span = 0.125, se = FALSE) +
ggtitle("CPU0 usage, data read from RRD file")
```
## More information
For more information on `rrdtool` and the `rrd` format please refer to the official [rrdtool documentation](https://oss.oetiker.ch/rrdtool/doc/index.en.html) and [tutorials](https://oss.oetiker.ch/rrdtool/tut/index.en.html).
You can also read a more in-depth description of the package in an [R Views](https://rviews.rstudio.com/) blog post [Reading and analyzing log files in the RRD database format](https://rviews.rstudio.com/2018/06/20/reading-rrd-files/).