src/libnetdata/parsers/durations.md
Netdata provides a flexible and powerful way to specify durations for various configurations and operations, such as alerts, database retention, and other configuration options. Durations can be expressed in a variety of units, ranging from nanoseconds to years, allowing users to define time intervals in a human-readable format.
Netdata supports a wide range of duration units. The system follows the Unified Code for Units of Measure (UCUM) standard where applicable. Below is a table of all the supported units, their corresponding representations, and their compatibility:
| Symbol | Description | Value | Compatibility | Formatter | Full Names |
|---|---|---|---|---|---|
ns | Nanoseconds | 1ns | UCUM | Yes | nanosecond, nanoseconds |
us | Microseconds | 1000ns | UCUM | Yes | microsecond, microseconds |
ms | Milliseconds | 1000us | UCUM | Yes | millisecond, milliseconds |
s | Seconds | 1000ms | UCUM | Yes | sec, secs, second, seconds |
m | Minutes | 60s | Natural | Yes | minute, minutes |
min | Minutes | 60s | UCUM | No | minute, minutes |
h | Hours | 60m | UCUM | Yes | hr, hrs, hour, hours |
d | Days | 24h | UCUM | Yes | day, days |
w | Weeks | 7d | Natural | No | week, weeks |
wk | Weeks | 7d | UCUM | No | week, weeks |
mo | Months | 30d | UCUM | Yes | month, months |
M | Months | 30d | Backwards | No | month, months |
q | Quarters | 3mo | Natural | No | quarter, quarters |
y | Years | 365d | Natural | Yes | year, years |
Y | Years | 365d | Backwards | No | year, years |
a | Years | 365d | UCUM | No | year, years |
Netdata allows users to express durations in both simple and complex formats.
Simple Formats: A duration can be specified using a number followed by a unit, such as 5m (5 minutes), 2h (2 hours), or 1d (1 day). Fractional numbers are also supported, such as 1.5d, 3.5mo or 1.2y.
Full Unit Names: In addition to abbreviated units, Netdata also supports full unit names for better readability. For example:
7 days or 7days (equivalent to 7d)2 hours or 2hours (equivalent to 2h)30 seconds or 30seconds (equivalent to 30s)7 DAYS, 7 Days, 7 days are all validComplex Formats: A duration can also be composed of multiple units added together. For example:
1y2mo3w4d represents 1 year, 2 months, 3 weeks, and 4 days.15d-12h represents 15 days minus 12 hours (which equals 14 days and 12 hours).2 hours 30 minutes or 2hours30minutes (equivalent to 2h30m)Each number given in durations can be either positive or negative. For example 1h15m is 1 hour and 15 minutes, but 1h-15m results to 45m.
The same unit can be given multiple times, so that 1d0.5d is 1d12h and 1d-0.5d is 12h.
The order of units in the expressions is irrelevant, so that 1m2h3d is the same to 3d2h1m.
The system will parse durations with spaces in them, but we suggest to write them down in compact form, without spaces. This is required, especially in alerts configuration, since spaces in durations will affect how parent expressions are tokenized.
Netdata provides various functions to parse and round durations according to specific needs:
Default Rounding to Seconds: Most duration uses in Netdata are rounded to the nearest second. For example, a duration of 1.4s would round to 1s, while 1.5s would round to 2s.
Rounding to Larger Units: In some cases, such as database retention, durations are rounded to larger units like days. Even when rounding to a larger unit, durations can still be expressed in smaller units (e.g., 24h86400s for 2d).
Netdata's duration expressions can handle durations ranging from the minimum possible value of -INT64_MAX to the maximum of INT64_MAX in nanoseconds. This range translates approximately to durations between -292 years to +292 years.
While Netdata provides a flexible system for specifying durations, some inconsistencies arise due to the way different units are defined:
1 Year (y) = 365 Days (d): In Netdata, a year is defined as 365 days. This is an approximation, since the average year is about 365.25 days.
1 Month (mo) = 30 Days (d): Similarly, a month in Netdata is defined as 30 days, which is also an approximation. In reality, months vary in length (28 to 31 days).
1 Quarter (q) = 3 Months (mo) = 90 Days (d): A quarter is defined as 3 months, or 90 days, which aligns with the approximation of each month being 30 days.
These definitions can lead to some unexpected results when performing arithmetic with durations:
Example of Inconsistency:
1y-1d in Netdata calculates to 364d but also as 12mo4d because 1y = 365d and 1mo = 30d. This is inconsistent because 1y is defined as 12mo5d or 4q5d (given the approximations above).
When the first letter of a duration expression is the minus character, Netdata parses the entire expression as positive and then it negates the result. for example: -1m15s is -75s, not -45s. To get -45s the expression should be -1m-15s. So the initial - is treated like -(expression).
The same rule is applied when generating duration expressions.
Netdata supports the "ago" suffix to express durations in the past. When a duration expression ends with "ago" (case-insensitive), the resulting value is negated. This provides a more natural way to express past time intervals:
7 days ago is equivalent to -7d2 hours ago is equivalent to -2h30 minutes ago is equivalent to -30mThe "ago" suffix works with all duration formats:
7d ago, 2h ago, 30m ago7 days ago, 2 hours ago, 30 minutes ago2 hours 30 minutes ago, 1d12h ago7 days AGO, 7 days Ago, 7daysagoNote: If you use a negative duration with "ago", it results in a positive value: -7 days ago = 7 days (double negative).
Here are some examples of valid duration expressions:
30s or 30 seconds: 30 seconds.5m or 5 minutes: 5 minutes.2h30m or 2 hours 30 minutes: 2 hours and 30 minutes.1.5d or 1.5 days: 1 day and 12 hours.1w3d4h or 1 week 3 days 4 hours: 1 week, 3 days, and 4 hours.1y2mo3d or 1 year 2 months 3 days: 1 year, 2 months, and 3 days.15d-12h or 15 days -12 hours: 14 days and 12 hours.7Days (case-insensitive): 7 days.2HOURS30MINUTES (case-insensitive): 2 hours and 30 minutes.7 days ago or 7d ago: 7 days in the past (equivalent to -7 days).2 hours 30 minutes ago: 2.5 hours in the past (equivalent to -2h30m).