diff --git a/content/en/dashboards/guide/_index.md b/content/en/dashboards/guide/_index.md index b1f9b8f0b9cb4..6040aed786326 100644 --- a/content/en/dashboards/guide/_index.md +++ b/content/en/dashboards/guide/_index.md @@ -32,6 +32,7 @@ cascade: {{< nextlink href="/dashboards/guide/apm-stats-graph" >}}Configuring an APM stats graph{{< /nextlink >}} {{< nextlink href="/dashboards/guide/version_history" >}}Version History{{< /nextlink >}} {{< nextlink href="/dashboards/guide/graphing_json/" >}}Graphing with JSON{{< /nextlink >}} + {{< nextlink href="dashboards/guide/getting_started_with_wildcard_widget" >}}Getting started with the Wildcard Widget{{< /nextlink >}} {{< nextlink href="/dashboards/guide/using_vega_lite_in_wildcard_widgets/" >}}Using Vega-Lite with Wildcard Widgets in Datadog{{< /nextlink >}} {{< nextlink href="/dashboards/guide/wildcard_examples" >}}Wildcard Widget Examples{{< /nextlink >}} {{< nextlink href="/dashboards/guide/graphing_json/" >}}Graphing with JSON diff --git a/content/en/dashboards/guide/getting_started_with_wildcard_widget.md b/content/en/dashboards/guide/getting_started_with_wildcard_widget.md new file mode 100644 index 0000000000000..9a9c1d6e6af99 --- /dev/null +++ b/content/en/dashboards/guide/getting_started_with_wildcard_widget.md @@ -0,0 +1,190 @@ +--- +title: Getting Started with the Wildcard Widget +further_reading: +- link: "/dashboards/widgets/wildcard/" + tag: "Documentation" + text: "Wildcard widget Overview" +- link: "/dashboards/guide/wildcard_examples/" + tag: "Guide" + text: "Wildcard widget example visualizations" +- link: "/dashboards/guide/using_vega_lite_in_wildcard_widgets/" + tag: "Guide" + text: "Using Vega-Lite in Wildcard widgets" +--- + +## Overview + +The Wildcard widget is a powerful and flexible visualization tool in Datadog that lets you build custom visual representations using the [Vega-Lite grammar][1]. + +### Tutorial Objectives + +By the end of this tutorial, you will be able to: + +* Use Vega-Lite concepts to define visualizations in Wildcard widgets. +* Import a query from an existing widget. + +### Prerequisites + +* A Datadog account with access to [Notebooks][2] or [Dashboards][3]. +* You have telemetry such as APM trace data or request duration metrics. +* You are familiar with basic Datadog widgets and dashboards and can [add a widget and edit it][4]. + +## Step 1: Import an existing query + +Rather than starting from scratch, import a request from an existing widget. Copy the query from a widget you're interested in exploring further (such as a Top List). To get started, you can use widgets from your [prebuilt dashboards][5]. + +1. Navigate to an existing dashboard with a useful widget (Top List of database queries). +2. Use the widget menu or use the keyboard shortcut (Ctrl/CMD + C) to copy the widget. +3. In a new dashboard, add a Wildcard widget. +4. In the editor, clear the default query ({{< img src="/icons/cancel-circle.png" alt="X icon to clear the query" inline="true" width="40px">}}). +5. Paste the copied request with Ctrl/Cmd + V. The query and associated fields carry over automatically. + +{{< img src="/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/import_widget_walkthrough.mp4" alt="Walkthrough of importing a widget query into the Wildcard widget in Datadog" video=true >}} + +## Step 2: Refine the query + +In the query editor: + +1. Expand the **Data Preview** to identify the fields returned from the query. +2. Next to your query, click **As** to add an alias to your query. This adds clarity, for example, rename `p50:trace.http.request{*} by {service}`→ `p50`. + +{{< img src="/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/refine_query_walkthrough.mp4" alt="Walkthrough of refining a query in the Wildcard widget, including renaming fields and adding a P95 formula" video=true >}} + +## Step 3: Auto-generate a visualization + +At the top of the query editor: + +1. Click the **Define Visual** tab. +2. Press Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows/Linux) to open the **Command Palette**. +3. Select **Auto-select chart**. + +{{< img src="/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/command_palette.mp4" alt="Your image description" video=true >}} + +Datadog automatically creates a visualization based on your query. + +
+Tip: Use the Command Palette (Cmd + Shift + P) to auto-select a chart type based on your query, add or edit encodings, or rotate axes/switch chart types. +
+ +{{% collapse-content title="Guided example of Auto-generate" level="h4" expanded=false %}} +1. In a new Wildcard widget, click the JSON tab of the query editor and paste the following query: +{{< img src="path/to/your/image-name-here.png" alt="Your image description" style="width:100%;" >}} + ```json + { + "response_format": "scalar", + "queries": [ + { + "query": "avg:system.cpu.user{*} by {env}", + "data_source": "metrics", + "name": "query1", + "aggregator": "last" + }, + { + "query": "max:system.cpu.user{*} by {env}", + "data_source": "metrics", + "name": "query2", + "aggregator": "last" + } + ], + "formulas": [ + { "formula": "query1" }, + { "formula": "query2" } + ], + "sort": { + "count": 15, + "order_by": [ + { + "type": "formula", + "index": 0, + "order": "desc" + } + ] + } + } + ``` +1. Click **Save Edits**. +2. At the top of your query editor, click the **Define Visual** tab. +3. Press Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows/Linux) to open the **Command Palette**. +4. Select **Auto-select chart**. The graph should automatically change from a bar chart to a scatterplot. + +{{% /collapse-content %}} + +## Step 4: Add a context menu + +To add interactivity to your graph, enable context menu support. + +1. In the visual JSON editor, copy and paste the following example bar chart widget to see how to add a context menu. This example includes a Tooltip and Context Menu configurations. + {{< highlight json "hl_lines=37-41" >}} +{ + "$schema": "https://vega.github.io/schema/vega-lite/v5.json", + "description": "Bar chart showing CPU usage by environment with Datadog context menu support", + "data": { + "name": "table1" + }, + "mark": "bar", + "encoding": { + "x": { + "field": "env", + "type": "nominal", + "sort": "-y", + "title": "Environment" + }, + "y": { + "field": "query1", + "type": "quantitative", + "title": "CPU Usage (%)" + }, + "tooltip": [ + { + "field": "env", + "type": "nominal" + }, + { + "field": "query1", + "type": "quantitative", + "title": "CPU Usage (%)" + }, + { + "field": "timestamp", + "type": "temporal", + "title": "Timestamp" + } + ] + }, + "params": [ + { + "name": "datadogPointSelection", + "select": "point" + } + ] +} +{{< /highlight >}} +2. Run and save the widget. +3. On your dashboard, find the widget you just created and click any data point in graph to bring up a **context menu**. + +For more information, see [Using Vega-Lite with Wildcard Widgets in Datadog][6]. + +## Next Steps + +Wildcard widgets support a wide range of customizations, including: +- [Adjusting the thickness of lines to show weight and intensity][7] +- [Adding images to visually represent values][8] +- [Layering visualizations for richer context][9] + +For more inspiration, see [Datadog Wildcard widget examples][10] and [Vega-Lite Examples][11]. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://vega.github.io/vega-lite/ +[2]: https://app.datadoghq.com/notebook/list +[3]: https://app.datadoghq.com/dashboard/lists?p=1 +[4]: /dashboards/widgets/wildcard/#setup +[5]: https://app.datadoghq.com/dashboard/lists/preset/3?p=1 +[6]: /dashboards/guide/using_vega_lite_in_wildcard_widgets/#context-menu-and-context-links +[7]: https://vega.github.io/vega-lite/examples/trail_color.html +[8]: https://vega.github.io/vega-lite/examples/isotype_bar_chart_emoji.html +[9]: https://vega.github.io/vega-lite/examples/layer_line_rolling_mean_point_raw.html +[10]: /dashboards/guide/wildcard_examples/ +[11]: https://vega.github.io/vega-lite/examples/ diff --git a/content/en/dashboards/guide/using_vega_lite_in_wildcard_widgets.md b/content/en/dashboards/guide/using_vega_lite_in_wildcard_widgets.md index 07362fd4b3dbe..1c9b999dc41f2 100644 --- a/content/en/dashboards/guide/using_vega_lite_in_wildcard_widgets.md +++ b/content/en/dashboards/guide/using_vega_lite_in_wildcard_widgets.md @@ -28,9 +28,9 @@ Customized color, font, spacing, and other design settings are available. These While you can create custom color palettes using hex codes, using the Datadog color palette ensures automated switching between light and dark modes. -Datadog offers additional color palettes beyond the public Vega color schemes, including: -- `dog_classic_area` -- `datadog16` +Datadog offers additional color palettes beyond the public Vega color schemes, including: +- `dog_classic_area` +- `datadog16` - `hostmap_blues` {{< whatsnext desc="Additional resources:" >}} @@ -74,11 +74,11 @@ Next, wherever you set a `format` key, use `formatType: hoverFormatter` and defi {{< /highlight >}} -{{% /collapse-content %}} +{{% /collapse-content %}} The second element of the "units" array represents a "per" unit, such as in "bits per second." Units should be provided in singular form (such as, "second" instead of "seconds"). Regular number formatting, such as specifying precision, scientific notation, or integers, is possible using [d3-format][2] tokens. Two popular formats include: -* `~s`: scientific prefix (for example, 2000 -> 2k), with trailing zeros removed +* `~s`: scientific prefix (for example, 2000 -> 2k), with trailing zeros removed * `.2f`: floating point to 2 decimals The `hoverFormatter` may also be called in [Vega expressions][3]. This function has the signature of: @@ -125,7 +125,7 @@ For example, you can use the following configuration to specify a height increme {{< /highlight >}} -{{% /collapse-content %}} +{{% /collapse-content %}} ## Referencing Datadog Data in Vega-Lite @@ -137,13 +137,13 @@ Whenever possible, Datadog widgets preserve tag names from your request's "group ### Additional Field Information -- Timeseries requests include a `_time` field for timestamps in milliseconds. -- Histogram request rows consist of three fields: `start`, `end`, and `count`. +- Timeseries requests include a `_time` field for timestamps in milliseconds. +- Histogram request rows consist of three fields: `start`, `end`, and `count`. - List request responses vary by data source. Use the [DataPreview][6] to determine available fields. ### Field names with special characters -Special considerations apply to field names that contain non-alphanumeric characters. Datadog Metrics tags [prohibit most non-alphanumeric characters][7]. However, not all products have this constraint and they allow characters in attribute names that may have dual meanings in Vega-Lite. These characters include square brackets `[]` and periods `.` which are used to access nested properties in object-shaped data. They need to be escaped because the backend flattens the data before returning it to you for /scalar and /timeseries data. +Special considerations apply to field names that contain non-alphanumeric characters. Datadog Metrics tags [prohibit most non-alphanumeric characters][7]. However, not all products have this constraint and they allow characters in attribute names that may have dual meanings in Vega-Lite. These characters include square brackets `[]` and periods `.` which are used to access nested properties in object-shaped data. They need to be escaped because the backend flattens the data before returning it to you for /scalar and /timeseries data. To ensure these characters are interpreted correctly by the Wildcard widget, you must escape these characters with `\\`. For example, when using the RUM query field `@view.name`, write it as `@view\\.name` in the Vega-Lite specification. @@ -155,7 +155,7 @@ With Datadog widgets, you have the ability to click on a graph datapoint to open To enable the context menu feature, include the following parameters in your Vega-Lite configuration: -``` +```json "params": [ { "name": "datadogPointSelection", @@ -164,6 +164,44 @@ To enable the context menu feature, include the following parameters in your Veg ] ``` +If the graph contains the `layer` key, the param must be added to one of the layer objects, not to the root of the spec. This is because parameters at the root are applied to all layers, which can cause conflicts. To avoid this, give each layer a uniquely named parameter by prefixing it with`datadogPointSelection_`, such as`datadogPointSelection_squares` or`datadogPointSelection_circles`. For example: + +```json +"layer": [ + { + "mark": "line", + "encoding": { + "x": { "field": "_time", "type": "temporal" }, + "y": { "field": "cpu", "type": "quantitative" }, + "color": { "field": "host", "type": "nominal" }, + "opacity": { "value": 0.4 } + }, + "params": [ + { + "name": "datadogPointSelection_lines", + "select": { "type": "point", "on": "click" } + } + ] + }, + { + "mark": "point", + "encoding": { + "x": { "field": "_time", "type": "temporal" }, + "y": { "field": "cpu", "type": "quantitative" }, + "color": { "field": "host", "type": "nominal" }, + "size": { "value": 50 } + }, + "params": [ + { + "name": "datadogPointSelection_circles", + "select": { "type": "point", "on": "click" } + } + ] + } +], +``` + + After you enable this feature, you can click on datapoints in the widget to open a context menu. Use the graph context menu with the context links of the graph editor. Context links bridge dashboard widgets with other pages in Datadog, as well as the third-party applications you have integrated into your workflows. For more information, see [Context Links][9]. You can also add dynamic custom links through the [`href` encoding][10]. This is useful if you do not need a full context menu of choices. diff --git a/content/en/dashboards/widgets/wildcard.md b/content/en/dashboards/widgets/wildcard.md index 8e39ab832e9a3..aaea741ef602b 100644 --- a/content/en/dashboards/widgets/wildcard.md +++ b/content/en/dashboards/widgets/wildcard.md @@ -2,6 +2,9 @@ title: Wildcard Widget widget_type: wildcard further_reading: +- link: "dashboards/guide/getting_started_with_wildcard_widget/" + tag: "Guide" + text: "Getting Started with the Wildcard Widget Tutorial" - link: "/dashboards/guide/using_vega_lite_in_wildcard_widgets/" tag: "Documentation" text: "Learn more about using Vega-Lite with Wildcard widgets" @@ -11,11 +14,14 @@ further_reading: - link: "https://vega.github.io/vega-lite/tutorials/getting_started.html" tag: "Vega Tutorial" text: "Introduction to Vega-Lite" +- link: "https://www.datadoghq.com/blog/wildcard-widget/" + tag: "Blog" + text: "Build Vega-Lite visualizations natively in Datadog with the Wildcard widget" --- ## Overview -The Wildcard widget in Datadog extends the flexibility of the [open-source Vega-Lite][1] "Grammar of Graphics" language, and integrates it with the Datadog platform. The Wildcard widget allows you to create graphs that are not available within native Datadog widgets and query systems. +The Wildcard widget in Datadog extends the flexibility of the [open-source Vega-Lite][1] "Grammar of Graphics" language, and integrates it with the Datadog platform. The Wildcard widget allows you to create graphs that are not available within native Datadog widgets and query systems. Use the Wildcard widget in [Dashboards][2] and [Notebooks][3]. @@ -23,7 +29,7 @@ Use the Wildcard widget in [Dashboards][2] and [Notebooks][3]. Datadog recommends using an existing [dashboard widget][4] to meet your use case. All native widgets have design and performance optimizations which are not available in the Wildcard widget. For known limitations, see the [Additional information](#additional-information) section. -However, if none of the Datadog widgets meets your visualization needs, a Wildcard widget is a fast way to get a new capability added to your Dashboards without waiting for a new feature or graph type to be added. +However, if none of the Datadog widgets meets your visualization needs, a Wildcard widget is a fast way to get a new capability added to your Dashboards without waiting for a new feature or graph type to be added. 1. **Don't start from scratch**. Vega-Lite maintains a public gallery with over [150 official examples][5]. If you're not sure what type of graph you want to use, fork an existing example to test the visualization. Use Vega-Lite over Vega for simplicity and ease of debugging. 1. **Test the Wildcard widget**. The flexibility of the Wildcard widget comes with the risk of creating slow, unappealing, or inconsistent visualizations. Test the Wildcard widget on a scratchpad or empty dashboard before adding Wildcard widgets to production. @@ -31,20 +37,20 @@ However, if none of the Datadog widgets meets your visualization needs, a Wildca ## Setup -After you create a Wildcard widget, you can configure the widget either as a [new configuration](#configure-a-new-wildcard-widget) or by [importing a configuration from an existing widget](#import-data-from-an-existing-widget). +After you create a Wildcard widget, you can configure the widget either as a [new configuration](#configure-a-new-wildcard-widget) or by [importing a configuration from an existing widget](#import-data-from-an-existing-widget). ### Configure a new Wildcard widget 1. [Check native widgets][4]. See if a Datadog widget can fulfill your requirements. 1. If no Datadog widget meets your requirements, in a new or pre-existing dashboard, click **Add Widgets**. -1. Click and drag the Wildcard Widget icon from the widget tray. +1. Click and drag the Wildcard Widget icon from the widget tray. 1. Select from the **Request Type** dropdown. For more information on Scalar and Timeseries types, see the [Formulas Scalar vs. Formulas Timeseries](#formulas-scalar-vs-formulas-timeseries) section of this page. -1. Copy a Vega-Lite Definition from the [public gallery][5] to find a starter Vega-Lite specification. +1. Copy a Vega-Lite Definition from the [public gallery][5] to find a starter Vega-Lite specification. 1. Open the Wildcard widget [full screen editor][6] and click **Define Visual**. 1. Paste the copied Vega-Lite definition. -1. Click **Run** to apply your configuration changes, see a preview of the visualization, and iterate on your design. +1. Click **Run** to apply your configuration changes, see a preview of the visualization, and iterate on your design. **Note**: You must click **Run** to add your changes, however this does not save your configuration. -1. (Optional) Debug Vega-Lite specification mismatches with [Data Preview](#data-preview). Make sure the query in your Vega-Lite specification maps to the Datadog query. +1. (Optional) Debug Vega-Lite specification mismatches with [Data Preview](#data-preview). Make sure the query in your Vega-Lite specification maps to the Datadog query. 1. Click **Save**. #### Formulas Scalar vs. Formulas Timeseries @@ -53,13 +59,13 @@ In Datadog dashboards, visualizations are powered by a multiple _request types_, **Timeseries** : This data format is designed to display how your data changes over time. - - **Use-cases**: It's ideal for monitoring metrics that fluctuate, such as CPU usage, memory consumption, or request rates. It helps identify trends, patterns, and anomalies over a specified time range. + - **Use-cases**: It's ideal for monitoring metrics that fluctuate, such as CPU usage, memory consumption, or request rates. It helps identify trends, patterns, and anomalies over a specified time range. **Scalar** : This data format aggregates your data producing 1 value per "group". The scalar format is used for the toplist, treemap, pie chart, and table widget, where each group refers to 1 shape (bar, rectangle, slice, or row respectively) in your graph. - **Use-cases**: It's best for displaying key performance indicators (KPIs) or summary statistics such as averages, sums, or percentiles. It provides a summary view of the current state or a specific metric. If you are not describing changes over time, use Scalar. -The Timeseries data format emphasizes data trends over time, while the Scalar format focuses on presenting single, computed values for quick assessments. Choose the Timeseries type if you need to visualize time on an axis or require individual time buckets. If not visualizing against time, select the Scalar type for performance. +The Timeseries data format emphasizes data trends over time, while the Scalar format focuses on presenting single, computed values for quick assessments. Choose the Timeseries type if you need to visualize time on an axis or require individual time buckets. If not visualizing against time, select the Scalar type for performance. **Note**: The "Formulas" prefix is used specifically for Scalar and Timeseries formats because they are compatible with the [Functions API][18]. The other formats, such as Histogram and List, do not support this API. @@ -74,7 +80,7 @@ The Timeseries data format emphasizes data trends over time, while the Scalar fo {{< img src="/dashboards/widgets/wildcard/command_palette.png" alt="Command palette modal showing the ability to search commands and autoselect chart" style="width:100%;" >}} -The command palette provides quick access to Wildcard widget tools. Activate with `cmd + shift + p` or click the info icon at the top of the page. +The command palette provides quick access to Wildcard widget tools. Activate with `cmd + shift + p` or click the info icon at the top of the page. ## Data Preview @@ -82,7 +88,7 @@ The command palette provides quick access to Wildcard widget tools. Activate wit The Data Preview table shows the response, fields, and values from your data request that are available to use in your Vega-lite specification. To access, click the arrow at the bottom of the Wildcard widget editor to *Show data preview*. There are three types of tables in the preview: - Request Rows: Displays your actual data. -- Request Columns: Displays column summary statistics and data types. +- Request Columns: Displays column summary statistics and data types. - Internal Tables: Displays transformed data stored by Vega-Lite. ## Map Datadog data to Vega-Lite specifications @@ -93,7 +99,7 @@ To see how Datadog values map to the Vega-Lite specification, start with the exa {{< img src="/dashboards/widgets/wildcard/example_configuration_query.png" alt="Example widget configuration metric query for system.cpu.user grouped by env" style="width:100%;" >}} -Click on the **Define Visual** tab to view how this query maps to Vega-Lite. Open the Data Preview panel and notice the matching **query1** and **env** fields listed in the Vega-Lite specification and the Data Preview column. +Click on the **Define Visual** tab to view how this query maps to Vega-Lite. Open the Data Preview panel and notice the matching **query1** and **env** fields listed in the Vega-Lite specification and the Data Preview column. {{< highlight json "hl_lines=8 12" >}} { @@ -138,7 +144,7 @@ The Wildcard Widget supports data requests from all data sources supported in na | Scalar Requests | Change, Pie Chart, Query Value, Scatter Plot, Table, Treemap, Top List, Distribution (of groups), Geomap | | Timeseries Requests | Timeseries, Heatmap | | Distribution Requests | Distribution (of points) | -| List requests | All “event” oriented data in the List widget | +| List requests | All “event” oriented data in the List widget | ## Additional information ### Choosing Between Vega and Vega-Lite diff --git a/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/cancel-circled.svg b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/cancel-circled.svg new file mode 100644 index 0000000000000..eb31680396fa2 --- /dev/null +++ b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/cancel-circled.svg @@ -0,0 +1,4 @@ + + + + diff --git a/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/command_palette.mp4 b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/command_palette.mp4 new file mode 100644 index 0000000000000..8785921b90e69 Binary files /dev/null and b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/command_palette.mp4 differ diff --git a/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/import_widget_walkthrough.mp4 b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/import_widget_walkthrough.mp4 new file mode 100644 index 0000000000000..477cedde2e4cf Binary files /dev/null and b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/import_widget_walkthrough.mp4 differ diff --git a/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/refine_query_walkthrough.mp4 b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/refine_query_walkthrough.mp4 new file mode 100644 index 0000000000000..fbe63dd3200da Binary files /dev/null and b/static/images/dashboards/guide/analyze_p50_vs_p95_latency_with_the_wildcard_widget/refine_query_walkthrough.mp4 differ diff --git a/static/images/icons/cancel-circle.png b/static/images/icons/cancel-circle.png new file mode 100644 index 0000000000000..70524b0368c82 Binary files /dev/null and b/static/images/icons/cancel-circle.png differ