|
| 1 | +--- |
| 2 | +title: Widget Builder |
| 3 | +sidebar_order: 15 |
| 4 | +description: "Learn how to create widgets for your dashboards or edit existing ones." |
| 5 | +--- |
| 6 | + |
| 7 | +<Note> |
| 8 | + |
| 9 | +This feature is available only if your organization is on either a Business or Trial plan. |
| 10 | + |
| 11 | +</Note> |
| 12 | + |
| 13 | +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: |
| 14 | + |
| 15 | + |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +## Widget Title |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +## Choose Your Visualization |
| 26 | + |
| 27 | +In this step, you can choose from four different visualization types: |
| 28 | + |
| 29 | +- [Area Chart / Bar Chart / Line Chart](#area-chart--bar-chart--line-chart) |
| 30 | +- [Table](#table) |
| 31 | +- [World Map](#world-map) |
| 32 | +- [Big Number](#big-number) |
| 33 | + |
| 34 | + |
| 35 | +### Area Chart / Bar Chart / Line Chart |
| 36 | + |
| 37 | +Area, bar, and line chart visualizations allow you to plot one or more aggregate functions as a time series. |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | +Each chart type allows you to solve different problems: |
| 42 | + |
| 43 | +- 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”. |
| 44 | +- 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”. |
| 45 | +- 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. |
| 46 | + |
| 47 | +### Table |
| 48 | + |
| 49 | +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). |
| 50 | + |
| 51 | +### World Map |
| 52 | + |
| 53 | +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. |
| 54 | + |
| 55 | +### Big Number |
| 56 | + |
| 57 | +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”. |
| 58 | + |
| 59 | +## Choose Your Dataset |
| 60 | + |
| 61 | +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). |
| 62 | + |
| 63 | +### Errors & Transactions |
| 64 | + |
| 65 | +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: |
| 66 | + |
| 67 | +- Tracking performance of an endpoint |
| 68 | +- Throughput by country |
| 69 | +- Users most affected by errors |
| 70 | + |
| 71 | +### Issues |
| 72 | +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. |
| 73 | +Choose this dataset if you want to customize a list of issues on your dashboard. Some widget examples include: |
| 74 | + |
| 75 | +- Issues assigned to your team |
| 76 | +- Most frequently occurring issues |
| 77 | +- The "Issues" dataset is only available in table visualization widgets and its disabled if you have other visualizations selected. |
| 78 | + |
| 79 | +### Releases |
| 80 | + |
| 81 | +<Note> |
| 82 | + |
| 83 | +This feature is available only if you're in the Early Adopter program. Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony. |
| 84 | +If you’re interested in being an Early Adopter, you can turn your organization’s Early Adopter status on/off in General Settings. This will affect all users in your organization and can be turned back off just as easily. |
| 85 | + |
| 86 | +</Note> |
| 87 | + |
| 88 | +Choosing "Releases" allows you to query properites specific to a release of your application, primarily session data. Choose this data set if you want to display healthy, errored and crashed sessions and crash rates for your releases or projects on your dashboard. Doesn't apply to World Map. Some widget examples include: |
| 89 | +- Crash rates for your latest release |
| 90 | +- Session count across releases |
| 91 | + |
| 92 | +## Choose Your Columns |
| 93 | + |
| 94 | +The option to set columns is only available for [table visualizations](/product/dashboards/widget-builder/#table). |
| 95 | + |
| 96 | +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). |
| 97 | + |
| 98 | +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/). |
| 99 | + |
| 100 | +Next to each column and equation, you have the option to set an alias that will replace the column name in the table header. |
| 101 | + |
| 102 | +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: |
| 103 | + |
| 104 | + |
| 105 | + |
| 106 | +## Choose What to Plot in the Y-axis |
| 107 | + |
| 108 | +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. |
| 109 | + |
| 110 | +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. |
| 111 | + |
| 112 | +## Filter Your Results |
| 113 | + |
| 114 | +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). |
| 115 | + |
| 116 | +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: |
| 117 | + |
| 118 | + |
| 119 | + |
| 120 | +## Group Your Results |
| 121 | + |
| 122 | +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. |
| 123 | + |
| 124 | +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: |
| 125 | + |
| 126 | + |
| 127 | + |
| 128 | +## Sort By a Column |
| 129 | + |
| 130 | +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. |
| 131 | + |
| 132 | +## Limit |
| 133 | + |
| 134 | +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. |
| 135 | + |
| 136 | +## Sort By a Y-axis |
| 137 | + |
| 138 | +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. |
| 139 | + |
| 140 | +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: |
| 141 | + |
| 142 | + |
0 commit comments