You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Signal] feat: quantile=0.95 is removed from args of unmarshallJsonMulti(). Instead .withQuantile(q=0.95) modifier function is introduced, allowing multiple quantiles to be rendered from the single signal.
6
+
-[Signal] feat: introduce modifier signal functions: withLegendFormat, withHideNameInLegend, withName, withNameShort, withAgglevel, withAggFunction, withInstanceLabels, withInstanceLabelsMixin, withGroupLabels, withGroupLabelsMixin, withInterval, withAlertsInterval, withRangeFunction, withUnit. This boosts singals flexibility, allowing them to be modified just before rendering in panels/alerts.
7
+
-[Signal] feat: If signals of type=counter are rendered into tables (as columns etc...) their sum interval is changed from $__interval to $__range by default to accumulate sum of the full dashboard range.
8
+
-[Signal] feat: If multiple signals are being rendered into single panel, the panel is now populated with all signals' descriptions. All of them are appended with signals' short names.
9
+
-[Signal] chore: all renderer functions use this.signalName as name.
10
+
1
11
# 0.5.3
2
12
-[Panels] feat: generic.timeSeries.threshold now allow overriding colors.
Copy file name to clipboardExpand all lines: common-lib/common/signal/README.md
+55-28Lines changed: 55 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,42 +19,50 @@ Workflow to generate dashboards would be as follows:
19
19
20
20
### Modify functions
21
21
22
-
These functions modify one of the signal's property and then return signal back. Can be used as part of the builder pattern.
23
-
24
-
- withTopK(limit=25) - wrap signal expression into topk().
25
-
- withExprWrappersMixin(wrapper=[]) - wrap signal expression into additional function on top of existing wrappers.
26
-
- withOffset(offset) - add offset modifier to the expression.
27
-
- withFilteringSelectorMixin(mixin) - add additional selector to filteringSelector used.
28
-
- withQuantile(quantile=0.95) - add quantile modifier to the expression for histogram signals.
22
+
These functions modify one of the signal's properties and then return the signal back. They are designed to be used as part of a builder pattern, typically applied just before rendering panels or alert expressions.
23
+
24
+
-`withTopK(limit=25)` - wrap signal expression into `topk(limit, ...)`.
25
+
-`withExprWrappersMixin(wrapper=[])` - wrap signal expression into additional function(s) on top of existing wrappers.
26
+
-`withOffset(offset)` - add `offset` modifier to the expression.
27
+
-`withFilteringSelectorMixin(mixin)` - add additional selector to `filteringSelector` used.
28
+
-`withQuantile(quantile=0.95)` - set histogram quantile (also applies to signals produced by `unmarshallJsonMulti()`).
29
+
-`withLegendFormat(legendFormat)` - override automatically generated legend with a custom template.
30
+
-`withHideNameInLegend(hide=true)` - hide or show `nameShort` in the legend, while keeping aggregation labels and kept labels.
31
+
-`withName(name)` / `withNameShort(nameShort)` - override full panel title and legend/column label respectively.
32
+
-`withAgglevel(aggLevel)` / `withAggFunction(aggFunction)` - override aggregation level/function per signal.
33
+
-`withInstanceLabels(...)` / `withInstanceLabelsMixin(...)` / `withGroupLabels(...)` / `withGroupLabelsMixin(...)` - override or extend grouping labels on a per-signal basis.
34
+
-`withInterval(interval)` / `withAlertsInterval(interval)` - override evaluation interval used in expressions and alert rules.
35
+
-`withRangeFunction(rangeFunction)` - override rate/delta/increase function used for counter-type signals.
36
+
-`withUnit(unit)` - override the effective unit used when rendering the signal.
29
37
30
38
### Render functions
31
39
32
40
These functions return signals view as one of the Grafana panels, its part, or as alerts.
33
41
34
42
- Panel functions
35
-
- asTimeSeries() - renders TimeSeries panel with signals expression as the the first target and panel override.
36
-
- asStat() - renders Stat panel with signals expression as the the first target and panel override.
37
-
- asGauge() - renders Gauge panel with signals expression as the the first target and panel override.
38
-
- asStatusHistory() - renders StatusHistory panel with signals expression as the the first target and panel override.
39
-
- asTable(format=table|time_series) - renders Table panel with signals expression as the the first target and panel override.
43
+
-`asTimeSeries()` - renders TimeSeries panel with signals expression as the the first target and panel override.
44
+
-`asStat()` - renders Stat panel with signals expression as the the first target and panel override.
45
+
-`asGauge()` - renders Gauge panel with signals expression as the the first target and panel override.
46
+
-`asStatusHistory()` - renders StatusHistory panel with signals expression as the the first target and panel override.
47
+
-`asTable(format=table|time_series)` - renders Table panel with signals expression as the the first target and panel override.
40
48
- Parts of panels
41
-
- asPanelMixin() - add signals expression as the the target and panel override to the existing panel of any type, except a table.
42
-
- asTableColumn(format=table|time_series) - add signals expression as the the target and panel override to the existing panel created with .asTable() function.
43
-
- asTarget() - add signals expression as the the target to the existing panel.
44
-
- asTableTarget() - add signals expression as the the target to the existing panel, with format=table.
45
-
- asOverride() - add panel override to the existing panel.
46
-
- asPanelExpression() - add signals expression to the panels target.
49
+
-`asPanelMixin()` - add signals expression as the the target and panel override to the existing panel of any type, except a table.
50
+
-`asTableColumn(format=table|time_series)` - add signals expression as the the target and panel override to the existing panel created with .asTable() function.
51
+
-`asTarget()` - add signals expression as the the target to the existing panel.
52
+
-`asTableTarget()` - add signals expression as the the target to the existing panel, with format=table.
53
+
-`asOverride()` - add panel override to the existing panel.
54
+
-`asPanelExpression()` - add signals expression to the panels target.
47
55
- Prometheus rules (alerts)
48
-
- asRuleExpression() - add signals expression without any Grafana dynamic variables inside. Can be used for Prometheus alerts and rules.
56
+
-`asRuleExpression()` - add signals expression without any Grafana dynamic variables inside. Can be used for Prometheus alerts and rules.
49
57
50
-
## Autotransformations
58
+
## Opiniated autotransformations
51
59
52
60
### Expressions
53
-
When one of built-in functions are used (asTimeSeries, asPanelsMixin, asTarget...) signals' base expressions are converted automatically based on the type:
61
+
When one of built-in functions are used (asTimeSeries(), asPanelsMixin(), asTarget()...) signals' base expressions are converted automatically based on the type:
54
62
55
-
- counter: is wrapped into `<rangeFunction>(<base>[<interval>])`
63
+
- counter: is wrapped into `<rangeFunction>(<base>[<interval>])`. When rendered into tables (for example via `asTable()` / `asTableColumn()`), counters use the full dashboard range (`$__range`) instead of `$__interval` when summing values.
56
64
- gauge: no transformation
57
-
- histogram: wrapped into `histogram_quantile(0.95, <aggFunction>(rate(<base>[<interval>])) by (le,<agg>))`
65
+
- histogram: wrapped into `histogram_quantile(q, <aggFunction>(rate(<base>[<interval>])) by (le,<agg>))`, where `q` defaults to `0.95` and can be overridden with `withQuantile(quantile)`.
58
66
- info: no transformation
59
67
- raw: no transformation. You can write your own complex expression and make sure is kept as is.
60
68
@@ -75,7 +83,7 @@ Init level:
75
83
|instanceLabels| List of labels used to identify single entity or specific service instance. |*|`[instance]`|`['instance']`|
76
84
|interval| The interval used in `counters` and `histogram` auto transformations. |1m,5m.1h..., $__rate_interval, $__interval...|`5m`,|`$__rate_interval`|
77
85
|alertsInterval| The interval used in `counters` and `histogram` auto transformations in alerts. Grafana's $__rate_interval or similar are not supported. |1m,5m.1h...|`5m`,|`5m`|
|aggKeepLabels| Extra labels to keep when aggregating with by() clause. |`['pool','level']`|`[]`|
80
88
|aggFunction| A function used to aggregate metrics. |avg,min,max,sum...|`sum`|`avg`|
81
89
|varMetric| A Metric used for variables discovery. |*|`up`|`node_uname_info`|
@@ -95,10 +103,10 @@ Signal's level:
95
103
|type|Signal's type. Depending on the type, some opinionated autotransformations would happen with queries, units. |gauge,counter,histogram,info,raw|gauge|-|
96
104
|optional| Set this signal optional.| true,false | false | false|
97
105
|unit| Signal's units. |*|bytes|``|
98
-
|description| Signal's description. Used to populate panel's description. |*|CPU usage time in percent.|``|
106
+
|description| Signal's description. Used to populate panel's description; when multiple signals are rendered into a single panel, all signal descriptions are combined, each prefixed with the signal's short name. |*|CPU usage time in percent.|``|
99
107
|sourceMaps[].expr| Signal's BASE expression in simplest form. Simplified jsonnet templating is supported (see below). Depending on signal's type(not `raw`) could autotransform to different form. |*|network_bytes_received_total{%(queriesSelector)s}|-|
100
108
|sourceMaps[].exprWrappers| Signal's additional wrapper functions that could be added as an array, [<left_part>, <right_part>]. Functions would be applied AFTER any autotransformation takes place. |*|`['topk(10,',')']`|[]|
|aggLevel| Metrics aggregation level. When set to `aggKeepLabels`, aggregation is driven purely by `aggKeepLabels`. |none, instance, group, aggKeepLabels|`group`|`none`|
102
110
|aggFunction| A function used to aggregate metrics. |avg,min,max,sum...|`sum`|`avg`|
103
111
|sourceMaps[].aggKeepLabels| Extra labels to keep when aggregating with by() clause. |`['pool','level']`|`[]`|
104
112
|sourceMaps[].infoLabel| Only applicable to `info` metrics. Points to label name used to extract info. |*|-|-|
@@ -117,8 +125,9 @@ The following is supported in expressions and legends:
117
125
-`%(filteringSelector)s` - expands to filteringSelector matchers
118
126
-`%(groupLabels)s` - expands to groupLabels list
119
127
-`%(instanceLabels)s` - expands to instanceLabels list
120
-
-`%(agg)s` - expands to list of labels according to `aggLevel` and `aggKeepLabels` choosen
121
-
-`%(aggLegend)s` - expands to label in legend format (i.e. `{{<label1>}}`) according to `aggLevel` and `aggKeepLabels` choosen
128
+
-`%(agg)s` - expands to list of labels according to `aggLevel` and `aggKeepLabels` chosen
129
+
-`%(aggLegend)s` - expands to label in legend format (i.e. `{{<label1>}}`) according to `aggLevel` and `aggKeepLabels` chosen
130
+
-`%(aggLegendExcludeKeepLabels)s` - expands to label in legend format (i.e. `{{<label1>}}`) according to `aggLevel` only, excluding `aggKeepLabels`
122
131
-`%(aggFunction)s` - expands to aggregation function
123
132
-`%(interval)s` - expands to `interval` value
124
133
-`%(alertsInterval)s` - expands to `interval` value
@@ -312,6 +321,24 @@ g.dashboard.new('Device')
312
321
)
313
322
```
314
323
324
+
## Example 4: Create table from signals
325
+
326
+
Use one signal to create the table with `asTable()`, then add more columns with `asTableColumn()` (from kafka-observ-lib):
327
+
328
+
```jsonnet
329
+
signals.consumerGroup.consumerGroupConsumeRate.asTable(name='Consumer group overview', format='time_series')
0 commit comments