diff --git a/content/en/dashboards/guide/_index.md b/content/en/dashboards/guide/_index.md index b1f9b8f0b9cb4..a9a646a140dd1 100644 --- a/content/en/dashboards/guide/_index.md +++ b/content/en/dashboards/guide/_index.md @@ -12,40 +12,54 @@ cascade: subcategory: Graphing Guides --- -{{< whatsnext desc="General Guides:" >}} - {{< nextlink href="dashboards/guide/maintain-relevant-dashboards" >}}Best practices for maintaining relevant dashboards{{< /nextlink >}} - {{< nextlink href="dashboards/guide/how-to-graph-percentiles-in-datadog" >}}Graphing percentiles in Datadog{{< /nextlink >}} +### Core Dashboard Concepts & Best Practices + +{{< whatsnext desc="Start here for foundational skills and broad strategies for effective dashboards." >}} + {{< nextlink href="dashboards/guide/maintain-relevant-dashboards" >}}Best practices for maintaining relevant dashboards{{< /nextlink >}} + {{< nextlink href="dashboards/guide/quick-graphs" >}}Quick Graphs{{< /nextlink >}} {{< nextlink href="dashboards/guide/query-to-the-graph" >}}Query to the Graph{{< /nextlink >}} + {{< nextlink href="dashboards/guide/powerpacks-best-practices" >}}Powerpacks best practices{{< /nextlink >}} + {{< nextlink href="dashboards/guide/tv_mode" >}}Using TV mode for Dashboards{{< /nextlink >}} +{{< /whatsnext >}} + +### Building & Customizing Visualizations + +{{< whatsnext desc="Create rich, usable dashboards with interactive features and meaningful visual styles." >}} {{< nextlink href="dashboards/guide/widget_colors" >}}Selecting the right colors for your graphs{{< /nextlink >}} - {{< nextlink href="dashboards/guide/compatible_semantic_tags" >}}Compatible semantic tags{{< /nextlink >}} + {{< nextlink href="dashboards/guide/unit-override" >}}Unit override{{< /nextlink >}} {{< nextlink href="dashboards/guide/custom_time_frames" >}}Custom time frames{{< /nextlink >}} - {{< nextlink href="dashboards/guide/quick-graphs" >}}Quick Graphs{{< /nextlink >}} {{< nextlink href="dashboards/guide/context-links" >}}Context Links{{< /nextlink >}} - {{< nextlink href="dashboards/guide/unit-override" >}}Unit override{{< /nextlink >}} - {{< nextlink href="dashboards/guide/how-to-use-terraform-to-restrict-dashboards" >}}Using Terraform to restrict the editing of a dashboard{{< /nextlink >}} - {{< nextlink href="dashboards/guide/is-read-only-deprecation" >}}Dashboards API: Migrate from is_read_only by December 13, 2024{{< /nextlink >}} + {{< nextlink href="dashboards/guide/version_history" >}}Version History{{< /nextlink >}} {{< nextlink href="dashboards/guide/embeddable-graphs-with-template-variables" >}}Embeddable graphs with template variables{{< /nextlink >}} {{< nextlink href="dashboards/guide/unable-to-iframe" >}}Why am I unable to iFrame certain HTTPS URLs?{{< /nextlink >}} - {{< nextlink href="dashboards/guide/powerpacks-best-practices" >}}Powerpacks best practices{{< /nextlink >}} +{{< /whatsnext >}} + +### Advanced Widgets, Data Sources & Techniques + + +{{< whatsnext desc="Use advanced tools and techniques to power up your dashboards." >}} + {{< nextlink href="dashboards/guide/how-to-graph-percentiles-in-datadog" >}}Graphing percentiles in Datadog{{< /nextlink >}} + {{< nextlink href="dashboards/guide/compatible_semantic_tags" >}}Compatible semantic tags{{< /nextlink >}} {{< nextlink href="dashboards/guide/slo_data_source" >}}Graph historical SLO data on Dashboards{{< /nextlink >}} - {{< nextlink href="/dashboards/guide/slo_graph_query" >}}Scope metric-based SLO queries{{< /nextlink >}} - {{< 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/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 - {{< /nextlink >}} - {{< nextlink href="/dashboards/guide/tv_mode" >}}Using TV mode for Dashboards - {{< /nextlink >}} + {{< nextlink href="dashboards/guide/slo_graph_query" >}}Scope metric-based SLO queries{{< /nextlink >}} + {{< nextlink href="dashboards/guide/apm-stats-graph" >}}Configuring an APM stats graph{{< /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{{< /nextlink >}} {{< /whatsnext >}} -{{< whatsnext desc="Functions:" >}} - {{< nextlink href="/dashboards/guide/how-weighted-works" >}}How does weighted() work?{{< /nextlink >}} - {{< nextlink href="/dashboards/guide/rollup-cardinality-visualizations" >}}Understanding rollup function and cardinality in visualizations{{< /nextlink >}} +### Functions, Automation & Access Control + +{{< whatsnext desc="Learn how data is transformed and how to automate and secure your dashboard setup." >}} +{{< nextlink href="dashboards/guide/how-weighted-works" >}}How does weighted() work?{{< /nextlink >}} +{{< nextlink href="dashboards/guide/rollup-cardinality-visualizations" >}}Understanding rollup function and cardinality in visualizations{{< /nextlink >}} +{{< nextlink href="dashboards/guide/how-to-use-terraform-to-restrict-dashboards" >}}Using Terraform to restrict the editing of a dashboard{{< /nextlink >}} {{< /whatsnext >}} -{{< whatsnext desc="Deprecated APIs:" >}} +### API Changes & Deprecations + +{{< whatsnext desc="Be aware of migrations and deprecated dashboard APIs." >}} + {{< nextlink href="dashboards/guide/is-read-only-deprecation" >}}Dashboards API: Migrate from is_read_only by December 13, 2024{{< /nextlink >}} {{< nextlink href="dashboards/guide/screenboard-api-doc" >}}Screenboard API{{< /nextlink >}} {{< nextlink href="dashboards/guide/timeboard-api-doc" >}}Timeboard API{{< /nextlink >}} {{< nextlink href="dashboards/guide/dashboard-lists-api-v1-doc" >}}Dashboard Lists API (v1){{< /nextlink >}} 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..d3c76e58d81be --- /dev/null +++ b/content/en/dashboards/guide/getting_started_with_wildcard_widget.md @@ -0,0 +1,129 @@ +--- +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][4]. In this tutorial, you'll learn how to use Datadog's **Wildcard widget** to build a flexible visualization that compares **typical (P50)** versus **slow (P95)** latency across your services. + +### 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. +* Visualize P50 vs. P5 latency as a scatterplot with labeled text. +* Enable inter-widget interaction using a context menu. + +### Prerequisites + +* A Datadog account with access to [Notebooks][1] or [Dashboards][2]. +* 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][3]. + +## Understand the Key Concepts + +Before building your first visualization, it's helpful to understand two core Vega-Lite concepts: **encoding** and **layering**. + +Encodings +: An encoding maps data to a visual element. You define these mappings in the "Define visual" tab of the Wildcard widget. For example:
+ * X position → p50 latency + * Y position → p95 latency + * Color → endpoint + * Shape → service + +Layering +: Layering allows you to stack different mark types (text, points, bars) to create composite visualizations. + +## 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). You can use widgets from your [prebuilt dashboards](https://app.datadoghq.com/dashboard/lists/preset/3?p=1). + +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. Add clarity by renaming field names. For example, rename `p50:trace.http.request{*} by {service}`→ `p50` +3. Click **Add Query** to add a second formula, and change the group by from `p50 by` → `p95 by` to compare outlier latency. + +{{< 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 scatterplot using the P50 and P95 metrics. + +
+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. +
+ +## Step 4:Add labels to the graph + +To add text labels directly to the chart: + +1. Add a `text` encoding: + * Use the field dropdown or JSON to map `viz` or `endpoint` as the text value. +2. Change the **mark type** to `text`: + * Use the command palette or enter it in JSON: `"mark": "text"` +3. Run the widget. + +## Step 5: Add a context menu + +To add interactivity to your graph, enable context menu support: + +1. In the visual JSON editor, add the following: + ```json + "params": [ + { + "name": "datadogPointSelection", + "select": "point" + } + ] + ``` +2. Save and run the widget. +3. Click any data point in your wildcard widget to bring up a **context menu** with dynamic filters. + +For more information, see [Using Vega-Lite with Wildcard Widgets in Datadog][5]. + +## Next Steps + +* Customize mark types and layering further for complex composite charts. +* Take a look at [Wildcard widget examples][7] for inspiration. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://app.datadoghq.com/notebook/list +[2]: https://app.datadoghq.com/dashboard/lists?p=1 +[3]: /dashboards/widgets/wildcard/#setup +[4]: https://vega.github.io/vega-lite/ +[5]: /dashboards/guide/using_vega_lite_in_wildcard_widgets/#context-menu-and-context-links +[6]: https://docs.datadoghq.com/dashboards/guide/using_vega_lite_in_wildcard_widgets/ +[7]: https://docs.datadoghq.com/dashboards/guide/wildcard_examples/ \ No newline at end of file diff --git a/content/en/dashboards/widgets/wildcard.md b/content/en/dashboards/widgets/wildcard.md index 8e39ab832e9a3..a28b82822fb84 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" 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/ddsql_editor/logs_metrics_queries_preview.png b/static/images/ddsql_editor/logs_metrics_queries_preview.png new file mode 100644 index 0000000000000..5a98663f79590 Binary files /dev/null and b/static/images/ddsql_editor/logs_metrics_queries_preview.png 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