> For the complete documentation index, see [llms.txt](https://docs.vectra.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vectra.ai/operations/dashboards-and-reports/creating-a-custom-dashboard-rux.md). # Dashboard creation best practices Plan, build, and maintain Vectra dashboards using live data, visualizations, and AI-assisted SQL. ## Introduction Custom Dashboards help Vectra users monitor security posture, spot risks, and move from summary data into investigation. Vectra dashboards bring important security data into one view. They help teams monitor posture, identify threats, and move into investigation without switching between reports or tools. A strong dashboard helps users make faster decisions. A weak dashboard creates noise and makes analysts search for what matters. **A great dashboard should answer two questions immediately: What is happening and what should I do next?** * Show threat activity, risk trends, and entity status at a glance. * Connect KPI numbers to investigation workflows. * Use rich text widgets to explain what to look for and why it matters. * Combine AI-generated and manually written SQL queries into one clear view. * Give each audience the right level of detail. {% hint style="warning" %} **Common Dashboard Mistakes** * **Too many widgets:** Aim for 8–12. For complex analyst dashboards, keep it under 16. * **No clear audience:** Executives and analysts need fundamentally different views * **Missing context:** A number without a trend, target, or explanation is just a number * **Duplicate metrics:** The same data shown in multiple chart types wastes attention * **Makes the next action clear**: Make the next action clear—investigate, review, escalate, or confirm that no action is needed. If it is not clear, simplify the dashboard or add context. {% endhint %} ## Dashboard best practices at a glance {% stepper %} {% step %} #### [Start from an existing Vectra dashboard](#id-1.-start-from-an-existing-dashboard) Duplicate and customize rather than building from scratch. {% endstep %} {% step %} #### [Define your goal before you build](#id-2.-define-your-goal-before-you-build) Every widget should answer a question or support an action. {% endstep %} {% step %} #### [Dashboard structure best practices](#id-03.-dashboard-structure-best-practices) **Lead with the most important information** * Put key values and summary information first, then trends and investigation detail. **Add context** * Explain what users are looking at, why it matters, and what they should do next. **Name everything clearly** * Use descriptive dashboard, section, and widget names. **Pivot to more detailed investigation** * Configure **Investigate further** where users need to move from summary to detail. {% endstep %} {% step %} #### [Choosing the right content](#id-04.-choosing-the-right-content) * What belongs and what doesn't belong to a Dashboard. * Make widgets respond to dashboard filters {% endstep %} {% step %} #### [Widget types and visualization](#id-5.-widget-types-and-visualization) * Use the chart type that makes the answer easiest to understand. * Use AI to get started, then refine with SQL when needed. * Review and simplify over time. Remove content that no longer helps users make decisions. {% endstep %} {% endstepper %} *** ## 1. Start from an existing dashboard The fastest way to build a good dashboard is to start from one that already works. Vectra dashboards are already structured with the right hierarchy, labels, and widget types for common security use cases. Duplicate one, then customize it for your audience. {% hint style="success" %} ## **Recommended approach: start from an existing dashboard and customize it** Choose a Vectra dashboard that is close to your goal. Duplicate it, then adjust the data, names, labels, and guidance for your team. * **Keep the structure:** KPIs first, trends next, investigation tables near the bottom. * **Customize the data:** Update SQL or AI-generated queries for your entities, time ranges, and data sources. * **Rename to your context:** Use your team’s terms for the dashboard name, section names, and widget labels. * **Add your context:** Use rich text widgets for playbook notes, MITRE references, links, and escalation guidance. {% endhint %}

{% hint style="info" %} ## Get started in 3 steps 1. Go to **Dashboards** in the left navigation 2. Find the **Best Practice Example Dashboard** or another Vectra dashboard close to your use case. 3. Open the **three-dot menu (⋮)** and select **Duplicate**. Then rename and customize it. {% endhint %} ## 2. Define your goal before you build Answer these four questions before adding widgets. Use the answers to create a short text widget at the top of the dashboard. #### The four planning questions 1. **What is the purpose?** Monitor posture, track threat trends, support incident response, report to leadership, or investigate a specific data source. 2. **Who is the audience?**


Audience	What they need	Best widget types
Executives	Risk posture, trend direction, key KPIs	Single Value, Spiral, Donut
Security managers	Team performance, alert volume, response times	Line, Bar, Scorecard, Stack Bar
Analysts	Detailed entity data, query results, investigation paths	Table, Heatmap, Bar with drill-down
Operators	Real-time monitoring, threshold alerts, active entities	Single Value, Map, Table with filters

3. **What questions must it answer?** Examples: “How many high-risk entities are active?” “Which entities have the most detections?” “Has detection volume changed over time?” 4. **What action should viewers take?** Every dashboard should lead somewhere: a triage queue, an investigation, an escalation decision, or a clear “no action needed.” {% hint style="info" %} **The 30-second rule** Can users answer their main question in under 30 seconds? If not, simplify the dashboard or improve the hierarchy. Write down the top three questions before building. {% endhint %} ## 3. Dashboard structure best practices Use sections to guide users from summary to detail. The section structure creates the dashboard’s hierarchy.

#### Recommended section order (example) 1. **Primary answer above the fold**\ Answer the dashboard’s main question in the first visible area. 2. **Security posture summary**\ Use Single Value widgets to show what is happening now. 3. **Trend analysis**\ Use line and bar charts to show whether conditions are improving or getting worse. 4. **Entity and risk analysis**\ Use charts and ranked tables to show where users should focus. 5. **Investigation tables**\ Use detailed tables with “Investigate further” configured. 6. **Test CSV export for table widgets.** If a table widget will be shared with stakeholders, verify that its CSV export contains the expected fields and values. 7. **Context and playbooks**\ Add rich text guidance, MITRE references, links, and escalation criteria.

#### Use titles and descriptions to create structure Use widget titles and descriptions to explain what users are looking at, what they should investigate, and why it matters. | Do | Don't | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Name every section clearly
Put Single Value widgets first
Add context before widgets when needed
Make the most important widget the most prominent
Keep related widgets together

Use names like “Section 1.”
Lead with investigation tables
Mix unrelated data without labels
Give every widget equal visual emphasis
Exceed 12–16 widgets on a single dashboard

| #### Using the Content panel The Content panel lists the dashboard’s named sections. On long dashboards, users rely on it to jump directly to the information they need. Use section names that describe the content, such as **Threat posture summary** or **High-risk entities**. Avoid generic names such as **Section 1** or **Tab name**. **The 5-second test** Show the dashboard to a colleague for five seconds, then ask: * “What is this tracking?” * “What would you do if something looked wrong?” If they cannot answer, improve the section names, hierarchy, or supporting context. #### Widget count guidelines | Executive / summary | 4–8 | Risk score, top threats, trend, critical entities | | ---------------------- | ----- | --------------------------------------------------------- | | Operational monitoring | 8–12 | Alert volume, entity analysis, response time, tables | | Analyst investigation | 12–16 | Multi-source, detailed tables, drill-downs, playbook text | ## 4. Choosing the right content Not every metric belongs on a dashboard. Include only what helps the audience understand, decide, or act. #### What belongs on a Vectra dashboard * **Threat and risk KPIs:** Total alerts, risk scores, active investigations, high-risk entities * **Trends:** Alert volume over time, risk score trajectory, detection patterns by data source * **Threshold alerts:** Entities exceeding risk scores, critical severity detections * **Filters:** Time frame, data source, entity type — give analysts context control * **Rich text context:** What to look for, why it matters, MITRE references, hyperlinks, code snippets * **Investigation tables:** Configured with "Investigate further" so analysts can act directly #### Make widgets respond to dashboard filters Dashboard filters only affect widgets that are configured to use them. When creating or editing a widget, make sure its SQL includes the relevant dashboard filter variables after the `WHERE` clause. `-- AND {timeRange}` `-- AND {cloudtrail.filters}` `-- AND {contains}` Use the variables that are relevant to the widget. Some filter variables are dynamic and depend on the dashboard filters currently available. **Best practice:** If a widget intentionally should not change with dashboard filters, leave it unfiltered. Otherwise, configure it so users get consistent results when they adjust the dashboard.

#### What does not belong * Avoid large raw-data tables. Configure “**Query for investigate further clickthrough”** when creating or editing a widget for deeper analysis. * The same metric shown in several chart types * Metrics with no owner or next action * Charts that do not answer a clear question

## 5. Widget types and visualization Choose the widget type based on the question you need to answer.


Widget	Purpose	Network-focused example	User takeaway	Example
Line chart	Shows change over time so users can spot increases, drops, or unusual patterns.	Detection volume by severity over the last 30 days.	“Is network activity getting better, worse, or changing suddenly?”
Sparkline / compact trend	Shows a small trend when space is limited.	7-day trend for high-risk host count.	“Is this metric moving in the right direction?”
Area chart	Shows volume over time with more visual weight than a line chart.	Total network detections over time.	“How much activity is happening, and when did it peak?”
Scatter plot	Shows relationships or outliers across two measures.	Hosts plotted by detection count and risk score.	“Which entities stand out from normal behavior?”
Bar chart	Compares categories so users can see what ranks highest.	Top 10 hosts by detection count.	“Where should I focus first?”
Stack bar	Shows how categories change together over time.	Weekly detections grouped by severity.	“Is the mix of activity changing, or is one severity level driving the trend?”
Histogram	Compares values across categories or time buckets.	Detection count by data source.	“Which source is producing the most activity?”
Heatmap	Shows dense patterns across two dimensions.	Detection frequency by host and day of week.	“Where are repeated patterns concentrated?”
Donut / Pie	Shows a simple breakdown of a whole into a few parts.	Detections by severity: critical, high, medium, low.	“What is the overall distribution?”
Table	Shows detailed records users can investigate.	Recent detections with host, severity, timestamp, and source.	“Which specific entities or detections should I open?”
Sankey	Shows movement or relationships between sources and destinations.	Internal hosts communicating with external destinations.	“Where is activity flowing?”
Map	Shows activity by location when geography matters.	Network detections by source country or region.	“Is activity coming from unexpected locations?”
Single Value	Shows one important number users need to understand immediately.	High-risk hosts detected in the last 24 hours.	“Is there something urgent I need to look at now?”
Spiral	Shows cyclical or repeating time patterns.	Detection activity by hour across multiple days.	“Is there a recurring pattern?”
Gauge	Shows progress or status against a threshold.	Current risk score compared with an escalation threshold.	“Is this metric within an acceptable range?”
Network graph	Shows relationships between entities.	Host-to-host communication paths around a suspicious entity.	“What is connected to this entity?”
Text	Adds guidance, definitions, links, and playbook context.	Notes explaining what to investigate in a suspicious host activity section.	“What does this mean, and what should I do next?”

#### Creating widgets: AI assistant or SQL editor When you click **Add Widget**, Vectra offers two paths to create a widget query.

{% hint style="info" %} **When to use AI vs. SQL** * **Use AI assistant for a fast starting point**, common security queries, or early exploration. * **Use SQL editor for exact logic**, joins, custom filters, and detailed query changes. * **Use both**: Start with AI Assisted Query, then refine the generated SQL in the SQL Editor. {% endhint %} ## Ready to build? The fastest path to a great dashboard is to find one that's close to your goal and duplicate it. Go to Dashboards, find the **\[Sample] Discovery Dashboard**, duplicate it, and start from there. 1. Navigate to **Dashboards** in the left nav (under Hunt) 2. Find the **\[Sample] Discovery Dashboard** — or any Vectra dashboard matching your use case 3. Click ⋮ → **Duplicate**, then rename and customize for your team [Go to Dashboards ↗](https://portal.vectra.ai/discover/all)\ [View Best Practice Example Dashboard ↗](https://portal.vectra.ai/discover/best-practice-example-dashboard) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.vectra.ai/operations/dashboards-and-reports/creating-a-custom-dashboard-rux.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.