Add a section for scalar vs. timeseries in wildcard widget #26324

estherk15 · 2024-11-15T21:07:17Z

What does this PR do? What is the motivation?

Add a section on the difference between timeseries and scalar types
DOCS-9326

Merge instructions

Merge queue is enabled in this repo. To have it automatically merged after it receives the required reviews, create the PR (from a branch that follows the <yourname>/description naming convention) and then add the following PR comment:

/merge

Additional notes

content/en/dashboards/widgets/wildcard.md

github-actions · 2024-11-15T21:10:03Z

Preview links (active after the `build_preview` check completes)

Modified Files

https://docs-staging.datadoghq.com/esther/docs-9326-wildcard-scalar-timeseries/dashboards/widgets/wildcard

hydrosquall

Thank you for looking into this change 🙇

I left some feedback about distinguishing request types from visualization types, let me know if discussing some parts of this live would be helpful.

hydrosquall · 2024-11-19T01:00:01Z

content/en/dashboards/widgets/wildcard.md

@@ -41,6 +42,22 @@ However, if none of the Datadog widgets meets your visualization needs, a Wildca
 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
+
+In Datadog dashboards, scalar and timeseries visualizations serve different purposes and are used to represent data in distinct ways.


Visualization might not be the noun we're looking for, we are referring to a data format (which has a corresponding "request type". Maybe something like

visualizations are powered by a multiple request types, including scalar and timeseries. Each request types changes the number and type of fields available for the data in a Wildcard Widget.

There are 2 other request types in the widget selector which are GA, List and Histogram. It's OK to not explain what all 4 of them in 1 PR, but we don't want people to have the impression that there are only 2 request types.

Suggested change

In Datadog dashboards, scalar and timeseries visualizations serve different purposes and are used to represent data in distinct ways.

In Datadog dashboards, visualizations are powered by a multiple _request types_, including scalar and timeseries. Each _request type_ changes the number and type of fields available for the data in a Wildcard widget.

hydrosquall · 2024-11-19T01:05:14Z

content/en/dashboards/widgets/wildcard.md

+   - **Appearance**: These visualizations are typically line or area charts. They show datapoints plotted against time (usually on the x-axis), to observe changes and trends.
+
+**Scalar**
+: This visualization presents a single, aggregate value derived from your data.


This describes the "query value" case, but doesn't fully describe how the scalar endpoint is used. The scalar endpoint powers the toplist, treemap, sumburst, and table widgets because 1 value is produced per groupBy and per formula .

I think that referring to these two sections as describing "data formats" rather than "visualization types" may make this easier to follow.

I think the takeaway that "if you need to describe a change over time, use timeseries, otherwise prefer scalar" works well for this section.

We may also want to touch briefly on why "Formulas" appears in the title. The other two request formats (histogram, list), are not compatible with Functions API (also called "Formulas and Functions" / "F+F" internally), which is why only Scalar/Timeseries have the formulas prefix.

Suggested change

: This visualization presents a single, aggregate value derived from your data.

: This data format presents a single, aggregate value derived from your data. The scalar endpoint powers the toplist, treemap, pie chart, and table widgets because 1 value is produced per `groupBy` and per `formula`.

hydrosquall · 2024-11-19T01:08:16Z

content/en/dashboards/widgets/wildcard.md

+**Timeseries**
+: This visualization 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. 
+   - **Appearance**: These visualizations are typically line or area charts. They show datapoints plotted against time (usually on the x-axis), to observe changes and trends.


I'm not sure we need to keep this section (since we are trying to focus convey that the request type is something that is independent of the visualization type - timeseries queries also can be used in the Heatmap widget), but if we do, DD timeseries are drawn in bar mode too (likely more frequently than areas).

Thanks, I'll remove the appearance section for both!

Suggested change

- **Appearance**: These visualizations are typically line or area charts. They show datapoints plotted against time (usually on the x-axis), to observe changes and trends.

estherk15

Thanks for the review @hydrosquall! I made changes from your suggestions, let me know if I missed anything!

estherk15 · 2024-11-19T14:45:11Z

content/en/dashboards/widgets/wildcard.md

@@ -41,6 +42,22 @@ However, if none of the Datadog widgets meets your visualization needs, a Wildca
 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
+
+In Datadog dashboards, scalar and timeseries visualizations serve different purposes and are used to represent data in distinct ways.


Suggested change

In Datadog dashboards, scalar and timeseries visualizations serve different purposes and are used to represent data in distinct ways.

In Datadog dashboards, visualizations are powered by a multiple _request types_, including scalar and timeseries. Each _request type_ changes the number and type of fields available for the data in a Wildcard widget.

estherk15 · 2024-11-19T14:45:47Z

content/en/dashboards/widgets/wildcard.md

+**Timeseries**
+: This visualization 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. 
+   - **Appearance**: These visualizations are typically line or area charts. They show datapoints plotted against time (usually on the x-axis), to observe changes and trends.


Thanks, I'll remove the appearance section for both!

Suggested change

- **Appearance**: These visualizations are typically line or area charts. They show datapoints plotted against time (usually on the x-axis), to observe changes and trends.

estherk15 · 2024-11-19T14:46:01Z

content/en/dashboards/widgets/wildcard.md

+**Scalar**
+: This visualization presents a single, aggregate value derived from your data.
+   - **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.
+   - **Appearance**: Scalars often appear as large, standalone numbers or small cards on dashboards, highlighting the most relevant statistics, like the current number of active users, or the sum of errors over the last hour.


Suggested change

- **Appearance**: Scalars often appear as large, standalone numbers or small cards on dashboards, highlighting the most relevant statistics, like the current number of active users, or the sum of errors over the last hour.

estherk15 · 2024-11-19T14:50:39Z

