# Module rrd

- Description
- Data Types
- Function Index
- Function Details

Round-Robin-Database (RRD) clone.

Copyright © 2011 Zuse Institute Berlin

Version: $Id$

Authors: Thorsten Schuett (`schuett@zib.de`).

## Description

Round-Robin-Database (RRD) clone.

## Data Types

### counter_type()

    counter_type() = number()

### data_type()

    data_type() =
        gauge_type() |
        counter_type() |
        histogram_type() |
        timing_type() |
        event_type(term())

### dump_fun_existing()

    dump_fun_existing(T) =
        fun((rrd(),
             From :: internal_time(),
             To :: internal_time(),
             Value :: data_type()) ->
                T)

### dump_fun_nonexisting()

    dump_fun_nonexisting(T) =
        fun((rrd(), From :: internal_time(), To :: internal_time()) ->
                ignore | {keep, T})

### erlang_timestamp()

    erlang_timestamp() =
        {MegaSecs :: non_neg_integer(),
         Secs :: 0..999999,
         MicroSecs :: 0..999999}

### event_type()

    event_type(T) = [{internal_time(), T}]

### gauge_type()

    gauge_type() = number()

### histogram_type()

    histogram_type() =
        histogram:histogram() | histogram_rt:histogram()

### internal_time()

    internal_time() = non_neg_integer()

default: micro seconds since Epoch

### rrd()

abstract datatype: `rrd()`

### time()

    time() = erlang_timestamp()

### timeseries_type()

    timeseries_type() =
        gauge |
        counter |
        event |
        {histogram, Size :: non_neg_integer()} |
        {histogram_rt,
         Size :: non_neg_integer(),
         BaseKey :: histogram_rt:base_key()} |
        {timing | timing_with_hist, us | ms | s | count | percent}

### timespan()

    timespan() = pos_integer()

### timing_type()

    timing_type() =
        {Sum :: number(),
         Sum2 :: number(),
         Count :: pos_integer(),
         Min :: number(),
         Max :: number(),
         Hist :: histogram:histogram()}

### update_fun()

    update_fun(T, NewV) =
        fun((Time :: internal_time(), Old :: T | undefined, NewV) -> T)

## Function Index

add/3 | Note: gauge, counter and timing types accept only number() as value, event accepts any value.
add_nonexisting_timeslots/2 | Adds to DB all non-existing time slots from OtherDB that are newer than or are in the current time slot of DB.
add_now/2 | Note: gauge, counter and timing types accept only number() as value, event accepts any value.
add_with/4 |
check_config/0 | Checks whether config parameters of the rrd module exist and are valid.
check_timeslot/2 | Advances the stored timeslots (if necessary) to the given time.
check_timeslot_now/1 | Advances the stored timeslots (if necessary) to the current time.
create/3 | Creates a new rrd() record.
create/4 | StepSize in milliseconds.
dump/1 |
dump_with/2 |
dump_with/3 |
get_all_values/2 | Gets all values as list from newest to oldest (desc) or from oldest to newest (asc).
get_count/1 |
get_current_time/1 |
get_slot_length/1 |
get_slot_start/2 | Gets the start of the given slot.
get_type/1 |
get_value/2 | Gets the value at the given time or 'undefined' if there is no value.
get_value_by_offset/2 | If SlotOffset is 0, gets the current value, otherwise the value in a previous slot the given offset away from the current one.
merge/2 | Merges any value of DB2 which is in the current or a future time slot of DB1 into it and returns a new rrd.
reduce_timeslots/2 | Reduces the number of time slots.
timing_with_hist_merge_fun/3 |

## Function Details

### create/3

    create(SlotLength :: timespan(),
           Count :: pos_integer(),
           Type :: timeseries_type()) ->
              rrd()

Creates a new rrd() record. SlotLength in microseconds, Count is the number of time slots to keep, type the type of rrd to create.

### add_now/2

    add_now(Value :: term(), DB :: rrd()) -> rrd()

