feat(widget-builder): Add GA documentation - (#5065)

Author: priscilawebdev

src/docs/product/dashboards/custom-dashboards/dashboard-widget-builder.png

@@ -39,65 +39,8 @@ When the "Show Templates" toggle is enabled, several default dashboard templates
 
 ## Widget Builder
 
-When you add a widget or edit an existing one, you’ll be prompted with a form and preview of the visualization. From here, you can:
-- Rename the widget
-- Change the queries
-- Provide legend aliases
-- Change the Y-Axes
+When adding a widget or editing an existing one, you will be taken to a new page where you can see the dashboard widget builder. The widget builder has several configuration options that you can use to shape data and add information to your dashboard. Learn more in the [Widget Builder documentation](/product/dashboards/widget-builder/).
 
-![Widget builder.](dashboard-widget-builder.png)
+## Widget Library
 
-The form includes these fields:
-- Widget Name: The name that appears at the top of each widget.
-- Visualization Display: The selected [visualization type](#visualization-types).
-- Query: The search parameters that define what you are investigating. Add additional queries to compare projects, organizations, releases, and so on. Each query has a legend alias you can name to view more easily in any of the time series charts. For more information on how to build a query, check out some of the rules we have for our [Discover Query Builder](/product/discover-queries/query-builder/).
-- Y-Axis: The attribute of the search parameters you want to map out. By default, count() is selected. Changing this to a duration will change the Y-Axis to milliseconds or seconds. Adding an overlay will add another set of data to compare. For example, to reflect P50, P75, and P90, you’ll require three overlays. If the units conflict, the charts will always base it off the first line.
-
-## Visualization Types
-
-### Line, Bar, and Area Charts
-
-Line, bar, and area chart visualizations allow you to plot one or more aggregate functions as a time series.
-
-![Time series widgets.](dashboard-widgets.png)
-
-Each chart type allows you to solve different problems:
-- Line charts are a general-purpose visualization. Make sure the Y-Axis units match if you add multiple overlays. Mixing count with duration will not yield useful results.
-- Bar charts will group results by day, making them good for daily roll-ups or
-  as 'big picture' summaries. An example would be 'count of errors per day'.
-- Area charts are ideal for showing results that are cumulative or where you want to
-  show a breakdown. An example would be 'count of errors for each major browser'.
-
-### Table Results
-
-Table results display the top results of a [Discover Query](/product/discover-queries/). This
-visualization is well suited to showing key fields and related aggregates. For
-example 'duration percentiles for the most frequently visited transaction
-names'. You can also choose to display [issues](/product/issues/) data in a table visualization using the [data set selector](#data-set-selection).
-
-### World Map
-
-Events are queried using the given function and `geo.country_code`. The results are plotted as a density value
-on a world map. An example scenario would be 'in which countries are users experiencing the most errors'. You can zoom the map using the mouse wheel, or pan the map by clicking and dragging the map around.
-
-### Big Number
-
-A big number visualization displays the current value of a single function. This visualization is well
-suited for high-level aggregates. An example scenario would be 'p95 of all
-transactions'.
-
-
-## Data Set Selection
-
-Select between events and [issues](/product/issues/) data in a widget with the "Data Set" selector.
-
-Choosing "All Events" allows you to query and aggregate error and transaction events in the same way you would for a [Discover query](/product/discover-queries/). Some widget examples include:
-- Tracking performance of an endpoint
-- Throughput by country
-- Users most affected by errors
-
-Choosing "Issues" allows you to query issue properties, such as `is:unresolved` or event properties such as `error.handled:0`, and to sort by issue fields such as `First Seen`. When searching on event properties, the search will return any issue that has one or more events matching the supplied event filters. Choose this data set if you want to customize a list of issues on your dashboard. Some widget examples include:
-- Issues assigned to your team
-- Most frequently occurring issues
-
-The "Issues" data set is only available in [table](#table-results) visualization widgets.
+The widget library contains a collection of prebuilt widgets you can add to your [custom dashboards](/product/dashboards/custom-dashboards/). Learn more in the [Widget Library documentation](/product/dashboards/widget-library/).

src/docs/product/dashboards/custom-dashboards/index.mdx

@@ -0,0 +1,132 @@
+---
+title: Widget Builder
+sidebar_order: 15
+description: "Learn how to create widgets for your dashboards or edit existing ones."
+---
+
+<Note>
+
+This feature is available only if your organization is on either a Business or Trial plan.
+
+</Note>
+
+When adding a widget or editing an existing one, you will be taken to a new page where you can see the dashboard widget builder:
+
+![Widget Builder overview.](widget-builder-overview.png)
+
+The widget builder has several configuration options that you can use to shape data and add information to your dashboard. These options are presented as steps in the widget builder, but you don't have to do them in the order they're presented in.
+
+Some of these options are standard and displayed for all widgets, but others are only displayed if you make specific selections. Below is a list of all the options that can be displayed when configuring your widget.
+
+## Widget Title
+
+By default, all new widgets are titled “Custom Widget”, but you can edit the title by clicking on the text. We recommend you update the title.
+
+## Choose Your Visualization
+
+In this step, you can choose from four different visualization types:
+
+- [Area Chart / Bar Chart / Line Chart](#area-chart--bar-chart--line-chart)
+- [Table](#table)
+- [World Map](#world-map)
+- [Big Number](#big-number)
+
+
+### Area Chart / Bar Chart / Line Chart
+
+Area, bar, and line chart visualizations allow you to plot one or more aggregate functions as a time series.
+
+![Time-series visualizations.](widget-builder-time-series-visualizations.png)
+
+Each chart type allows you to solve different problems: 
+
+- Area charts are ideal for showing results that are cumulative or where you want to show a breakdown. An example would be “count of errors for each major browser”. 
+- Bar charts will group results by day, making them good for daily roll-ups or as “big picture” summaries. An example would be “count of errors per day”. 
+- Line charts are a general-purpose visualization. Make sure the Y-Axis units match if you add multiple overlays. Mixing count with duration will not yield useful results.
+
+### Table
+
+Table charts display the results of a [Discover Query](/product/discover-queries/). This visualization is well suited to showing key fields and related aggregates. For example “duration percentiles for the most frequently visited transaction names”. You can also choose to display [issues](/product/issues/) data in a table visualization using the [dataset selector](/product/dashboards/widget-builder/#choose-your-dataset).
+
+### World Map
+
+Events are queried using the given function and `geo.country_code`. The results are plotted as a density value on a world map. An example scenario would be “in which countries are users experiencing the most errors”. You can zoom the map using the mouse wheel, or pan the map by clicking and dragging the map around.
+
+### Big Number
+
+A big number visualization displays the current value of a single function. This visualization is well suited for high-level aggregates. An example scenario would be “p95 of all transactions”.
+
+## Choose Your Dataset
+
+In the dataset selection step, choose which type of data you would like to use in your widget. This data is classified into two different datasets: [errors and transactions](#errors--transactions) and [issues](#issues).
+
+### Errors & Transactions
+
+Choosing "Errors and Transactions" allows you to query and aggregate error and transaction events in the same way you would for a [Discover Query](/product/discover-queries/). Some widget examples include: 
+
+- Tracking performance of an endpoint 
+- Throughput by country 
+- Users most affected by errors
+
+### Issues
+Choosing "Issues (States, Assignment, Time, etc.)" allows you to query issue properties, such as `is:unresolved` or event properties such as `error.handled:0`, and to sort by issue fields such as `First Seen`. When searching on event properties, the search will return any issue that has one or more events matching the supplied event filters. 
+Choose this dataset if you want to customize a list of issues on your dashboard. Some widget examples include:
+
+- Issues assigned to your team 
+- Most frequently occurring issues
+- The "Issues" dataset is only available in table visualization widgets and its disabled if you have other visualizations selected.
+
+## Choose Your Columns
+
+The option to set columns is only available for [table visualizations](/product/dashboards/widget-builder/#table).
+
+By default, the first column is already configured for you, but you can update it. To add more columns, which stacks events, add [functions](/product/discover-queries/query-builder/#stacking-functions) (`f(x)`) that can take in parameters. [Field and tag columns](/product/sentry-basics/search/searchable-properties/#event-properties) will help you view more details about the events (for example, `title` to see the description of an issue or `users` to see how many users it's affecting).
+
+You can also add equations to your query using the table columns as equation variables, and the results will be displayed in the query results table. Learn more in [Adding Query Equations](/product/discover-queries/query-builder/query-equations/).
+
+Next to each column and equation, you have the option to set an alias that will replace the column name in the table header. 
+
+If two or more columns are added, you can change the order in which they're displayed in the table by clicking and dragging them:
+
+![Drag and drop column.](widget-builder-drag-and-drop-column.png)
+
+## Choose What to Plot in the Y-axis
+
+The option to set a y-axis is available on all visualizations except [table](/product/dashboards/widget-builder/#table). In the case of [time-series visualizations](/product/dashboards/widget-builder/#area-chart--bar-chart--line-chart), you'll be able to plot up to three values that can be functions or equations. If the units of your selections conflict, then the y-axis of the chart will be labeled using the units of the first selection.
+
+You can also choose to construct an equation by clicking “Add an Equation”. Doing this displays a text box where you can enter your equation. Functions that you've added previously in this step will appear for autocompletion, but you can add other functions as well.
+
+## Filter Your Results
+
+Use this field to filter your results by the searchable properties of your [dataset selection](/product/dashboards/widget-builder/#choose-your-dataset). For more information on which properties apply to each dataset, check out our [full Searchable Properties documentation](/product/sentry-basics/search/searchable-properties/#properties-table).
+
+On [time-series visualizations](/product/dashboards/widget-builder/#area-chart--bar-chart--line-chart) you can add up to three queries to filter your results, each with their own search conditions, to compare results. Each query will generate a new series in your chart for each y-axis. To make it easier to differentiate between them in the legend and tooltip, you can add a legend alias that will be added as a prefix to the labels, as in the example below:
+
+![Filter your results.](widget-builder-filter-your-results-example.png)
+
+## Group Your Results
+
+The option to group results is only available for [time-series visualizations](/product/dashboards/widget-builder/#area-chart--bar-chart--line-chart). You can group your time series results by different fields or tags such as project, environment, or transaction. You can select up to 20 fields to group your data.
+
+If two or more groups are added, a draggable element will be displayed that you can use to sort the fields, but the sort does not impact how your data is displayed in the visualization:
+
+![Drag and drop group by.](widget-builder-drag-and-drop-group-by.png)
+
+## Sort By a Column
+
+The option to sort by a column is only available for [table visualizations](/product/dashboards/widget-builder/#table). Choose one of the columns of your table to sort by, and set whether you want to sort high-to-low or low-to-high.
+
+## Limit
+
+The option to limit your results is only available for [time-series visualizations](/product/dashboards/widget-builder/#area-chart--bar-chart--line-chart) where you've applied a grouping. Depending on your configuration (for example, multiple y-axes, multiple queries), your chart results could become unmanageable, so a limit is imposed. You can change this limit by selecting it in the dropdown. We intend to show at most 10 series (that is, lines in a line chart or bars in a bar chart) when multiple y-axes or queries are selected.
+
+## Sort By a Y-axis
+
+The option to sort by a y-axis is only available if you've applied a grouping to your data (in [“Group your results”](/product/dashboards/widget-builder/#group-your-results)). The sorting applies to the underlying groups in your results and thus affects the series that appear in your chart. You can select fields that you used for grouping, select equations defined in the y-axes, construct any function similar to how you would select a function for plotting, or construct a custom equation.
+
+If you select “Custom Equation”, an extra field appears where you can enter an equation of your choice that will be applied to the query:
+
+![Custom equation field.](widget-builder-custom-equation-field.png)
+
+
+

src/docs/product/dashboards/widget-builder/index.mdx

@@ -10,20 +10,20 @@ This feature is available only if your organization is on either a Business or T
 
 </Note>
 
-The widget library contains a collection of prebuilt widgets you can add to your [custom dashboards](/product/dashboards/customize-dashboards/). To access it, click “Add Widget” (existing dashboard) or the plus icon (new dashboard) and switch to the “Widget Library” tab in the modal that appears.
+The widget library contains a collection of prebuilt widgets you can add to your [custom dashboards](/product/dashboards/customize-dashboards/). You can access the widget library in the right sidebar of the [widget builder](/product/dashboards/widget-builder/).
 
 The library includes the following widgets:
 
 - **Duration Distribution**: A multi-overlay chart visualizing the distribution of transaction duration across various percentiles (p50, p75, and p95)
-- **High Throughput Transactions**: The top five transactions with the largest number of events
+- **High Throughput Transactions**: The top five transactions with the largest number of events, represented in an area chart 
 - **LCP by Country**: World map showing the p75 of page load times for each country
 - **Miserable Users**: The total number of unique users who have experienced slow transactions (transaction duration greater than 1200ms)
 - **Slow vs. Fast Transactions**: Bar chart comparing the percentage of transactions that are over 300ms (slow) and under 300ms (fast)
 - **Issues For Review**: A table of unresolved issues for review, ordered by the most recently seen issues
 - **Top Unhandled Error Types**: The top five most frequently encountered unhandled errors
 - **Users Affected by Errors**: A comparison of the total number of errors and the number of unique users affected by the errors
 
-You can change the title, queries, fields, visualization types, and sort order of these prebuilt widgets to suit your use case by clicking the context menu on the widget and selecting "Edit Widget".
+You can change the title, queries, fields, visualization types, sort order, and other fields of these prebuilt widgets to suit your use case by clicking the context menu on the widget and selecting "Edit Widget".
 
 ## Example Use Cases
 
@@ -67,7 +67,7 @@ Finally, add a third query for for the frustrating transaction duration:
 
 The chart now shows cumulative counts at different response time thresholds.
 
-![Response Threshold Widget.](dashboard-response-threshold-widget.png)
+![Response Thresholds Widget.](widget-library-response-thresholds-widget.png)
 
 ### My top issues
 
@@ -82,7 +82,7 @@ Update "Columns" to add `project` so you can see the associated project with eac
 
 ### Priority issues
 
-The issues data set is unique in that you can add a free form [token](/product/sentry-basics/search/#syntax) to your search condition that will filter by issue titles containing the token. For example, you can search `integrity` to filter by all issue titles containing `integrity`. Update the search condition with a token of your choice:
+The [issues dataset](/product/dashboards/widget-builder/#issues) is unique in that you can add a free form [token](/product/sentry-basics/search/#syntax) to your search condition that will filter by issue titles containing the token. For example, you can search `integrity` to filter by all issue titles containing `integrity`. Update the search condition with a token of your choice:
 
 - Search condition: `is:unresolved is:for_review {token}`
 

src/docs/product/dashboards/widget-builder/widget-builder-custom-equation-field.png

@@ -40,7 +40,7 @@ From the **Issues** page, you can begin to triage. The page is organized into ta
 
 Learn more about triaging issues and their different states in [Issue States and Triage](/product/issues/states-triage/).
 
-You can also add issues data to your [custom dashboards](/product/dashboards/custom-dashboards/), as widgets, using the [data set selector](/product/dashboards/custom-dashboards/#data-set-selection).
+You can also add issues data to your [custom dashboards](/product/dashboards/custom-dashboards/), as widgets, using the [dataset selector](/product/dashboards/widget-builder/#choose-your-dataset).
 
 ## Learn More
 

src/docs/product/dashboards/widget-builder/widget-builder-drag-and-drop-column.png

@@ -6,7 +6,7 @@ Sentry.withScope(scope -> {
   scope.setLevel(SentryLevel.FATAL);
   scope.setTransaction("main");
 
-  // This message includes the data set to the scope in this block:
+  // This message includes the dataset to the scope in this block:
   Sentry.captureMessage("Fatal message!");
 });
 ```
@@ -19,7 +19,7 @@ Sentry.withScope { scope ->
   scope.level = SentryLevel.FATAL
   scope.setTransaction("main")
 
-  // This message includes the data set to the scope in this block:
+  // This message includes the dataset to the scope in this block:
   Sentry.captureMessage("Fatal message!")
 }
 ```