Airframe Metrics

airframe-metrics is a library for using human-readable representations of time, data byte size, etc.

Usage

Maven Central

build.sbt

libraryDependencies += "org.wvlet.airframe" %% "airframe-metrics" % "(version)"

DataSize

Human-readable byte-size representation (e.g., 10GB, 1TB, etc.)

import wvlet.airframe.metrics.DataSize

// Returns the most succinct representation of the data size
DataSize.succinct(1024).toString // 1kB
DataSize.succinct(3 * 1024 * 1024).toString // 3MB

// Parse the datasize strings
DataSize("5GB") // DataSize(5.0, GIGABYTE)

ElapsedTime

Human-readable time representation (e.g., 1ns, 1 us, 1ms, 1s, 1m, 1h, 1d, etc.) useful for measuring elapsed times.

import wvlet.airframe.metrics.ElapsedTime

// Returns the most succinct
ElapsedTime.succinctMillis(3 * 1000) // ElapsedTime(3.0, SECONDS)
ElapsedTime.succinctMillis(60 * 1000) // ElapsedTime(1.0, MINUTES)

// Parse the elapsed time strings
val e = ElapsedTime("1h") // ElapsedTime(1.0, HOURS)
e.toMillis // 3600000

Relative Time Window

When writing data processing programs of time-series data, we usually don’t care about the exact date. Rather we use relative time windows from the current time, such as today, last 7 days, last 6 hours, last month, etc. TimeWindow class in airframe-metrics enables specifying such time windows using a human-friendly string format.

Code Example

import wvlet.airframe.metrics.TimeWindow

val w =
  TimeWindow
  .withTimeZone("PDT")  // Set a time zone (you can also use withSystemTimeZone, withUTC, etc.)
  .withOffset("2016-06-26 01:23:45-0700") // Specify the context time. The default is the current time.

// last 7 days
println(w.parse("-7d"))     // [2016-06-19 00:00:00-0700,2016-06-26 00:00:00-0700)

// last 7 days to now
println(w.parse("-7d/now")) // [2016-06-19 00:00:00-0700,2016-06-26 01:23:45-0700)

Time Window String Representation

To specify time ranges at ease, airframe-metrics uses the following string representation of time windows, such as -1d, -30m, +7d, etc. Values with (or without)- sign means the last time range, and values with + sign means the next time range from the context time.

Format

DURATION := (+ | -)?(INTEGER)(UNIT)
// seconds, minutes, hours, days, weeks, (M)onths, quarters, years
UNIT     := s | m | h | d | w | M | q | y

OFFSET   := DURATION | DATE_TIME
RANGE    := (DURATION) (/ (OFFSET))?
DATE_TIME := yyyy-MM-dd( HH:mm:ss(.ZZZ|' ' z)?)?

Examples

Here are several examples of relative time window strings when the current time is 2016-06-26 01:23:45-0700:

Duration Definition start end (exclusive)
1h this hour 2016-06-26 01:00:00-0700 2016-06-26 02:00:00-0700
1d today 2016-06-26 00:00:00-0700 2016-06-27 00:00:00-0700
1M this month 2016-06-01 00:00:00-0700 2016-07-01 00:00:00-0700
-1h last hour 2016-06-26 00:00:00-0700 2016-06-26 01:00:00-0700
-1h/0h last hour 2016-06-26 00:00:00-0700 2016-06-26 01:00:00-0700
-1h/0m last hour until last minute 2016-06-26 00:00:00-0700 2016-06-26 01:23:00-0700
-1h/0s last hour until last second 2016-06-26 00:00:00-0700 2016-06-26 01:23:45-0700
-1h/now last hour to now 2016-06-26 00:00:00-0700 2016-06-26 01:23:45-0700
-60m/2017-01-23 01:23:45 last 60 minutes to the given offset minute 2017-01-23 00:23:00-0700 2017-01-23 01:23:00-0700
-1d last day 2016-06-25 00:00:00-0700 2016-06-26 00:00:00-0700
-7d last 7 days 2016-06-19 00:00:00-0700 2016-06-26 00:00:00-0700
-7d/now last 7 days to now 2016-06-10 00:00:00-0700 2016-06-26 01:23:45-0700
-3d/2017-04-07 last 3 days from a given offset 2017-04-04 00:00:00-0700 2017-04-07 00:00:00-0700
+7d next 7 days (including today) 2016-06-26 00:00:00-0700 2016-07-03 00:00:00-0700
+7d/now next 7 days from now 2016-06-26 01:23:45-0700 2016-07-03 00:00:00-0700
-1w last week 2016-06-13 00:00:00-0700 2016-06-20 00:00:00-0700
-1M last month 2016-05-01 00:00:00-0700 2016-06-01 00:00:00-0700
-1q last quarter 2016-01-01 00:00:00-0700 2016-04-01 00:00:00-0700
-1y last year 2015-01-01 00:00:00-0700 2016-01-01 00:00:00-0700
-1h/2017-01-23 01:00:00 last hour from the given offset (hour) 2017-01-23 00:00:00-0700 2017-01-23 01:00:00-0700
-1h/2017-01-23 01:23:45 last hour from the given offset (hour) 2017-01-23 00:00:00-0700 2017-01-23 01:00:00-0700
-1M/2017-01-23 01:23:45 last month from the given offset (hour) 2016-12-01 00:00:00-0700 2017-01-01 00:00:00-0700
0M/2017-01-23) from beginning of the month to a given offset 2017-01-01 00:00:00-0700 2017-01-23 00:00:00-0700
+1M/2017-01-23 01:23:45) from a given offset to end of the month 2017-01-23 01:23:45-0700 2017-02-01 00:00:00-0700