Skip to content

Commit 0c4c79a

Browse files
authored
Clarify how to pass flag for extras repo and trim whitespace (#17962)
1 parent 1a1b95c commit 0c4c79a

File tree

1 file changed

+13
-14
lines changed

1 file changed

+13
-14
lines changed

docs/developer/guidelines/dashboards.md

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ ddev meta dash export <URL_OF_DASHBOARD> <INTEGRATION>
2121
```
2222

2323
!!! tip
24-
If the dashboard is for a contributor-maintained integration in the `integration-extras` repo, run the command with the `--extras` or `-e` flag.
24+
If the dashboard is for a contributor-maintained integration in the `integration-extras` repo, run `ddev --extras meta ...` instead of `ddev meta ...`.
2525

2626
The command will add the dashboard definition to the `manifest.json` file of the integration.
2727
The dashboard JSON payload will be available in `/assets/dashboards/<DASHBOARD_TITLE>.json`.
@@ -46,7 +46,7 @@ Ensure logos render correctly on the Dashboard List page and within the preset d
4646

4747
A dashboard that follows best practices helps users consume data quickly. Best practices reduce friction when figuring out where to search for specific information or how to interpret data and find meaning. Additionally, guidelines give dashboard makers a starting point when creating a new dashboard.
4848

49-
### Visual Style Guidelines Checklist
49+
### Visual Style Guidelines Checklist
5050

5151
![Full length example](../assets/images/example_full_length.png)
5252

@@ -58,7 +58,7 @@ A dashboard that follows best practices helps users consume data quickly. Best p
5858
- [x] All widgets are placed within a group based on thematic organization, rather than directly on the background of the dashboard
5959
![Group titles](../assets/images/group_titles.png)
6060
- [x] *Query value* widgets have a timeseries background (e.g. "Bars") instead of being blank
61-
- [x] Visualizations with obvious thresholds or zones use semantic formatting for graphs or custom red/green/yellow text formatting for query values.
61+
- [x] Visualizations with obvious thresholds or zones use semantic formatting for graphs or custom red/green/yellow text formatting for query values.
6262
- [x] Color coordination between group headers, notes within groups, and graphs within groups (e.g. all group headers or note widgets the same color). If you've applied a vivid green to all group headers, try making its notes light green.
6363
![Header color usage](../assets/images/header_color_usage.png)
6464
- [x] Legends for each graph. Legends make it easy to read a graph without having to hover over each series or maximize the widget. Make sure you use aliases so the legend is easy to read. Automatic mode for legends is a great option that hides legends when space is tight and shows them when there's room.
@@ -80,33 +80,33 @@ A dashboard that follows best practices helps users consume data quickly. Best p
8080
1. Add a logo to the dashboard header. The integration logo will automatically appear in the header if the icon exists [here](https://druids.datadoghq.com/logos/logo-gallery) and the `integration_id` matches the icon name. That means it will only appear when the dashboard you're working on is made into the official integration board.
8181
![Logo in header](../assets/images/logo_header.png)
8282

83-
1. Include the integration name in the dashboard title. (e.g. "Elasticsearch Overview Dashboard").
84-
83+
1. Include the integration name in the dashboard title. (e.g. "Elasticsearch Overview Dashboard").
84+
8585
!!! warning
8686
Avoid using ++hyphen++ (hyphen) in the dashboard title as the dashboard URL is generated from the title.
87-
87+
8888

8989
### Standard Groups to Include
9090

91-
1. Always include an *About* group for the integration containing a brief description and helpful links. Edit the *About* group and select the "banner" display option (with the "Show Title" option unchecked), then link to a banner image like this: `/static/images/integration_dashboard/your-image.png`. For instructions on how to create and upload a banner image, go to the [DRUIDS logo gallery](https://druids.datadoghq.com/logos/logo-gallery), click the relevant logo, and click the *Dashboard Banner* tab. The *About* section should contain content, not data; avoid making the *About* section full-width. Consider copying the content in the *About* section into the hovercard that appears when hovering over the dashboard title.
91+
1. Always include an *About* group for the integration containing a brief description and helpful links. Edit the *About* group and select the "banner" display option (with the "Show Title" option unchecked), then link to a banner image like this: `/static/images/integration_dashboard/your-image.png`. For instructions on how to create and upload a banner image, go to the [DRUIDS logo gallery](https://druids.datadoghq.com/logos/logo-gallery), click the relevant logo, and click the *Dashboard Banner* tab. The *About* section should contain content, not data; avoid making the *About* section full-width. Consider copying the content in the *About* section into the hovercard that appears when hovering over the dashboard title.
9292

93-
1. Also include an *Overview* group containing service checks (e.g. liveness or readiness checks), a few of the most important metrics, and a monitor summary if you have pre-existing monitors for this integration, and place it at the top of the dashboard. The *Overview* section should contain data.
93+
1. Also include an *Overview* group containing service checks (e.g. liveness or readiness checks), a few of the most important metrics, and a monitor summary if you have pre-existing monitors for this integration, and place it at the top of the dashboard. The *Overview* section should contain data.
9494
![About and overview groups](../assets/images/about_and_overview_groups.png)
9595

9696
1. If log collection is enabled, make a *Logs* group. Insert a timeseries widget showing a bar graph of logs by status over time. Also include a log stream of logs with the "Error" or "Critical" status.
9797

9898
!!! tip
99-
Consider turning groups into powerpacks if they appear repeatedly in dashboards irrespective of the integration type, so that you can insert the entire group with the correct formatting with a few clicks rather than adding the same widgets from scratch each time.
99+
Consider turning groups into powerpacks if they appear repeatedly in dashboards irrespective of the integration type, so that you can insert the entire group with the correct formatting with a few clicks rather than adding the same widgets from scratch each time.
100100

101101
### Design Guidelines
102-
102+
103103
1. Research the metrics supported by the integration and consider grouping them in relevant categories. Groups containing prioritized metrics that are key to the performance and overview of the integration should be closer to the top. Some considerations when deciding which widgets should be grouped together:
104104
- Go from macro to micro levels within the system (e.g. for a database integration's dashboard, you could group node metrics in one group, index metrics in the next group, shard metrics in the third group)
105105
- Go from upstream to downstream sections within the system (e.g. for a data streams integration's dashboard, you could group producer metrics in one group, broker metrics in the next group, and consumer metrics in the third group)
106-
- Group together metrics that lead to the same actionable insights (e.g. all indexing metrics that reveal which indexes/shards should be optimized could all go in one group, while resource utilization metrics like disk space or memory usage that inform allocation and redistribution decisions should be grouped together in a separate group).
106+
- Group together metrics that lead to the same actionable insights (e.g. all indexing metrics that reveal which indexes/shards should be optimized could all go in one group, while resource utilization metrics like disk space or memory usage that inform allocation and redistribution decisions should be grouped together in a separate group).
107107

108108

109-
1. [Template variables](https://docs.datadoghq.com/dashboards/template_variables/) allow you to dynamically filter one or more widgets in a dashboard. Template variables must be universal and accessible by any user or account using the monitored service. Make sure all relevant graphs are listening to the relevant template variable filters. Template variables should be customized based on the type of technology.
109+
1. [Template variables](https://docs.datadoghq.com/dashboards/template_variables/) allow you to dynamically filter one or more widgets in a dashboard. Template variables must be universal and accessible by any user or account using the monitored service. Make sure all relevant graphs are listening to the relevant template variable filters. Template variables should be customized based on the type of technology.
110110

111111
| Type of integration technology | Typical Template Variable |
112112
| - | - |
@@ -157,11 +157,10 @@ A dashboard that follows best practices helps users consume data quickly. Best p
157157

158158
1. Stream widgets should be at least 6 columns wide (half the dashboard width) for readability. You should place them at the end of a dashboard so they don't "trap" scrolling. It's useful to put stream widgets in a group by themselves so they can be collapsed. Add an event stream only if the service monitored by the dashboard is reporting events. Use `sources:service_name`.
159159
![Stream widgets](../assets/images/stream_widgets.png)
160-
160+
161161
1. Always check a dashboard at 1280px wide and 2560px wide to see how it looks on a smaller laptop and a larger monitor. The most common screen widths for dashboards are 1920, 1680, 1440, 2560, and 1280px, making up more than half of all dashboard page views combined.
162162

163163
!!! tip
164164
If your monitor isn't large enough for high density mode, use the browser zoom controls to zoom out.
165165

166166
![QA at different widths](../assets/images/qa_widths.png)
167-

0 commit comments

Comments
 (0)