feat: added LineChartWidget

steadybit · Oct 22, 2024 · 7c44fc5 · 7c44fc5
1 parent 63fe685
commit 7c44fc5
Show file tree

Hide file tree

Showing 8 changed files with 653 additions and 141 deletions.
diff --git a/docs/img/widgets/line-chart.png b/docs/img/widgets/line-chart.png
diff --git a/docs/widgets.md b/docs/widgets.md
@@ -5,21 +5,21 @@ To enhance the user experience, ActionKit also supports the extension of the exp
 Supported widgets types:
 
 * [State Over Time](#state-over-time)
+* [Line Chart](#line-chart)
 * [Log Widget](#log-widget)
 * [Markdown Widget](#markdown-widget)
 
+All widgets require two components to function:
+
+- Metrics or Logs containing the information. These are returned by the action during experiment execution by the various endpoints, e.g., the `status` endpoint.
+- Static configuration describes how the widget should filter, aggregate, and label the metrics for user presentation. This configuration is part of the `ActionDescription` and is returned by the `describe` endpoint.
+
 ## State Over Time
 
 This widget helps visualize how the state of a system or component evolved. For example, to show a Kubernetes pod's readiness state or the state of the monitoring system's alarms. The screenshot below depicts how the [Datadog extension](https://github.com/steadybit/extension-datadog) uses this widget type to visualize the state of [Datadog monitors](https://docs.datadoghq.com/monitors/) over time.
 
 ![An run view widget visualizing the status of a Datadog monitor over time](./img/widgets/state-over-time.png)
 
-The state over time widget requires two components to function:
-
-- Metrics containing information about the status at any one time.
-- Static configuration describes how to filter, aggregate and label the metrics for user presentation.
-
-
 ### Configuration
 
 The widget configuration describes from which metric fields Steadybit should retrieve information. More specifically:
@@ -29,8 +29,8 @@ The widget configuration describes from which metric fields Steadybit should ret
 - `state.from`: Maps to the name of a metric field containing the current state at any time. Supported values for this field are:
   - `danger` - ![#f4857d](https://placehold.co/10x20/f4857d/f4857d.png)![#ed5d50](https://placehold.co/10x20/ed5d50/ed5d50.png)
   - `warn` - ![#F9D34C](https://placehold.co/10x20/F9D34C/F9D34C.png)![#F99F4C](https://placehold.co/10x20/F99F4C/F99F4C.png)
-  - `info` - ![#d5d8e0](https://placehold.co/10x20/d5d8e0/d5d8e0.png)![#cbced9](https://placehold.co/10x20/cbced9/cbced9.png)
   - `success` - ![#4ab3ae](https://placehold.co/20x20/4ab3ae/4ab3ae.png)
+  - `info` - ![#d5d8e0](https://placehold.co/10x20/d5d8e0/d5d8e0.png)![#cbced9](https://placehold.co/10x20/cbced9/cbced9.png)
 - `tooltip.from`: Maps to the name of a metric field containing the current tooltip at any time.
 - `url.from`: Maps to the name of a metric field containing a URL. When available, it causes a chart segment to turn into a hyperlink.
 - `value.hide`: Controls whether the metric values carry meaning and should be shown.
@@ -68,7 +68,7 @@ The following snippet is an example depicting the Datadog extension's configurat
 
 ### Metrics
 
-You can provide data points for this widget through metrics. You can define metrics through various ActionKit endpoints, e.g., the `status` endpoint. The following snippet is an example of a metric generated by the Datadog extension.
+You need to provide data points for this widget through metrics. You can define metrics through various ActionKit endpoints, e.g., the `status` endpoint. The following snippet is an example of a metric generated by the Datadog extension.
 
 ```json
 {
@@ -89,6 +89,120 @@ You can provide data points for this widget through metrics. You can define metr
 }
 ```
 
+## Line Chart
+
+This widget helps visualize value in a line chart. For example, to show response times of an HTTP Endpoint. The screenshot below shows how the [HTTP extension](https://github.com/steadybit/extension-http) uses this widget type.
+
+![An run view widget visualizing the HTTP response times of a given url](./img/widgets/line-chart.png)
+
+### Configuration
+
+The widget configuration describes from which metric fields Steadybit should retrieve information. More specifically:
+
+- `Identity`
+  - `Metric` & `From`: Which metrics should be considered to be part of the same line chart. The `identity.metric` is the name of the metric, `identity.from` is the name of the metric attribute which will form a line.
+  - `Mode`: The mode of the identity. Supported values are:
+    - `widget_per_value`: Each value returned by the attribute specified by `identity.from` will be a separate widget in the run view.
+    - `select`: Each value returned by the attribute specified by `identity.from` can be selected in the header of a single widget in the run view.
+- `Grouping`: Optional - can be used to group datapoints and color them. If not provided, all values will be shown in the same color.
+  - `ShowSummary`: Controls whether a summary of the values should be shown in a pie-chart.
+  - `Groups`: A list of groups that should be shown in the line chart. Each group has a title, color, and a matcher. The matcher specifies how to filter the values of the metric to be part of the group.
+    - `Color`:
+      - `danger` - ![#f4857d](https://placehold.co/20x20/f4857d/f4857d.png)
+      - `warn` - ![#F9D34C](https://placehold.co/20x20/F9D34C/F9D34C.png)
+      - `success` - ![#4ab3ae](https://placehold.co/20x20/4ab3ae/4ab3ae.png)
+      - `info` - ![#d5d8e0](https://placehold.co/20x20/d5d8e0/d5d8e0.png)
+    - `Matcher`:'
+      - `action_kit_api.LineChartWidgetGroupMatcherFallback`: All values that do not match any other group will be part of this group.
+      - `action_kit_api.LineChartWidgetGroupMatcherNotEmpty`: All values with a non empty attribute specified by `key` will be part of this group.
+      - `action_kit_api.LineChartWidgetGroupMatcherKeyEqualsValue`: `key` with a specific `value` will be part of this group.
+- `Tooltip`: Optional - can be used to configure the tooltip of the line chart.
+  - `MetricValueTitle`: The value of the metric specified by `identity` is always shown in the tooltip. `MetricValueTitle` specifies the title of the metric value.
+  - `MetricValueUnit`: The unit of the value for the y-axis.
+  - `AdditionalContent`: A list of additional content that should be shown in the tooltip. Each additional content has a title and a from attribute. Attribute which don't exist in the metric will be ignored.
+
+The following snippet is an example of the widget definition in extension-http.
+
+```go
+return action_kit_api.ActionDescription{
+...
+    Widgets: extutil.Ptr([]action_kit_api.Widget{
+        action_kit_api.LineChartWidget{
+            Type:  action_kit_api.ComSteadybitWidgetLineChart,
+            Title: "HTTP Responses",
+            Identity: action_kit_api.LineChartWidgetIdentityConfig{
+                MetricName: "response_time",
+                From:       "url",
+                Mode:       action_kit_api.ComSteadybitWidgetLineChartIdentityModeWidgetPerValue,
+            },
+            Grouping: extutil.Ptr(action_kit_api.LineChartWidgetGroupingConfig{
+                ShowSummary: extutil.Ptr(true),
+                Groups: []action_kit_api.LineChartWidgetGroup{
+                    {
+                        Title: "Successul",
+                        Color: "success",
+                        Matcher: action_kit_api.LineChartWidgetGroupMatcherFallback{
+                            Type: action_kit_api.ComSteadybitWidgetLineChartGroupMatcherFallback,
+                        },
+                    },
+                    {
+                        Title: "Failure",
+                        Color: "danger",
+                        Matcher: action_kit_api.LineChartWidgetGroupMatcherNotEmpty{
+                            Type: action_kit_api.ComSteadybitWidgetLineChartGroupMatcherNotEmpty,
+                            Key:  "error",
+                        },
+                    },
+                    {
+                        Title: "Unexpected Status",
+                        Color: "warn",
+                        Matcher: action_kit_api.LineChartWidgetGroupMatcherKeyEqualsValue{
+                            Type:  action_kit_api.ComSteadybitWidgetLineChartGroupMatcherKeyEqualsValue,
+                            Key:   "expected_http_status",
+                            Value: "false",
+                        },
+                    },
+                    ...
+                },
+            }),
+            Tooltip: extutil.Ptr(action_kit_api.LineChartWidgetTooltipConfig{
+                MetricValueTitle: extutil.Ptr("Response Time"),
+                MetricValueUnit:  extutil.Ptr("ms"),
+                AdditionalContent: []action_kit_api.LineChartWidgetTooltipContent{
+                    {
+                        From:  "error",
+                        Title: "Error",
+                    },
+                    {
+                        From:  "http_status",
+                        Title: "HTTP Status",
+                    },
+                },
+            }),
+        },
+    })
+```
+
+### Metrics
+
+You need to provide data points for this widget through metrics. You can define metrics through various ActionKit endpoints, e.g., the `status` endpoint. The following snippet is an example of a metric generated by the HTTP extension.
+
+```json
+{
+  "metrics": [
+    {
+      "name": "response_time",
+      "metric": {
+        "url": "https://www.steadybit.com",
+        "http_status": "200",
+        "response_time_constraints_fulfilled": "false"
+      },
+      "timestamp": "2024-10-04T19:16:52+0100",
+      "value": 156
+    }
+  ]
+}
+```
 
 ## Log Widget
 
@@ -107,7 +221,7 @@ The following snippet is an example depicting the Kubernetes extension's configu
 
 ```go
 return action_kit_api.ActionDescription{
-	...
+    ...
     Widgets: extutil.Ptr([]action_kit_api.Widget{
         action_kit_api.LogWidget{
             Type:    action_kit_api.ComSteadybitWidgetLog,
@@ -155,7 +269,7 @@ Example:
 
 ```go
 return action_kit_api.ActionDescription{
-	...
+    ...
     Widgets: extutil.Ptr([]action_kit_api.Widget{
         action_kit_api.MarkdownWidget{
             Type:    action_kit_api.ComSteadybitWidgetMarkdown,

diff --git a/go/action_kit_api/CHANGELOG.md b/go/action_kit_api/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## 2.9.4
+
+- adding `LineChartWidget`
+
 ## 2.9.3
 
 - adding `technology` to `ActionDescription`