[pkg/ottl] Cleanup OTTL Time/Duration

pkg/ottl/expression.go

@@ -583,13 +583,13 @@ func (p *Parser[K]) newGetterFromConverter(c converter) (Getter[K], error) {
 	}, nil
 }
 
-// TimeGetter is a Getter that must return an time.Time.
+// TimeGetter is a Getter that must return a time.Time.
 type TimeGetter[K any] interface {
-	// Get retrieves an time.Time value.
+	// Get retrieves a time.Time value.
 	Get(ctx context.Context, tCtx K) (time.Time, error)
 }
 
-// StandardTimeGetter is a basic implementation of IntGetter
+// StandardTimeGetter is a basic implementation of TimeGetter
 type StandardTimeGetter[K any] struct {
 	Getter func(ctx context.Context, tCtx K) (interface{}, error)
 }
@@ -613,9 +613,9 @@ func (g StandardTimeGetter[K]) Get(ctx context.Context, tCtx K) (time.Time, erro
 	}
 }
 
-// DurationGetter is a Getter that must return an time.Duration.
+// DurationGetter is a Getter that must return a time.Duration.
 type DurationGetter[K any] interface {
-	// Get retrieves an int64 value.
+	// Get retrieves an time.Duration value.
 	Get(ctx context.Context, tCtx K) (time.Duration, error)
 }
 

pkg/ottl/ottlfuncs/README.md

@@ -279,20 +279,29 @@ Available Converters:
 - [ConvertCase](#convertcase)
 - [ExtractPatterns](#extractpatterns)
 - [FNV](#fnv)
+- [Hours](#hours)
 - [Duration](#duration)
 - [Int](#int)
 - [IsMap](#ismap)
 - [IsMatch](#ismatch)
 - [IsString](#isstring)
 - [Log](#log)
+- [Microseconds](#microseconds)
+- [Milliseconds](#milliseconds)
+- [Minutes](#minutes)
+- [Nanoseconds](#nanoseconds)
 - [ParseJSON](#parsejson)
+- [Seconds](#seconds)
 - [SHA1](#sha1)
 - [SHA256](#sha256)
 - [SpanID](#spanid)
 - [Split](#split)
-- [Time](#time)
-- [TraceID](#traceid)
 - [Substring](#substring)
+- [Time](#time)
+- [UnixMicro](#unixmicro)
+- [UnixMilli](#unixmilli)
+- [UnixNano](#unixnano)
+- [UnixSeconds](#unixseconds)
 - [UUID](#UUID)
 
 ### Concat
@@ -389,6 +398,20 @@ Examples:
 
 - `FNV("name")`
 
+### Hours
+
+`Hours(value)`
+
+The `Hours` Converter returns the duration as a floating point number of hours.
+
+`value` is a `time.Duration`. If `value` is another type an error is returned.
+
+The returned type is `float64`.
+
+Examples:
+
+- `Hours(Duration("1h"))`
+
 ### Int
 
 `Int(value)`
@@ -516,6 +539,62 @@ Examples:
 
 - `Int(Log(attributes["duration_ms"])`
 
+### Microseconds
+
+`Microseconds(value)`
+
+The `Microseconds` Converter returns the duration as an integer millisecond count.
+
+`value` is a `time.Duration`. If `value` is another type an error is returned.
+
+The returned type is `int64`.
+
+Examples:
+
+- `Microseconds(Duration("1h"))`
+
+### Milliseconds
+
+`Milliseconds(value)`
+
+The `Milliseconds` Converter returns the duration as an integer millisecond count.
+
+`value` is a `time.Duration`. If `value` is another type an error is returned.
+
+The returned type is `int64`.
+
+Examples:
+
+- `Milliseconds(Duration("1h"))`
+
+### Minutes
+
+`Minutes(value)`
+
+The `Minutes` Converter returns the duration as a floating point number of minutes.
+
+`value` is a `time.Duration`. If `value` is another type an error is returned.
+
+The returned type is `float64`.
+
+Examples:
+
+- `Minutes(Duration("1h"))`
+
+### Nanoseconds
+
+`Nanoseconds(value)`
+
+The `Nanoseconds` Converter returns the duration as an integer nanosecond count.
+
+`value` is a `time.Duration`. If `value` is another type an error is returned.
+
+The returned type is `int64`.
+
+Examples:
+
+- `Nanoseconds(Duration("1h"))`
+
 ### ParseJSON
 
 `ParseJSON(target)`
@@ -547,6 +626,20 @@ Examples:
 
 - `ParseJSON(body)`
 
+### Seconds
+
+`Seconds(value)`
+
+The `Seconds` Converter returns the duration as a floating point number of seconds.
+
+`value` is a `time.Duration`. If `value` is another type an error is returned.
+
+The returned type is `float64`.
+
+Examples:
+
+- `Seconds(Duration("1h"))`
+
 ### SHA1
 
 `SHA1(value)`
@@ -618,6 +711,21 @@ Examples:
 
 - ```Split("A|B|C", "|")```
 
+### Substring
+
+`Substring(target, start, length)`
+
+The `Substring` Converter returns a substring from the given start index to the specified length.
+
+`target` is a string. `start` and `length` are `int64`.
+
+If `target` is not a string or is nil, an error is returned.
+If the start/length exceed the length of the `target` string, an error is returned.
+
+Examples:
+
+- `Substring("123456789", 0, 3)`
+
 ### Time
 
 The `Time` Converter takes a string representation of a time and converts it to a Golang `time.Time`.
@@ -642,20 +750,61 @@ Examples:
 
 - `TraceID(0x00000000000000000000000000000000)`
 
-### Substring
+### UnixMicro
 
-`Substring(target, start, length)`
+`UnixMicro(value)`
 
-The `Substring` Converter returns a substring from the given start index to the specified length.
+The `UnixMicro` Converter returns the time as a Unix time, the number of microseconds elapsed since January 1, 1970 UTC.
 
-`target` is a string. `start` and `length` are `int64`.
+`value` is a `time.Time`. If `value` is another type an error is returned.
 
-If `target` is not a string or is nil, an error is returned.
-If the start/length exceed the length of the `target` string, an error is returned.
+The returned type is `int64`.
 
 Examples:
 
-- `Substring("123456789", 0, 3)`
+- `UnixMicro(Time("02/04/2023", "%m/%d/%Y"))`
+
+### UnixMilli
+
+`UnixMilli(value)`
+
+The `UnixMilli` Converter returns the time as a Unix time, the number of milliseconds elapsed since January 1, 1970 UTC.
+
+`value` is a `time.Time`. If `value` is another type an error is returned.
+
+The returned type is `int64`.
+
+Examples:
+
+- `UnixMilli(Time("02/04/2023", "%m/%d/%Y"))`
+
+### UnixNano
+
+`UnixNano(value)`
+
+The `UnixNano` Converter returns the time as a Unix time, the number of nanoseconds elapsed since January 1, 1970 UTC.
+
+`value` is a `time.Time`. If `value` is another type an error is returned.
+
+The returned type is `int64`.
+
+Examples:
+
+- `UnixNano(Time("02/04/2023", "%m/%d/%Y"))`
+
+### UnixSeconds
+
+`UnixSeconds(value)`
+
+The `UnixSeconds` Converter returns the time as a Unix time, the number of seconds elapsed since January 1, 1970 UTC.
+
+`value` is a `time.Time`. If `value` is another type an error is returned.
+
+The returned type is `int64`.
+
+Examples:
+
+- `UnixSeconds(Time("02/04/2023", "%m/%d/%Y"))`
 
 ### UUID