content/en/dashboards/widgets/wildcard.md

+   - **Appearance**: These visualizations are typically line or area charts. They show datapoints plotted against time (usually on the x-axis), to observe changes and trends.
+
+**Scalar**
+: This visualization presents a single, aggregate value derived from your data.


Suggested change

: This visualization presents a single, aggregate value derived from your data.

: This data format presents a single, aggregate value derived from your data. The scalar endpoint powers the toplist, treemap, pie chart, and table widgets because 1 value is produced per `groupBy` and per `formula`.

estherk15 · 2024-11-19T15:11:47Z

content/en/dashboards/widgets/wildcard.md

+
+**Scalar**
+: This visualization presents a single, aggregate value derived from your data.
+   - **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.


Suggested change

- **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.

- **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.

estherk15 · 2024-11-19T15:14:50Z

content/en/dashboards/widgets/wildcard.md

+   - **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.
+   - **Appearance**: Scalars often appear as large, standalone numbers or small cards on dashboards, highlighting the most relevant statistics, like the current number of active users, or the sum of errors over the last hour.
+
+Timeseries visualizations emphasize data trends over time, scalar visualizations focus on presenting single, computed values that help with quick assessments. If you're going to visualize time on an axis, or need individual time buckets, choose the Timeseries type. However, if you're not vizualizing against time, choose the Scalar type as it's much more performant.


Suggested change

Timeseries visualizations emphasize data trends over time, scalar visualizations focus on presenting single, computed values that help with quick assessments. If you're going to visualize time on an axis, or need individual time buckets, choose the Timeseries type. However, if you're not vizualizing against time, choose the Scalar type as it's much more performant.

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.

estherk15 · 2024-11-19T15:19:30Z

content/en/dashboards/widgets/wildcard.md

+In Datadog dashboards, scalar and timeseries visualizations serve different purposes and are used to represent data in distinct ways.
+
+**Timeseries**
+: This visualization is designed to display how your data changes over time.


Suggested change

: This visualization is designed to display how your data changes over time.

: This data format is designed to display how your data changes over time.

Add a section for scalar vs. timeseries in wildcard widget

e0b78a2

estherk15 requested a review from a team as a code owner November 15, 2024 21:07

estherk15 requested a review from hydrosquall November 15, 2024 21:08

estherk15 commented Nov 15, 2024

View reviewed changes

content/en/dashboards/widgets/wildcard.md Outdated Show resolved Hide resolved

estherk15 commented Nov 15, 2024

View reviewed changes

content/en/dashboards/widgets/wildcard.md Outdated Show resolved Hide resolved

estherk15 added 2 commits November 15, 2024 16:10

Apply suggestions from code review

8ba49f7

Merge branch 'master' into esther/docs-9326-wildcard-scalar-timeseries

ceb474e

hestonhoffman approved these changes Nov 18, 2024

View reviewed changes

hydrosquall reviewed Nov 19, 2024

View reviewed changes

estherk15 commented Nov 19, 2024

View reviewed changes

Add functions doc reference

06c12db

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a section for scalar vs. timeseries in wildcard widget #26324

Add a section for scalar vs. timeseries in wildcard widget #26324

estherk15 commented Nov 15, 2024 •

edited by jira bot

Loading

github-actions bot commented Nov 15, 2024

hydrosquall left a comment

hydrosquall Nov 19, 2024

estherk15 Nov 19, 2024 •

edited

Loading

hydrosquall Nov 19, 2024

estherk15 Nov 19, 2024

hydrosquall Nov 19, 2024

estherk15 Nov 19, 2024

estherk15 left a comment

estherk15 Nov 19, 2024 •

edited

Loading

estherk15 Nov 19, 2024

estherk15 Nov 19, 2024

estherk15 Nov 19, 2024

estherk15 Nov 19, 2024

estherk15 Nov 19, 2024 •

edited

Loading

estherk15 Nov 19, 2024

	In Datadog dashboards, scalar and timeseries visualizations serve different purposes and are used to represent data in distinct ways.
	In Datadog dashboards, visualizations are powered by a multiple _request types_, including scalar and timeseries. Each _request type_ changes the number and type of fields available for the data in a Wildcard widget.

	: This visualization presents a single, aggregate value derived from your data.
	: This data format presents a single, aggregate value derived from your data. The scalar endpoint powers the toplist, treemap, pie chart, and table widgets because 1 value is produced per `groupBy` and per `formula`.

	- 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.
	- 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.

-Timeseries visualizations emphasize data trends over time, scalar visualizations focus on presenting single, computed values that help with quick assessments. If you're going to visualize time on an axis, or need individual time buckets, choose the Timeseries type. However, if you're not vizualizing against time, choose the Scalar type as it's much more performant.
+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.

	: This visualization is designed to display how your data changes over time.
	: This data format is designed to display how your data changes over time.

Add a section for scalar vs. timeseries in wildcard widget #26324

Are you sure you want to change the base?

Add a section for scalar vs. timeseries in wildcard widget #26324

Conversation

estherk15 commented Nov 15, 2024 • edited by jira bot Loading

What does this PR do? What is the motivation?

Merge instructions

Additional notes

github-actions bot commented Nov 15, 2024

Preview links (active after the build_preview check completes)

Modified Files

hydrosquall left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

estherk15 Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

estherk15 left a comment

Choose a reason for hiding this comment

estherk15 Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

estherk15 Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

estherk15 commented Nov 15, 2024 •

edited by jira bot

Loading

Preview links (active after the `build_preview` check completes)

estherk15 Nov 19, 2024 •

edited

Loading

estherk15 Nov 19, 2024 •

edited

Loading

estherk15 Nov 19, 2024 •

edited

Loading