Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(stdlib/contrib): Add stdlib/contrib package events #3266

Merged
merged 2 commits into from
Oct 22, 2020
Merged

feat(stdlib/contrib): Add stdlib/contrib package events #3266

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c04321
feat(stdlib/contrib): Add stdlib/contrib package events
tomhollingworth Oct 19, 2020
0bf640f
feat(stdlib/contrib): Add stdlib/contrib package events (#1)
tomhollingworth Oct 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions libflux/go/libflux/buildinfo.gen.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,9 @@ var sourceHashes = map[string]string{
"stdlib/contrib/sranka/sensu/sensu.flux": "50f8e87b24535c7c37f99db96e419c5337c4b425c0a97596a9a1c86c6f275837",
"stdlib/contrib/sranka/teams/teams.flux": "57d5656dcb2db79f173e84d551efdbeefb643d028eaaecfff8ee7d2a033f9f50",
"stdlib/contrib/sranka/telegram/telegram.flux": "37d1614a215c6ca523e4efa5642ec9104936755a403e5bc4481d82a602f7719b",
"stdlib/contrib/tomhollingworth/events/duration.flux": "3b6b638039d9f59fa5f96d7139f2f0ecbbc1f9de79c3beee5a5f122cf0eab0f1",
"stdlib/contrib/tomhollingworth/events/duration_test.flux": "1a53a0f14f58dc8d0b5b6e7f4802988b92f8beee828e072ec4a42e661c71abc5",
"stdlib/contrib/tomhollingworth/events/duration_with_stop_test.flux": "086180642ff1a8f813f32796c321f03c2a8988c8976bbc20c8d3a29a323c4d19",
"stdlib/csv/csv.flux": "8710762ef15231ac7f5ef2afabab75941c3e25bf4b3822396875157563fcebf5",
"stdlib/date/date.flux": "14f78a91ff77417c47172e7a447cf517635049b978e08d2405c3af3cd014d450",
"stdlib/date/hour_duration_test.flux": "e349cddb4cc4967fd578da8eb453e9f7d9776176249323755356362653962c9c",
Expand Down
135 changes: 135 additions & 0 deletions stdlib/contrib/tomhollingworth/events/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Events Package

Use this Flux Package calculate the time between a record and the next record. The function `events.duration` peeks at the next record and calculates the duration an between records and associates it with the start of the event. For the final record it can be compared against a stop column or a timestamp. This function differs to existing `elapsed` which removes the first entry and `stateDuration` which totalized on a function.

See also
- [elapsed](https://docs.influxdata.com/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/elapsed/)
- [stateDuration](https://docs.influxdata.com/influxdb/v2.0/reference/flux/stdlib/built-in/transformations/stateduration/)

## events.duration

`duration` calculates the duration of the event.

| Name | Type | Description |
| ----------- | -------- | ---------------------------------------------------------------------------- |
| unit | duration | Units of state duration 'ns', 'us', 'µs', 'ms', 's', 'm', 'h' |
| columnName | string | The name of the result column. Default `duration` |
| timeColumn | string | The name of the time column, default `_time` |
| stopColumn | string | The name of the stop column, default `_stop` |
| stop | time | Optional. If provided, it will be used instead of the stop column |

Basic Example:

```flux
import "contrib/tomhollingworth/events"

from(bucket: "example-bucket")
|> range(start: -24h)
|> events.duration()
```

### Last Record Duration

The last record needs a time to compare to. The following strategy is implemented:
- Use `stop` if provided.
- If no `stop` time is provided, then use the value from the `stopColumn` column on the last record.
- If no `stopColumn` is provided then use `_stop` by default.

### Comparison to other functions

Consider the following dataset of a door opening and closing:

```flux
import "csv"

inData = "
#datatype,string,long,dateTime:RFC3339,string,string
#group,false,true,false,false,false
#default,,,,,
,result,table,_time,_value,_field
,,0,2020-01-01T08:00:00Z,Closed,value
,,0,2020-01-01T08:15:00Z,Open,value
,,0,2020-01-01T08:15:08Z,Closed,value
,,0,2020-01-01T08:21:00Z,Open,value
,,0,2020-01-01T08:21:07Z,Closed,value
,,0,2020-01-01T08:24:00Z,Open,value
,,0,2020-01-01T08:24:12Z,Closed,value
"

csv.from(csv: inData)
|> range(start: 2020-01-01T08:00:00Z, stop: 2020-01-01T08:30:00Z)
```

`|> elapsed()` yields the following. The first record is dropped and durations are associated with subsequent records. Totalizing on filter on value and summing the elasped column would have the duration swapped between open and closed.

```diff
-, result, table, _start, _stop, _time, _value, _field
+, result, table, _start, _stop, _time, _value, _field, elasped
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:00:00Z, Closed, value
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:10:00Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:10:00Z, Closed, value, 1600
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:00Z, Open, value, 1300
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:08Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:08Z, Closed, value, 8
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:00Z, Open, value, 1352
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:07Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:07Z, Closed, value, 7
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:00Z, Open, value, 173
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:12Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:12Z, Closed, value, 12
```

`|> stateDuration(fn: (r) => true)` yields the following. The duration is continuously totalized. For a particular state we could also include that in our stateDuration function, however time is counted twice on subsequent events. Totalizing this would have that time counted twice.

```diff
-, result, table, _start, _stop, _time, _value, _field
+, result, table, _start, _stop, _time, _value, _field, stateDuration
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:00:00Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:00:00Z, Closed, value, 0
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:10:00Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:10:00Z, Closed, value, 600
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:00Z, Open, value, 900
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:08Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:08Z, Closed, value, 908
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:00Z, Open, value, 1260
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:07Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:07Z, Closed, value, 1267
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:00Z, Open, value, 1440
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:12Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:12Z, Closed, value, 1452
```

`|> events.duration()` yields the following.
```diff
-, result, table, _start, _stop, _time, _value, _field
+, result, table, _start, _stop, _time, _value, _field, duration
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:00:00Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:00:00Z, Closed, value, 600
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:10:00Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:10:00Z, Closed, value, 300
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:00Z, Open, value, 8
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:08Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:15:08Z, Closed, value, 352
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:00Z, Open, value, 7
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:07Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:21:07Z, Closed, value, 173
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:00Z, Open, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:00Z, Open, value, 12
-, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:12Z, Closed, value
+, , 0, 2020-01-01T08:00:00Z, 2020-01-01T08:30:00Z, 2020-01-01T08:24:12Z, Closed, value, 348
```

## Contact

- Author: Tom Hollingworth
- Email: tom.hollingworth@spruiktec.com
- Github: [@tomhollingworth](https://github.com/tomhollingworth)
- Influx Slack: [@tomhollingworth](https://influxdata.com/slack)
13 changes: 13 additions & 0 deletions stdlib/contrib/tomhollingworth/events/duration.flux
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
package events

// duration will calculate the duration between records
// for each record. The duration calculated is between
// the current record and the next. The last record will
// compare against either the stopColum (default: _stop)
// or a stop timestamp value.
//
// `timeColumn` - Optional string. Default '_time'. The value used to calculate duration
// `columnName` - Optional string. Default 'duration'. The name of the result column
// `stopColumn` - Optional string. Default '_stop'. The name of the column to compare the last record on
// `stop` - Optional Time. Use a fixed time to compare the last record against instead of stop column.
builtin duration : (<-tables: [A], ?unit: duration, ?timeColumn: string, ?columnName: string, ?stopColumn: string, ?stop: time) => [B] where A: Record, B: Record
Loading