Note: gauge, counter and timing types accept only number() as value, event accepts any value.

### check_timeslot_now/1

    check_timeslot_now(DB :: rrd()) -> rrd()

Advances the stored timeslots (if necessary) to the current time.

### dump/1

    dump(DB :: rrd()) -> [{From :: time(), To :: time(), data_type()}]

### dump_with/2

    dump_with(DB :: rrd(), FunExist :: dump_fun_existing(T)) -> [T]

### dump_with/3

    dump_with(DB :: rrd(),
              FunExist :: dump_fun_existing(T),
              FunNotExist :: dump_fun_nonexisting(U)) ->
                 [T | U]

### merge/2

    merge(DB1 :: rrd(), DB2 :: rrd()) -> rrd()

Merges any value of DB2 which is in the current or a future time slot of DB1 into it and returns a new rrd. Note: gauge rrd values will only be updated if no previous value existed since we can not determine which value is newer. For any value from DB2 uses (StartTime + EndTime) div 2 as the time for adding it.

### create/4

    create(SlotLength :: timespan(),
           Count :: pos_integer(),
           Type :: timeseries_type(),
           StartTime :: time() | internal_time()) ->
              rrd()

StepSize in milliseconds

### add/3

    add(Time :: time() | internal_time(),
        Value :: term(),
        DB :: rrd()) ->
           rrd()

Note: gauge, counter and timing types accept only number() as value, event accepts any value.

### check_timeslot/2

    check_timeslot(Time :: time() | internal_time(), DB :: rrd()) ->
                      rrd()

Advances the stored timeslots (if necessary) to the given time.

### add_with/4

    add_with(Time :: internal_time(),
             NewV,
             DB :: rrd(),
             F :: update_fun(data_type(), NewV)) ->
                rrd()

### get_slot_start/2

    get_slot_start(SlotIdx :: integer(), DB :: rrd()) ->
                      internal_time()

Gets the start of the given slot. Some examples of values for SlotIdx: previous slot: -1, current slot: 0, next slot: 1

### reduce_timeslots/2

    reduce_timeslots(SlotCount :: pos_integer(), DB :: rrd()) -> rrd()

Reduces the number of time slots.

### add_nonexisting_timeslots/2

    add_nonexisting_timeslots(DB :: rrd(), OtherDB :: rrd()) -> rrd()

Adds to DB all non-existing time slots from OtherDB that are newer than or are in the current time slot of DB. Both structures must have the same type and the same slot borders!

### get_slot_length/1

    get_slot_length(DB :: rrd()) -> timespan()

### get_type/1

    get_type(DB :: rrd()) -> timeseries_type()

### get_count/1

    get_count(DB :: rrd()) -> pos_integer()

### get_current_time/1

    get_current_time(DB :: rrd()) -> internal_time()

### get_value/2

    get_value(DB :: rrd(), Time :: time() | internal_time()) ->
                 undefined | data_type()

Gets the value at the given time or 'undefined' if there is no value.

### get_value_by_offset/2

    get_value_by_offset(DB :: rrd(), SlotOffset :: non_neg_integer()) ->
                           undefined | data_type()

If SlotOffset is 0, gets the current value, otherwise the value in a previous slot the given offset away from the current one. May return 'undefined' if there is no value.

### get_all_values/2

    get_all_values(X1 :: asc | desc, DB :: rrd()) ->
                      [undefined | data_type()]

Gets all values as list from newest to oldest (desc) or from oldest to newest (asc). Values may be undefined.

### timing_with_hist_merge_fun/3

    timing_with_hist_merge_fun(Time :: internal_time(),
                               Old :: timing_type() | undefined,
                               New :: timing_type() | undefined) ->
                                  timing_type() | undefined

### check_config/0

    check_config() -> boolean()

Checks whether config parameters of the rrd module exist and are valid.

Generated by EDoc, Feb 29 2016, 16:12:18.