[pkg/ottl] Updated docs for Time converter (open-telemetry#32185)

**Description:** Updated docs for ottl converter so it includes more information about substitutes users can use Few examples with timezone handling were added **Link to tracking Issue:** open-telemetry#32140 **Testing:** no testing **Documentation:** --------- Co-authored-by: Curtis Robert <[email protected]> Co-authored-by: Tyler Helmuth <[email protected]>
bogdandrutu · Apr 17, 2024 · 134c3a8 · 134c3a8
1 parent a84971c
commit 134c3a8
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 5 deletions.
diff --git a/internal/coreinternal/timeutils/internal/ctimefmt/ctimefmt.go b/internal/coreinternal/timeutils/internal/ctimefmt/ctimefmt.go
@@ -86,10 +86,10 @@ var ctimeSubstitutes = map[string]string{
 // %S - Second as a zero-padded decimal number (00, 01, ..., 59)
 // %L - Millisecond as a decimal number, zero-padded on the left (000, 001, ..., 999)
 // %f - Microsecond as a decimal number, zero-padded on the left (000000, ..., 999999)
-// %s - Nanosecond as a decimal number, zero-padded on the left (000000, ..., 999999)
+// %s - Nanosecond as a decimal number, zero-padded on the left (00000000, ..., 99999999)
 // %z - UTC offset in the form ±HHMM[SS[.ffffff]] or empty(+0000, -0400)
 // %Z - Timezone name or abbreviation or empty (UTC, EST, CST)
-// %D, %x - Short MM/DD/YY date, equivalent to %m/%d/%y
+// %D, %x - Short MM/DD/YYYY date, equivalent to %m/%d/%y
 // %F - Short YYYY-MM-DD date, equivalent to %Y-%m-%d
 // %T, %X - ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S
 // %r - 12-hour clock time (02:55:02 pm)

diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md
@@ -1131,15 +1131,58 @@ Examples:
 
 ### Time
 
-The `Time` Converter takes a string representation of a time and converts it to a Golang `time.Time`.
+`Time(target, format)`
 
-`time` is a string. `format` is a string.
+The `Time` Converter takes a string representation of a time and converts it to a Golang `time.Time`.
 
-If either `time` or `format` are nil, an error is returned. The parser used is the parser at [internal/coreinternal/parser](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/internal/coreinternal/timeutils). If the time and format do not follow the parsing rules used by this parser, an error is returned.
+`target` is a string. `format` is a string.
+
+If either `target` or `format` are nil, an error is returned. The parser used is the parser at [internal/coreinternal/parser](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/internal/coreinternal/timeutils). If the `target` and `format` do not follow the parsing rules used by this parser, an error is returned.
+
+`format` denotes a textual representation of the time value formatted according to ctime-like format string. It follows [standard Go Layout formatting](https://pkg.go.dev/time#pkg-constants) with few additional substitutes:
+| substitution | description | examples |
+|-----|-----|-----|
+|`%Y` | Year as a zero-padded number | 0001, 0002, ..., 2019, 2020, ..., 9999 |
+|`%y` | Year, last two digits as a zero-padded number | 01, ..., 99 |
+|`%m` | Month as a zero-padded number | 01, 02, ..., 12 |
+|`%o` | Month as a space-padded number | 1, 2, ..., 12 |
+|`%q` | Month as an unpadded number | 1,2,...,12 |
+|`%b`, `%h` | Abbreviated month name | Jan, Feb, ... |
+|`%B` | Full month name | January, February, ... |
+|`%d` | Day of the month as a zero-padded number | 01, 02, ..., 31 |
+|`%e` | Day of the month as a space-padded number| 1, 2, ..., 31 |
+|`%g` | Day of the month as a unpadded number | 1,2,...,31 |
+|`%a` | Abbreviated weekday name | Sun, Mon, ... |
+|`%A` | Full weekday name | Sunday, Monday, ... |
+|`%H` | Hour (24-hour clock) as a zero-padded number | 00, ..., 24 |
+|`%I` | Hour (12-hour clock) as a zero-padded number | 00, ..., 12 |
+|`%l` | Hour 12-hour clock | 0, ..., 24 |
+|`%p` | Locale’s equivalent of either AM or PM | AM, PM |
+|`%P` | Locale’s equivalent of either am or pm | am, pm |
+|`%M` | Minute as a zero-padded number | 00, 01, ..., 59 |
+|`%S` | Second as a zero-padded number | 00, 01, ..., 59 |
+|`%L` | Millisecond as a zero-padded number | 000, 001, ..., 999 |
+|`%f` | Microsecond as a zero-padded number | 000000, ..., 999999 |
+|`%s` | Nanosecond as a zero-padded number | 00000000, ..., 99999999 |
+|`%z` | UTC offset in the form ±HHMM[SS[.ffffff]] or empty | +0000, -0400 |
+|`%Z` | Timezone name or abbreviation or empty | UTC, EST, CST |
+|`%D`, `%x` | Short MM/DD/YYYY date, equivalent to %m/%d/%y | 01/21/2031 |
+|`%F` | Short YYYY-MM-DD date, equivalent to %Y-%m-%d | 2031-01-21 |
+|`%T`,`%X` | ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S | 02:55:02 |
+|`%r` | 12-hour clock time | 02:55:02 pm |
+|`%R` | 24-hour HH:MM time, equivalent to %H:%M | 13:55 |
+|`%n` | New-line character ('\n') | |
+|`%t` | Horizontal-tab character ('\t') | |
+|`%%` | A % sign | |
+|`%c` | Date and time representation | Mon Jan 02 15:04:05 2006 |
 
 Examples:
 
 - `Time("02/04/2023", "%m/%d/%Y")`
+- `Time("Feb 15, 2023", "%b %d, %Y")`
+- `Time("2023-05-26 12:34:56 HST", "%Y-%m-%d %H:%M:%S %Z")`
+- `Time("1986-10-01T00:17:33 MST", "%Y-%m-%dT%H:%M:%S %Z")`
+- `Time("2012-11-01T22:08:41+0000 EST", "%Y-%m-%dT%H:%M:%S%z %Z")`
 
 ### TraceID