| 1 | ## Durations in Netdata |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ### Supported Duration Units |
| 6 | |
| 7 | 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: |
| 8 | |
| 9 | | Symbol | Description | Value | Compatibility | Formatter | Full Names | |
| 10 | |:------:|:------------:|:--------:|:-------------:|:---------:|:----------:| |
| 11 | | `ns` | Nanoseconds | `1ns` | UCUM | **Yes** | nanosecond, nanoseconds | |
| 12 | | `us` | Microseconds | `1000ns` | UCUM | **Yes** | microsecond, microseconds | |
| 13 | | `ms` | Milliseconds | `1000us` | UCUM | **Yes** | millisecond, milliseconds | |
| 14 | | `s` | Seconds | `1000ms` | UCUM | **Yes** | sec, secs, second, seconds | |
| 15 | | `m` | Minutes | `60s` | Natural | **Yes** | minute, minutes | |
| 16 | | `min` | Minutes | `60s` | UCUM | No | minute, minutes | |
| 17 | | `h` | Hours | `60m` | UCUM | **Yes** | hr, hrs, hour, hours | |
| 18 | | `d` | Days | `24h` | UCUM | **Yes** | day, days | |
| 19 | | `w` | Weeks | `7d` | Natural | No | week, weeks | |
| 20 | | `wk` | Weeks | `7d` | UCUM | No | week, weeks | |
| 21 | | `mo` | Months | `30d` | UCUM | **Yes** | month, months | |
| 22 | | `M` | Months | `30d` | Backwards | No | month, months | |
| 23 | | `q` | Quarters | `3mo` | Natural | No | quarter, quarters | |
| 24 | | `y` | Years | `365d` | Natural | **Yes** | year, years | |
| 25 | | `Y` | Years | `365d` | Backwards | No | year, years | |
| 26 | | `a` | Years | `365d` | UCUM | No | year, years | |
| 27 | |
| 28 | - **UCUM**: The unit is specified in the Unified Code for Units of Measure (UCUM) standard. |
| 29 | - **Natural**: We feel that this is more natural for expressing durations with single letter units. |
| 30 | - **Backwards**: This unit has been used in the past in Netdata, and we support it for backwards compatibility. |
| 31 | - **Full Names**: All full unit names are supported in addition to the abbreviated forms and are case-insensitive. |
| 32 | |
| 33 | ### Duration Expression Format |
| 34 | |
| 35 | Netdata allows users to express durations in both simple and complex formats. |
| 36 | |
| 37 | - **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`. |
| 38 | |
| 39 | - **Full Unit Names**: In addition to abbreviated units, Netdata also supports full unit names for better readability. For example: |
| 40 | - `7 days` or `7days` (equivalent to `7d`) |
| 41 | - `2 hours` or `2hours` (equivalent to `2h`) |
| 42 | - `30 seconds` or `30seconds` (equivalent to `30s`) |
| 43 | - All unit names are case-insensitive: `7 DAYS`, `7 Days`, `7 days` are all valid |
| 44 | |
| 45 | - **Complex Formats**: A duration can also be composed of multiple units added together. For example: |
| 46 | - `1y2mo3w4d` represents 1 year, 2 months, 3 weeks, and 4 days. |
| 47 | - `15d-12h` represents 15 days minus 12 hours (which equals 14 days and 12 hours). |
| 48 | - `2 hours 30 minutes` or `2hours30minutes` (equivalent to `2h30m`) |
| 49 | |
| 50 | 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`. |
| 51 | |
| 52 | The same unit can be given multiple times, so that `1d0.5d` is `1d12h` and `1d-0.5d` is `12h`. |
| 53 | |
| 54 | The order of units in the expressions is irrelevant, so that `1m2h3d` is the same to `3d2h1m`. |
| 55 | |
| 56 | 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. |
| 57 | |
| 58 | ### Duration Rounding |
| 59 | |
| 60 | Netdata provides various functions to parse and round durations according to specific needs: |
| 61 | |
| 62 | - **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`. |
| 63 | |
| 64 | - **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`). |
| 65 | |
| 66 | ### Maximum and Minimum Duration Limits |
| 67 | |
| 68 | 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. |
| 69 | |
| 70 | ### Inconsistencies in Duration Units |
| 71 | |
| 72 | While Netdata provides a flexible system for specifying durations, some inconsistencies arise due to the way different units are defined: |
| 73 | |
| 74 | - **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. |
| 75 | |
| 76 | - **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). |
| 77 | |
| 78 | - **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. |
| 79 | |
| 80 | These definitions can lead to some unexpected results when performing arithmetic with durations: |
| 81 | |
| 82 | **Example of Inconsistency**: |
| 83 | |
| 84 | `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). |
| 85 | |
| 86 | ### Negative Durations |
| 87 | |
| 88 | 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)`. |
| 89 | |
| 90 | The same rule is applied when generating duration expressions. |
| 91 | |
| 92 | ### "Ago" Suffix |
| 93 | |
| 94 | 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: |
| 95 | |
| 96 | - **`7 days ago`** is equivalent to **`-7d`** |
| 97 | - **`2 hours ago`** is equivalent to **`-2h`** |
| 98 | - **`30 minutes ago`** is equivalent to **`-30m`** |
| 99 | |
| 100 | The "ago" suffix works with all duration formats: |
| 101 | - Abbreviated: `7d ago`, `2h ago`, `30m ago` |
| 102 | - Full names: `7 days ago`, `2 hours ago`, `30 minutes ago` |
| 103 | - Complex expressions: `2 hours 30 minutes ago`, `1d12h ago` |
| 104 | - Case variations: `7 days AGO`, `7 days Ago`, `7daysago` |
| 105 | |
| 106 | Note: If you use a negative duration with "ago", it results in a positive value: `-7 days ago` = 7 days (double negative). |
| 107 | |
| 108 | ### Example Duration Expressions |
| 109 | |
| 110 | Here are some examples of valid duration expressions: |
| 111 | |
| 112 | 1. **`30s`** or **`30 seconds`**: 30 seconds. |
| 113 | 2. **`5m`** or **`5 minutes`**: 5 minutes. |
| 114 | 3. **`2h30m`** or **`2 hours 30 minutes`**: 2 hours and 30 minutes. |
| 115 | 4. **`1.5d`** or **`1.5 days`**: 1 day and 12 hours. |
| 116 | 5. **`1w3d4h`** or **`1 week 3 days 4 hours`**: 1 week, 3 days, and 4 hours. |
| 117 | 6. **`1y2mo3d`** or **`1 year 2 months 3 days`**: 1 year, 2 months, and 3 days. |
| 118 | 7. **`15d-12h`** or **`15 days -12 hours`**: 14 days and 12 hours. |
| 119 | 8. **`7Days`** (case-insensitive): 7 days. |
| 120 | 9. **`2HOURS30MINUTES`** (case-insensitive): 2 hours and 30 minutes. |
| 121 | 10. **`7 days ago`** or **`7d ago`**: 7 days in the past (equivalent to -7 days). |
| 122 | 11. **`2 hours 30 minutes ago`**: 2.5 hours in the past (equivalent to -2h30m). |