Section description explaining what will be accomplished.
- -TECHNICAL_FEATURES
- to achieve USER_BENEFITS.
-
-
- Human-readable description for the step
-Section description explaining what will be accomplished.
- -TECHNICAL_FEATURES
- to achieve USER_BENEFITS.
-
-
- Human-readable description for the step
-` for technical terms
-* For content between ``, keep to one short sentence. Do not use the name of the element being highlighted by the system. For example, instead of `The Logs menu opens the Logs page`, use `Click to open the Logs page.`
+* Keep interactive comments (`tooltip`) under 250 characters
+* Use Markdown for formatting UI elements and technical terms
+* For content in `tooltip`, keep to one short sentence. Do not use the name of the element being highlighted by the system. For example, instead of "The **Logs** menu opens the Logs page", use "Click to open the Logs page."
* Use user-centric words like those in the following list:
* Instead of visualization or card, use panel
* Instead of menu item, use the name of the menu item. For example, instead of "Click the Logs menu item", write "Click Logs."
@@ -81,45 +145,41 @@ Provide alternative workflows for different user permissions
* Instead of dropdown, use menu. For example, instead of "the Data source dropdown", write "the Data source menu"
* Instead of interface, use page, section, or panel.
* Avoid using button. For example, instead of "Click the Select button", write "Click Select."
- * Only bold titles or names of items on the GUI. For example, do not use "Click the `Logs tab`." Instead, write "Click the `Logs` tab."
+ * Only bold titles or names of items on the GUI. For example, do not use "Click the **Logs tab**." Instead, write "Click the **Logs** tab."
* Do not use integration or plugin. Find another way to describe what you mean.
- * Instead of "`menu button` (three dots)", use "log menu icon (three dots)".
+ * Instead of "**menu button** (three dots)", use "log menu icon (three dots)".
* Always include "What you will learn" before each section, and "What you have learned" after each section.
* If an item is to be clicked, only use "Click". Do not use obscure terms like "navigate to", "examine", or "check out".
* Write user-centric descriptions that match mental models
* Include context about why each step matters
-```html
-
-
-
-
- What you will learn: A brief description of your guide
- -{example-query} query {what it does and why}...
-
- See how a {query type} query looks
-incorrect port numbers, network connectivity,
- or authentication credentials.
-
- Review connection settings if test failed
-` for technical terms
+- **Formatted**: Use Markdown for UI elements and technical terms
- **Concise**: Keep under 250 characters for good UX
#### Error Prevention
- **Comprehensive requirements**: Include all necessary preconditions
- **Helpful hints**: Explain what will happen and why
- **Graceful failures**: Provide skippable options for edge cases
-- **Clear verification**: Use `data-verify` for state-changing actions
+- **Clear verification**: Use `verify` for state-changing actions
### Common Mistakes to Avoid
❌ **Missing Requirements**
-```html
-
-
+```json
+// Bad: No requirements for DOM interaction
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save']"
+}
```
✅ **Good: Includes necessary requirements**
-```html
-
+```json
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save']",
+ "requirements": ["exists-reftarget", "on-page:/dashboard"]
+}
```
❌ **Unclear Selectors**
-```html
-
-
+```json
+// Bad: Brittle CSS class selector
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": ".btn-primary.save-button"
+}
```
✅ **Good: Stable attribute-based selector**
-```html
-
+```json
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save-dashboard']"
+}
```
❌ **Missing Context**
-```html
-
-
+```json
+// Bad: No explanation of what will happen
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input",
+ "targetvalue": "value"
+}
```
✅ **Good: Clear context and purpose**
-```html
-
+```json
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='name']",
+ "targetvalue": "prometheus",
+ "tooltip": "Sets a descriptive name for easy identification"
+}
```
❌ **Overly Complex Steps**
-```html
-
-
-
-
-
-
-
-
- Navigate to admin, go to users, add user, fill details, create user
-
+```json
+// Bad: Too many actions in one step
+{
+ "type": "multistep",
+ "content": "Navigate to admin, go to users, add user, fill details, create user",
+ "steps": [
+ {"action": "navigate", "reftarget": "/admin"},
+ {"action": "button", "reftarget": "Users"},
+ {"action": "button", "reftarget": "Add user"},
+ {"action": "formfill", "reftarget": "input[id='name']", "targetvalue": "john"},
+ {"action": "formfill", "reftarget": "input[id='email']", "targetvalue": "john@example.com"},
+ {"action": "button", "reftarget": "Create"}
+ ]
+}
```
✅ **Good: Broken into logical sections**
-```html
-
- Navigate to user management
- Start adding new user
-
-
-
- Fill user details
-
- Create the user account
-
-```# Common Interactive Workflow Patterns for AI
-
-## Standard Workflow Templates
-
-### Data Source Setup Workflow
-```html
-
-
- Set Up {DataSource} Data Source
-
-
- -
- Navigate to data source management
-
-
- -
- Click Add new data source
-
-
- -
- Select {DataSource} from the list
-
-
- -
- Name your data source
-
-
- -
- Set the server URL
-
-
- -
- Save and test the connection
-
-
-
-```
-
-### Dashboard Creation Workflow
-```html
-
-
- Create {Purpose} Dashboard
-
-
- -
- Navigate to create new dashboard
-
-
- -
- Add your first panel
-
-
- -
- Select your data source
-
-
- -
- Enter your query
-
-
- -
- Set panel title
-
-
- -
- Save your dashboard
-
-
-
-```
-
-### Plugin Installation Workflow
-```html
-
-
- Install {Plugin Name} Plugin
-
-
- -
- Navigate to plugin management
-
-
- -
- Search for the plugin
-
-
- -
- Find the plugin in search results
-
-
- -
- Install the plugin
-
-
-
-```
-
-### Alert Rule Creation Workflow
-```html
-
-
- Create {Metric} Alert Rule
-
-
- -
- Navigate to create alert rule
-
-
- -
- Name your alert rule
-
-
- -
- Select data source
-
-
- -
- Enter alert query
-
-
- -
- Set alert threshold
-
-
- -
- Save the alert rule
-
-
-
-```
-
-## Data Source Specific Patterns
-
-### Prometheus Setup
-```html
-
-
- - Go to data sources
- - Add data source
- - Select Prometheus
- - Name it
- - Set URL
- - Save and test
-
-
-```
-
-### Loki Setup
-```html
-
-
- - Go to data sources
- - Add data source
- - Select Loki
- - Name it
- - Set URL
- - Save and test
-
-
-```
-
-### InfluxDB Setup
-```html
-
-
- - Go to data sources
- - Add data source
- - Select InfluxDB
- - Name it
- - Set URL
- - Set database
- - Save and test
-
-
-```
-
-## Visualization Creation Patterns
-
-### Time Series Panel
-```html
-
-
- - Add panel
- - Select Prometheus
- - Enter rate query
- - Select time series
- - Set title
- - Apply changes
-
-
-```
-
-### Stat Panel
-```html
-
-
- - Add panel
- - Select Prometheus
- - Enter up query
- - Select stat visualization
- - Set title
- - Apply changes
-
-
-```
-
-### Table Panel
-```html
-
-
- - Add panel
- - Select Prometheus
- - Enter up query
- - Select table visualization
- - Set title
- - Apply changes
-
-
-```
-
-## Query Pattern Library
-
-### Prometheus Queries
-```html
-
-
- Check which targets are up
-
-
-
-
- Calculate request rate over 5 minutes
-
-
-
-
- Calculate CPU usage percentage
-
-
-
-
- Calculate memory usage percentage
-
-
-
-
- Calculate disk usage percentage
-
-```
-
-### Loki Queries
-```html
-
-
- Query Grafana service logs
-
-
-
-
- Filter for error messages
-
-
-
-
- Calculate log rate
-
-
-
-
- Parse JSON logs and filter by level
-
-```
-
-## Educational Pattern Library
-
-### Interface Explanation Pattern
-```html
-
-
-
- This {UI_ELEMENT_NAME} {what_it_does}.
- {why_its_important}. {specific_capabilities_or_features}.
-
-
- Learn about the {UI_ELEMENT_NAME}
-
-```
-
-### Feature Introduction Pattern
-```html
-
-
- Understanding {Feature Name}
-
-
-
- -
- {Feature overview explanation}
- Explore the main {feature} interface
-
-
-
- -
- {Control explanation}
- Notice the {control name} controls
-
-
-
- -
- {Example explanation}
- See how {feature} displays information
-
-
-
-```
-
-### Concept-to-Practice Pattern
-```html
-
-
-
- The query editor is where you write {query language} queries...
-
- Learn about writing queries
-
-
-
-
-
- This {example-query} query {what it does and why}...
-
- See how a {query type} query looks
-
-
-
-
- Now enter your own {query type} query
-
-
-
-
- Run the query to see results
-
-```
-
-## Multi-Step Patterns
-
-### Quick Multi-Actions
-```html
-
-
-
-
- Add visualization and select {datasource} data source
-
-
-
-
-
-
- Go to plugins and search for {plugin name}
-
-
-
-
-
-
-
- Fill name and URL, then test connection
-
-```
-
-## Permission-Aware Patterns
-
-### Admin vs User Workflows
-```html
-
-
- Complete Setup (Admin)
-
- - Install plugins
- - Configure data sources
- - Manage users
-
-
-
-
-
- User Setup (Non-Admin)
-
- - Browse dashboards
- - Try data exploration
- -
-
- Contact your administrator to request additional permissions
- for creating dashboards, configuring data sources, or installing plugins.
-
- Know how to request additional access
-
-
-
-```
-
-### Skippable Feature Patterns
-```html
-
-
- Use advanced query expressions (skip if not supported)
-
-
-
-
- Open custom application (skip if plugin not installed)
-
-```
-
-## Error Recovery Patterns
-
-### Primary + Fallback Pattern
-```html
-
-
- Use automatic setup wizard
-
-
-
-
- Or configure data source manually
-
-```
-
-### Validation and Retry Pattern
-```html
-
-
- Test the data source connection
-
-
-
-
-
- If the connection test failed, verify your URL and
- authentication settings. Common issues include
- incorrect port numbers, network connectivity,
- or authentication credentials.
-
- Review connection settings if test failed
-
-```
-
-## AI Content Generation Guidelines
-
-### Step-by-Step Generation Process
-
-1. **Analyze User Request**
- - Identify the main goal/outcome
- - Determine required Grafana features
- - Assess user permission requirements
- - Plan logical step progression
-
-2. **Choose Guide Structure**
- - Single workflow → one section
- - Complex workflow → multiple sections
- - Educational content → mix show-only and regular steps
- - Quick actions → multistep elements
-
-3. **Generate Requirements**
- - Always include `exists-reftarget` for DOM actions
- - Add `navmenu-open` for navigation elements
- - Include page requirements for page-specific actions
- - Add permission requirements for admin features
- - Include data/plugin requirements for dependent features
-
-4. **Add Objectives Where Appropriate**
- - Use for expensive setup steps that might already be done
- - Include for navigation when user might already be on target page
- - Add for state checks that auto-complete workflows
-
-5. **Write Helpful Content**
- - Clear step descriptions that match user mental model
- - Interactive comments for complex UI elements
- - Hints that provide context and guidance
- - Error handling for edge cases
-
-### Content Quality Rules
-
-#### Step Descriptions
-- **Action-focused**: "Click Save button" not "The save button can be clicked"
-- **User-centric**: "Save your dashboard" not "Execute save action"
-- **Context-aware**: "Enter Prometheus server URL" not "Enter URL"
-- **Goal-oriented**: "Create monitoring dashboard" not "Fill out form"
-
-#### Interactive Comments
-- **Educational**: Explain what elements do and why they matter
-- **Contextual**: Provide information that helps users understand
-- **Formatted**: Use `` for UI elements, `` for technical terms
-- **Concise**: Keep under 250 characters for good UX
-
-#### Error Prevention
-- **Comprehensive requirements**: Include all necessary preconditions
-- **Helpful hints**: Explain what will happen and why
-- **Graceful failures**: Provide skippable options for edge cases
-- **Clear verification**: Use `data-verify` for state-changing actions
-
-### Common Mistakes to Avoid
-
-❌ **Missing Requirements**
-```html
-
-
-```
-✅ **Good: Includes necessary requirements**
-```html
-
-```
-
-❌ **Unclear Selectors**
-```html
-
-
+```json
+{
+ "type": "section",
+ "id": "user-management",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/admin/users",
+ "content": "Navigate to user management"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Add user",
+ "content": "Start adding new user"
+ },
+ {
+ "type": "multistep",
+ "content": "Fill user details",
+ "steps": [
+ {"action": "formfill", "reftarget": "input[id='name']", "targetvalue": "john"},
+ {"action": "formfill", "reftarget": "input[id='email']", "targetvalue": "john@example.com"}
+ ]
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Create user",
+ "content": "Create the user account"
+ }
+ ]
+}
```
-✅ **Good: Stable attribute-based selector**
-```html
-
-```
-
-❌ **Missing Context**
-```html
-
-
-```
-✅ **Good: Clear context and purpose**
-```html
-
-```
-
-❌ **Overly Complex Steps**
-```html
-
-
-
-
-
-
-
-
- Navigate to admin, go to users, add user, fill details, create user
-
-```
-✅ **Good: Broken into logical sections**
-```html
-
- Navigate to user management
- Start adding new user
-
-
-
- Fill user details
-
- Create the user account
-
-```
\ No newline at end of file
diff --git a/.cursor/complete-example-tutorial.mdc b/.cursor/complete-example-tutorial.mdc
index 480c47c2d..6c290f041 100644
--- a/.cursor/complete-example-tutorial.mdc
+++ b/.cursor/complete-example-tutorial.mdc
@@ -8,1251 +8,466 @@ alwaysApply: true
This complete guide demonstrates all interactive features and best practices. Use this as a template for creating comprehensive guides.
-```html
-
-
-
-
- Advanced Grafana Monitoring Setup
-
-
- Advanced Grafana Monitoring Setup
-
- Welcome to the complete Grafana monitoring setup guide! This comprehensive guide will teach you:
-
- - Setting up multiple data sources (Prometheus, Loki)
- - Creating effective monitoring dashboards
- - Configuring intelligent alerting rules
- - Understanding advanced Grafana features
-
-
-
- Section 1: Grafana Interface Overview
- Before we start building, let's explore Grafana's interface to understand where everything is located.
-
-
-
-
- -
-
- The navigation menu is your control center for accessing all Grafana features.
- It organizes tools by function:
Dashboards for visualizations,
- Explore for ad-hoc queries, Alerting for monitoring,
- and Administration for system management.
-
- Explore the main navigation structure
-
-
-
- -
-
- The main content area is where you'll spend most of your time.
- It displays dashboards, configuration pages, query interfaces,
- and all the tools you need for effective observability.
-
- This is where your monitoring work happens
-
-
-
- -
-
- The top header contains global controls available from any page:
-
organization switcher, user preferences, help resources,
- and global search. These tools support your workflow regardless of where you are in Grafana.
-
- Notice the global controls in the header
-
-
-
-
-
- Section 2: Configure Prometheus Data Source
- Now let's set up Prometheus as our metrics data source. This will provide the foundation for all our monitoring dashboards.
-
-
-
-
- -
- Navigate to data source management
-
-
-
- -
- Click Add new data source
-
-
-
- -
-
- Prometheus is a powerful monitoring system that collects
-
time-series metrics from your applications and infrastructure.
- It's perfect for tracking performance indicators, resource usage,
- and application health.
-
- Select Prometheus from the data source types
-
-
-
- -
- Set a descriptive name for the data source
-
-
-
- -
-
- The Prometheus URL tells Grafana where to find your metrics server.
- Port
9090 is the standard Prometheus port. In production, this might be
- https://prometheus.company.com or an internal service address.
-
- Enter the Prometheus server URL
-
-
-
- -
- Save and test the connection
-
-
-
-
-
- Section 3: Create Monitoring Dashboard
- With our data source configured, let's create a comprehensive monitoring dashboard with multiple visualization types.
-
-
-
-
- -
- Navigate to create a new dashboard
-
-
-
- -
-
-
-
-
-
- Add visualization and select Prometheus data source
-
-
-
- -
-
- The
up query shows how many monitoring targets are healthy.
- This is a fundamental availability metric that tells you
- if your monitoring infrastructure is working correctly.
-
- Enter the availability query
-
-
-
- -
-
-
-
-
-
- Open visualization picker and select Stat
-
-
-
- -
- Set descriptive panel title
-
-
-
- -
- Apply the panel configuration
-
-
-
- -
- Add a second panel for trend analysis
-
-
-
- -
-
-
-
-
-
-
-
- Add visualization, select Prometheus, and enter CPU usage query
-
-
-
- -
-
- Time series visualizations are perfect for showing how metrics
- change over time. This
CPU usage percentage calculation helps you
- understand resource utilization patterns and plan capacity accordingly.
-
- Set time series panel title
-
-
-
- -
- Apply the time series panel
-
-
-
- -
-
-
-
-
-
-
-
- Save dashboard with title "System Monitoring"
-
-
-
-
-
- Section 4: Configure Monitoring Alerts
- Now let's set up intelligent alerts to notify you when system issues occur, before your users notice them.
-
-
-
-
- -
- Navigate to create new alert rule
-
-
-
- -
-
- The alert rule form lets you define monitoring conditions that trigger notifications.
- You'll specify
query conditions, evaluation frequency,
- threshold values, and notification channels to create
- proactive monitoring that keeps your systems healthy.
-
- Examine the alert rule configuration interface
-
-
-
- -
- Name your alert rule descriptively
-
-
-
- -
- Select Prometheus as the alert data source
-
-
-
- -
-
- This alert query triggers when CPU usage exceeds 80%.
- The
rate() function calculates per-second CPU usage,
- and the condition > 80 defines our threshold
- for what constitutes "high" CPU usage.
-
- Enter CPU usage alert condition
-
-
-
- -
- Set evaluation interval to 1 minute
-
-
-
- -
- Save the alert rule
-
-
-
-
-
- Section 5: Explore Advanced Features
- Let's explore some of Grafana's advanced features that can enhance your monitoring experience.
-
-
-
-
- -
- Explore the query library feature (skip if not available)
-
-
-
- -
- Navigate to Explore for ad-hoc queries
-
-
-
- -
-
- Explore is your data investigation playground. Write queries,
- test hypotheses, and analyze metrics without creating permanent dashboards.
- It's perfect for incident troubleshooting and data discovery.
-
- Learn about the Explore interface
-
-
-
- -
- Access plugin management (admin only)
-
-
-
- -
-
- Plugins extend Grafana's capabilities with new data sources,
- panel types, and applications. While you need
admin privileges
- to install plugins, you can use any plugins that are already installed
- in your Grafana instance.
-
- Learn about Grafana's plugin ecosystem
-
-
-
-
-
- Section 6: Verify Your Setup
- Let's verify everything is working correctly and explore your new monitoring capabilities.
-
-
-
-
- -
- Return to your dashboards list
-
-
-
- -
-
- Your System Monitoring dashboard now appears in the dashboard list.
- The
star icon lets you favorite it for quick access, and the
- menu button provides options for sharing, exporting, or managing permissions.
-
- Find your newly created monitoring dashboard
-
-
-
- -
- Open your System Monitoring dashboard
-
-
-
- -
-
- Your Targets Up panel shows real-time availability data.
- The large number indicates how many monitoring targets are healthy.
- This gives you an instant overview of your infrastructure health.
-
- Review your availability monitoring panel
-
-
-
- -
-
- The time range picker controls what time period your dashboard displays.
- Try
Last 1 hour for recent data, Last 24 hours for daily patterns,
- or Last 7 days for weekly trend analysis.
-
- Notice the time range controls
-
-
-
- -
-
- The refresh button updates your dashboard with the latest data.
- You can also enable
auto-refresh to keep your monitoring views
- current without manual intervention - perfect for live monitoring scenarios.
-
- Learn about dashboard refresh options
-
-
-
-
-
- 🎉 Congratulations!
- Outstanding work! You've successfully completed the advanced Grafana monitoring setup guide. You now have:
-
- - ✅ Comprehensive Interface Knowledge - You understand Grafana's layout and navigation
- - ✅ Prometheus Data Source - Connected and tested for reliable metrics collection
- - ✅ System Monitoring Dashboard - Multiple panel types showing different aspects of system health
- - ✅ Intelligent Alerting - Proactive monitoring that notifies you of issues
- - ✅ Advanced Feature Awareness - Knowledge of Explore, plugins, and additional capabilities
-
-
- What You Can Do Next
-
- - Expand Your Dashboard - Add more panels for memory, disk, and network monitoring
- - Configure More Alerts - Set up alerts for different metrics and thresholds
- - Explore Data Sources - Connect Loki for logs, Tempo for traces, or other systems
- - Team Collaboration - Share dashboards with your team and set up notification channels
- - Advanced Queries - Learn more complex PromQL for sophisticated monitoring
-
-
- Next Recommended Guide: Loki + Grafana 101 to add log monitoring to your observability stack.
-
-
-
-```
-
-## Key Features Demonstrated
-
-### 1. Show-Only Educational Mode
-- Interface orientation without state changes
-- Rich interactive comments with formatting
-- Progressive disclosure of concepts
-
-### 2. Requirements and Objectives System
-- Auto-completion when objectives already met
-- Permission-aware workflows
-- Graceful degradation for missing requirements
-
-### 3. Multi-Step Atomic Actions
-- Complex UI workflows as single user actions
-- Just-in-time requirements checking
-- Error handling with specific failure points
-
-### 4. Section-Based Organization
-- Logical grouping of related steps
-- Progress persistence across browser sessions
-- Sequential dependencies between sections
-
-### 5. Advanced Error Handling
-- Skippable steps for permission issues
-- Alternative workflows for different user types
-- Helpful error messages with context
-
-### 6. Performance Optimization
-- Efficient selector usage
-- Grouped requirement checks
-- Lazy evaluation of complex conditions
-
-### 7. Accessibility Features
-- Screen reader friendly hints
-- Keyboard navigation support
-- ARIA attribute integration
-
-## Guide Quality Characteristics
-
-### Educational Value
-- **Progressive Learning**: Concepts introduced before practice
-- **Contextual Explanations**: Rich comments explain why things matter
-- **Multiple Learning Modes**: Observation, demonstration, and hands-on practice
-- **Real-World Relevance**: Practical skills applicable to actual monitoring
-
-### Technical Excellence
-- **Robust Error Handling**: Graceful failure and recovery options
-- **Cross-Version Compatibility**: Works across different Grafana versions
-- **Performance Conscious**: Efficient selectors and requirement checking
-- **Accessibility Compliant**: Works with assistive technologies
-
-### User Experience
-- **Clear Progress Indicators**: Users always know where they are
-- **Resumable Workflows**: Can continue after interruptions
-- **Helpful Guidance**: Hints and comments provide context
-- **Flexible Paths**: Alternatives for different user capabilities
-
-This example demonstrates the full power of the interactive guide system and serves as a comprehensive template for creating high-quality, educational Grafana guides.# Complete Example Guide - All Features Demonstration
-
-## Guide: Advanced Grafana Monitoring Setup
-
-This complete guide demonstrates all interactive features and best practices. Use this as a template for creating comprehensive guides.
-
-```html
-
-
-
-
- Advanced Grafana Monitoring Setup
-
-
- Advanced Grafana Monitoring Setup
-
- Welcome to the complete Grafana monitoring setup guide! This comprehensive guide will teach you:
-
- - Setting up multiple data sources (Prometheus, Loki)
- - Creating effective monitoring dashboards
- - Configuring intelligent alerting rules
- - Understanding advanced Grafana features
-
-
-
- Section 1: Grafana Interface Overview
- Before we start building, let's explore Grafana's interface to understand where everything is located.
-
-
-
-
- -
-
- The navigation menu is your control center for accessing all Grafana features.
- It organizes tools by function:
Dashboards for visualizations,
- Explore for ad-hoc queries, Alerting for monitoring,
- and Administration for system management.
-
- Explore the main navigation structure
-
-
-
- -
-
- The main content area is where you'll spend most of your time.
- It displays dashboards, configuration pages, query interfaces,
- and all the tools you need for effective observability.
-
- This is where your monitoring work happens
-
-
-
- -
-
- The top header contains global controls available from any page:
-
organization switcher, user preferences, help resources,
- and global search. These tools support your workflow regardless of where you are in Grafana.
-
- Notice the global controls in the header
-
-
-
-
-
- Section 2: Configure Prometheus Data Source
- Now let's set up Prometheus as our metrics data source. This will provide the foundation for all our monitoring dashboards.
-
-
-
-
- -
- Navigate to data source management
-
-
-
- -
- Click Add new data source
-
-
-
- -
-
- Prometheus is a powerful monitoring system that collects
-
time-series metrics from your applications and infrastructure.
- It's perfect for tracking performance indicators, resource usage,
- and application health.
-
- Select Prometheus from the data source types
-
-
-
- -
- Set a descriptive name for the data source
-
-
-
- -
-
- The Prometheus URL tells Grafana where to find your metrics server.
- Port
9090 is the standard Prometheus port. In production, this might be
- https://prometheus.company.com or an internal service address.
-
- Enter the Prometheus server URL
-
-
-
- -
- Save and test the connection
-
-
-
-
-
- Section 3: Create Monitoring Dashboard
- With our data source configured, let's create a comprehensive monitoring dashboard with multiple visualization types.
-
-
-
-
- -
- Navigate to create a new dashboard
-
-
-
- -
-
-
-
-
-
- Add visualization and select Prometheus data source
-
-
-
- -
-
- The
up query shows how many monitoring targets are healthy.
- This is a fundamental availability metric that tells you
- if your monitoring infrastructure is working correctly.
-
- Enter the availability query
-
-
-
- -
-
-
-
-
-
- Open visualization picker and select Stat
-
-
-
- -
- Set descriptive panel title
-
-
-
- -
- Apply the panel configuration
-
-
-
- -
- Add a second panel for trend analysis
-
-
-
- -
-
-
-
-
-
-
-
- Add visualization, select Prometheus, and enter CPU usage query
-
-
-
- -
-
- Time series visualizations are perfect for showing how metrics
- change over time. This
CPU usage percentage calculation helps you
- understand resource utilization patterns and plan capacity accordingly.
-
- Set time series panel title
-
-
-
- -
- Apply the time series panel
-
-
-
- -
-
-
-
-
-
-
-
- Save dashboard with title "System Monitoring"
-
-
-
-
-
- Section 4: Configure Monitoring Alerts
- Now let's set up intelligent alerts to notify you when system issues occur, before your users notice them.
-
-
-
-
- -
- Navigate to create new alert rule
-
-
-
- -
-
- The alert rule form lets you define monitoring conditions that trigger notifications.
- You'll specify
query conditions, evaluation frequency,
- threshold values, and notification channels to create
- proactive monitoring that keeps your systems healthy.
-
- Examine the alert rule configuration interface
-
-
-
- -
- Name your alert rule descriptively
-
-
-
- -
- Select Prometheus as the alert data source
-
-
-
- -
-
- This alert query triggers when CPU usage exceeds 80%.
- The
rate() function calculates per-second CPU usage,
- and the condition > 80 defines our threshold
- for what constitutes "high" CPU usage.
-
- Enter CPU usage alert condition
-
-
-
- -
- Set evaluation interval to 1 minute
-
-
-
- -
- Save the alert rule
-
-
-
-
-
- Section 5: Explore Advanced Features
- Let's explore some of Grafana's advanced features that can enhance your monitoring experience.
-
-
-
-
- -
- Explore the query library feature (skip if not available)
-
-
-
- -
- Navigate to Explore for ad-hoc queries
-
-
-
- -
-
- Explore is your data investigation playground. Write queries,
- test hypotheses, and analyze metrics without creating permanent dashboards.
- It's perfect for incident troubleshooting and data discovery.
-
- Learn about the Explore interface
-
-
-
- -
- Access plugin management (admin only)
-
-
-
- -
-
- Plugins extend Grafana's capabilities with new data sources,
- panel types, and applications. While you need
admin privileges
- to install plugins, you can use any plugins that are already installed
- in your Grafana instance.
-
- Learn about Grafana's plugin ecosystem
-
-
-
-
-
- Section 6: Verify Your Setup
- Let's verify everything is working correctly and explore your new monitoring capabilities.
-
-
-
-
- -
- Return to your dashboards list
-
-
-
- -
-
- Your System Monitoring dashboard now appears in the dashboard list.
- The
star icon lets you favorite it for quick access, and the
- menu button provides options for sharing, exporting, or managing permissions.
-
- Find your newly created monitoring dashboard
-
-
-
- -
- Open your System Monitoring dashboard
-
-
-
- -
-
- Your Targets Up panel shows real-time availability data.
- The large number indicates how many monitoring targets are healthy.
- This gives you an instant overview of your infrastructure health.
-
- Review your availability monitoring panel
-
-
-
- -
-
- The time range picker controls what time period your dashboard displays.
- Try
Last 1 hour for recent data, Last 24 hours for daily patterns,
- or Last 7 days for weekly trend analysis.
-
- Notice the time range controls
-
-
-
- -
-
- The refresh button updates your dashboard with the latest data.
- You can also enable
auto-refresh to keep your monitoring views
- current without manual intervention - perfect for live monitoring scenarios.
-
- Learn about dashboard refresh options
-
-
-
-
-
- 🎉 Congratulations!
- Outstanding work! You've successfully completed the advanced Grafana monitoring setup guide. You now have:
-
- - ✅ Comprehensive Interface Knowledge - You understand Grafana's layout and navigation
- - ✅ Prometheus Data Source - Connected and tested for reliable metrics collection
- - ✅ System Monitoring Dashboard - Multiple panel types showing different aspects of system health
- - ✅ Intelligent Alerting - Proactive monitoring that notifies you of issues
- - ✅ Advanced Feature Awareness - Knowledge of Explore, plugins, and additional capabilities
-
-
- What You Can Do Next
-
- - Expand Your Dashboard - Add more panels for memory, disk, and network monitoring
- - Configure More Alerts - Set up alerts for different metrics and thresholds
- - Explore Data Sources - Connect Loki for logs, Tempo for traces, or other systems
- - Team Collaboration - Share dashboards with your team and set up notification channels
- - Advanced Queries - Learn more complex PromQL for sophisticated monitoring
-
-
- Next Recommended Guide: Loki + Grafana 101 to add log monitoring to your observability stack.
-
-
-
+```json
+{
+ "id": "advanced-grafana-monitoring",
+ "title": "Advanced Grafana Monitoring Setup",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# Advanced Grafana Monitoring Setup\n\nWelcome to the complete Grafana monitoring setup guide! This comprehensive guide will teach you:\n\n- Setting up multiple data sources (Prometheus, Loki)\n- Creating effective monitoring dashboards\n- Configuring intelligent alerting rules\n- Understanding advanced Grafana features"
+ },
+ {
+ "type": "section",
+ "id": "interface-tour",
+ "title": "Section 1: Grafana Interface Overview",
+ "tooltip": "Educational tour of Grafana's main interface elements",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Before we start building, let's explore Grafana's interface to understand where everything is located."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "nav[data-testid='navigation-mega-menu']",
+ "requirements": ["navmenu-open"],
+ "doIt": false,
+ "tooltip": "The navigation menu is your control center for accessing all Grafana features. It organizes tools by function: Dashboards for visualizations, Explore for ad-hoc queries, Alerting for monitoring, and Administration for system management.",
+ "content": "Explore the main navigation structure"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "main[data-testid='main-content']",
+ "doIt": false,
+ "tooltip": "The main content area is where you'll spend most of your time. It displays dashboards, configuration pages, query interfaces, and all the tools you need for effective observability.",
+ "content": "This is where your monitoring work happens"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "header[data-testid='grafana-app-header']",
+ "doIt": false,
+ "tooltip": "The top header contains global controls available from any page: organization switcher, user preferences, help resources, and global search. These tools support your workflow regardless of where you are in Grafana.",
+ "content": "Notice the global controls in the header"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "setup-prometheus",
+ "title": "Section 2: Configure Prometheus Data Source",
+ "requirements": ["is-admin"],
+ "objectives": ["has-datasource:type:prometheus"],
+ "tooltip": "Creates Prometheus data source - skipped if already configured",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Now let's set up Prometheus as our metrics data source. This will provide the foundation for all our monitoring dashboards."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/connections/datasources",
+ "requirements": ["navmenu-open"],
+ "verify": "on-page:/connections",
+ "content": "Navigate to data source management"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Add new data source",
+ "requirements": ["exists-reftarget"],
+ "content": "Click Add new data source"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[href='/connections/datasources/prometheus']",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Prometheus is a powerful monitoring system that collects time-series metrics from your applications and infrastructure. It's perfect for tracking performance indicators, resource usage, and application health.",
+ "content": "Select Prometheus from the data source types"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='basic-settings-name']",
+ "targetvalue": "prometheus-main",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Descriptive names help identify data sources in large deployments",
+ "content": "Set a descriptive name for the data source"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='connection-url']",
+ "targetvalue": "http://prometheus:9090",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "The Prometheus URL tells Grafana where to find your metrics server. Port 9090 is the standard Prometheus port. In production, this might be https://prometheus.company.com or an internal service address.",
+ "content": "Enter the Prometheus server URL"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save & test",
+ "requirements": ["exists-reftarget"],
+ "verify": "has-datasource:prometheus-main",
+ "content": "Save and test the connection"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "create-monitoring-dashboard",
+ "title": "Section 3: Create Monitoring Dashboard",
+ "requirements": ["section-completed:setup-prometheus"],
+ "objectives": ["has-dashboard-named:System Monitoring"],
+ "tooltip": "Creates comprehensive monitoring dashboard with multiple panels",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "With our data source configured, let's create a comprehensive monitoring dashboard with multiple visualization types."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/dashboard/new",
+ "requirements": ["navmenu-open"],
+ "verify": "on-page:/dashboard/new",
+ "content": "Navigate to create a new dashboard"
+ },
+ {
+ "type": "multistep",
+ "requirements": ["on-page:/dashboard/new"],
+ "tooltip": "Creates a stat panel showing system availability",
+ "content": "Add visualization and select Prometheus data source",
+ "steps": [
+ {
+ "action": "button",
+ "reftarget": "Add visualization",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "prometheus-main",
+ "requirements": ["has-datasource:prometheus-main"]
+ }
+ ]
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "up",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "The up query shows how many monitoring targets are healthy. This is a fundamental availability metric that tells you if your monitoring infrastructure is working correctly.",
+ "content": "Enter the availability query"
+ },
+ {
+ "type": "multistep",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Changes to stat visualization for single-value display",
+ "content": "Open visualization picker and select Stat",
+ "steps": [
+ {
+ "action": "button",
+ "reftarget": "button[data-testid='toggle-viz-picker']",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "highlight",
+ "reftarget": "div[aria-label='Plugin visualization item Stat']",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='Panel editor option pane field input Title']",
+ "targetvalue": "Targets Up",
+ "requirements": ["exists-reftarget"],
+ "content": "Set descriptive panel title"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Apply",
+ "requirements": ["exists-reftarget"],
+ "content": "Apply the panel configuration"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Add panel",
+ "requirements": ["exists-reftarget", "on-page:/dashboard"],
+ "content": "Add a second panel for trend analysis"
+ },
+ {
+ "type": "multistep",
+ "requirements": ["on-page:/dashboard"],
+ "tooltip": "Creates time series panel for CPU usage trends",
+ "content": "Add visualization, select Prometheus, and enter CPU usage query",
+ "steps": [
+ {
+ "action": "button",
+ "reftarget": "Add visualization",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "prometheus-main",
+ "requirements": ["has-datasource:prometheus-main"]
+ },
+ {
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "100 - (avg(rate(node_cpu_seconds_total{mode='idle'}[5m])) * 100)",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='Panel editor option pane field input Title']",
+ "targetvalue": "CPU Usage %",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Time series visualizations are perfect for showing how metrics change over time. This CPU usage percentage calculation helps you understand resource utilization patterns and plan capacity accordingly.",
+ "content": "Set time series panel title"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Apply",
+ "requirements": ["exists-reftarget"],
+ "content": "Apply the time series panel"
+ },
+ {
+ "type": "multistep",
+ "requirements": ["on-page:/dashboard"],
+ "tooltip": "Saves dashboard with descriptive title",
+ "content": "Save dashboard with title 'System Monitoring'",
+ "steps": [
+ {
+ "action": "button",
+ "reftarget": "Save dashboard",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "formfill",
+ "reftarget": "input[aria-label='Save dashboard title field']",
+ "targetvalue": "System Monitoring",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Save",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "setup-alerting",
+ "title": "Section 4: Configure Monitoring Alerts",
+ "requirements": ["section-completed:create-monitoring-dashboard", "has-permission:alerting:write"],
+ "tooltip": "Configures CPU usage alert - requires alerting permissions",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Now let's set up intelligent alerts to notify you when system issues occur, before your users notice them."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/alerting/new",
+ "requirements": ["navmenu-open"],
+ "verify": "on-page:/alerting/new",
+ "content": "Navigate to create new alert rule"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='alert-rule-form']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "tooltip": "The alert rule form lets you define monitoring conditions that trigger notifications. You'll specify query conditions, evaluation frequency, threshold values, and notification channels to create proactive monitoring that keeps your systems healthy.",
+ "content": "Examine the alert rule configuration interface"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='alert-rule-name']",
+ "targetvalue": "High CPU Usage Alert",
+ "requirements": ["exists-reftarget"],
+ "content": "Name your alert rule descriptively"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "prometheus-main",
+ "requirements": ["has-datasource:prometheus-main", "exists-reftarget"],
+ "content": "Select Prometheus as the alert data source"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='alert-query-editor']",
+ "targetvalue": "100 - (avg(rate(node_cpu_seconds_total{mode='idle'}[5m])) * 100) > 80",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "This alert query triggers when CPU usage exceeds 80%. The rate() function calculates per-second CPU usage, and the condition > 80 defines our threshold for what constitutes 'high' CPU usage.",
+ "content": "Enter CPU usage alert condition"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='evaluation-interval']",
+ "targetvalue": "1m",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "How often Grafana checks this condition",
+ "content": "Set evaluation interval to 1 minute"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save rule",
+ "requirements": ["exists-reftarget"],
+ "content": "Save the alert rule"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "advanced-features",
+ "title": "Section 5: Explore Advanced Features",
+ "requirements": ["section-completed:setup-alerting"],
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Let's explore some of Grafana's advanced features that can enhance your monitoring experience."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/explore",
+ "requirements": ["navmenu-open", "has-feature:queryLibrary", "min-version:8.5.0"],
+ "skippable": true,
+ "tooltip": "Query library requires specific Grafana version and feature toggle",
+ "verify": "on-page:/explore",
+ "content": "Explore the query library feature (skip if not available)"
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/explore",
+ "requirements": ["navmenu-open"],
+ "verify": "on-page:/explore",
+ "content": "Navigate to Explore for ad-hoc queries"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='query-editor-container']",
+ "requirements": ["on-page:/explore", "exists-reftarget"],
+ "doIt": false,
+ "tooltip": "Explore is your data investigation playground. Write queries, test hypotheses, and analyze metrics without creating permanent dashboards. It's perfect for incident troubleshooting and data discovery.",
+ "content": "Learn about the Explore interface"
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/admin/plugins",
+ "requirements": ["is-admin", "navmenu-open"],
+ "skippable": true,
+ "tooltip": "Plugin management requires admin privileges",
+ "verify": "on-page:/admin/plugins",
+ "content": "Access plugin management (admin only)"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='plugin-info']",
+ "requirements": ["has-role:viewer"],
+ "doIt": false,
+ "tooltip": "Plugins extend Grafana's capabilities with new data sources, panel types, and applications. While you need admin privileges to install plugins, you can use any plugins that are already installed in your Grafana instance.",
+ "content": "Learn about Grafana's plugin ecosystem"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "verify-setup",
+ "title": "Section 6: Verify Your Setup",
+ "requirements": ["section-completed:create-monitoring-dashboard"],
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Let's verify everything is working correctly and explore your new monitoring capabilities."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/dashboards",
+ "requirements": ["navmenu-open"],
+ "verify": "on-page:/dashboards",
+ "content": "Return to your dashboards list"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[title*='System Monitoring']",
+ "requirements": ["has-dashboard-named:System Monitoring", "exists-reftarget"],
+ "doIt": false,
+ "tooltip": "Your System Monitoring dashboard now appears in the dashboard list. The star icon lets you favorite it for quick access, and the menu button provides options for sharing, exporting, or managing permissions.",
+ "content": "Find your newly created monitoring dashboard"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "System Monitoring",
+ "requirements": ["has-dashboard-named:System Monitoring", "exists-reftarget"],
+ "verify": "on-page:/d/",
+ "content": "Open your System Monitoring dashboard"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='panel-container']:first-of-type",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "tooltip": "Your Targets Up panel shows real-time availability data. The large number indicates how many monitoring targets are healthy. This gives you an instant overview of your infrastructure health.",
+ "content": "Review your availability monitoring panel"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='time-range-picker']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "tooltip": "The time range picker controls what time period your dashboard displays. Try Last 1 hour for recent data, Last 24 hours for daily patterns, or Last 7 days for weekly trend analysis.",
+ "content": "Notice the time range controls"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='refresh-button']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "tooltip": "The refresh button updates your dashboard with the latest data. You can also enable auto-refresh to keep your monitoring views current without manual intervention - perfect for live monitoring scenarios.",
+ "content": "Learn about dashboard refresh options"
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## 🎉 Congratulations!\n\nOutstanding work! You've successfully completed the advanced Grafana monitoring setup guide. You now have:\n\n- ✅ **Comprehensive Interface Knowledge** - You understand Grafana's layout and navigation\n- ✅ **Prometheus Data Source** - Connected and tested for reliable metrics collection\n- ✅ **System Monitoring Dashboard** - Multiple panel types showing different aspects of system health\n- ✅ **Intelligent Alerting** - Proactive monitoring that notifies you of issues\n- ✅ **Advanced Feature Awareness** - Knowledge of Explore, plugins, and additional capabilities\n\n### What You Can Do Next\n\n- **Expand Your Dashboard** - Add more panels for memory, disk, and network monitoring\n- **Configure More Alerts** - Set up alerts for different metrics and thresholds\n- **Explore Data Sources** - Connect Loki for logs, Tempo for traces, or other systems\n- **Team Collaboration** - Share dashboards with your team and set up notification channels\n- **Advanced Queries** - Learn more complex PromQL for sophisticated monitoring\n\n**Next Recommended Guide:** [Loki + Grafana 101](bundled:loki-grafana-101) to add log monitoring to your observability stack."
+ }
+ ]
+}
```
## Key Features Demonstrated
@@ -1312,4 +527,4 @@ This complete guide demonstrates all interactive features and best practices. Us
- **Helpful Guidance**: Hints and comments provide context
- **Flexible Paths**: Alternatives for different user capabilities
-This example demonstrates the full power of the interactive guide system and serves as a comprehensive template for creating high-quality, educational Grafana guides.
\ No newline at end of file
+This example demonstrates the full power of the interactive guide system and serves as a comprehensive template for creating high-quality, educational Grafana guides.
diff --git a/.cursor/complex-selectors-and-hover.mdc b/.cursor/complex-selectors-and-hover.mdc
index f391bace0..2bb9f910b 100644
--- a/.cursor/complex-selectors-and-hover.mdc
+++ b/.cursor/complex-selectors-and-hover.mdc
@@ -15,13 +15,14 @@ The interactive guide system now supports advanced CSS selectors including `:has
Trigger hover states on elements to reveal UI that appears only on hover (e.g., Tailwind `group-hover:` classes, CSS `:hover` states).
### Syntax
-```html
-
- {Description of what to hover}
-
+```json
+{
+ "type": "interactive",
+ "action": "hover",
+ "reftarget": "{CSS_SELECTOR}",
+ "requirements": ["exists-reftarget"],
+ "content": "{Description of what to hover}"
+}
```
### Behavior
@@ -33,51 +34,66 @@ Trigger hover states on elements to reveal UI that appears only on hover (e.g.,
### Common Use Cases
#### Hover-Revealed Action Buttons
-```html
-
-
-
-
- Edit user details
-
+```json
+// Buttons that appear on row hover
+{
+ "type": "multistep",
+ "content": "Edit user details",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "tr[data-row-id='user-123']",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Edit",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
#### Hover-Revealed Menus
-```html
-
-
-
-
- Access preferences from settings menu
-
+```json
+// Dropdown menus on navigation hover
+{
+ "type": "multistep",
+ "content": "Access preferences from settings menu",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "nav[role='navigation'] > div:contains('Settings')",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Preferences",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
#### Service List Hover Actions
-```html
-
-
-
-
- Open checkout service dashboard
-
+```json
+// Application Observability workload list
+{
+ "type": "multistep",
+ "content": "Open checkout service dashboard",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-cy='wb-list-item']:has(p:contains('checkoutservice'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Dashboard",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
### Best Practices for Hover
@@ -95,49 +111,54 @@ Trigger hover states on elements to reveal UI that appears only on hover (e.g.,
Finds elements containing specific text content (jQuery-style selector).
#### Basic Usage
-```html
-
-
- Highlight checkout service
-
-
-
-
- Find error messages
-
-
-
-
- Find running status indicators
-
+```json
+// Find by text content
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div:contains('checkoutservice')",
+ "requirements": ["exists-reftarget"],
+ "content": "Highlight checkout service"
+}
+
+// Case-sensitive matching
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "p:contains('ERROR')",
+ "requirements": ["exists-reftarget"],
+ "content": "Find error messages"
+}
+
+// Partial text matching
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "span:contains('Running')",
+ "requirements": ["exists-reftarget"],
+ "content": "Find running status indicators"
+}
```
#### Combined with Attributes
-```html
-
-
- Find frontend service card
-
-
-
-
- Find production dashboard
-
+```json
+// Most reliable: Attribute + text content
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-cy='service-card']:contains('frontend')",
+ "requirements": ["exists-reftarget"],
+ "content": "Find frontend service card"
+}
+
+// Dashboard list item by title
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='dashboard-link']:contains('Production Metrics')",
+ "requirements": ["exists-reftarget"],
+ "content": "Find production dashboard"
+}
```
### `:has()` Pseudo-Selector
@@ -145,49 +166,54 @@ Finds elements containing specific text content (jQuery-style selector).
Finds elements that contain specific descendant elements.
#### Basic Usage
-```html
-
-
- Highlight service cards with descriptions
-
-
-
-
- Find panels with alert icons
-
-
-
-
- Highlight forms with validation errors
-
+```json
+// Find containers with specific children
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-cy='service-card']:has(p)",
+ "requirements": ["exists-reftarget"],
+ "content": "Highlight service cards with descriptions"
+}
+
+// Find panels with alerts
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='panel']:has(svg[data-icon='alert'])",
+ "requirements": ["exists-reftarget"],
+ "content": "Find panels with alert icons"
+}
+
+// Find forms with errors
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "form:has(span[role='alert'])",
+ "requirements": ["exists-reftarget"],
+ "content": "Highlight forms with validation errors"
+}
```
#### Advanced Targeting
-```html
-
-
- Find deletable rows
-
-
-
-
- Find configurable sections
-
+```json
+// Find rows with specific buttons
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "tr:has(button[data-action='delete'])",
+ "requirements": ["exists-reftarget"],
+ "content": "Find deletable rows"
+}
+
+// Find sections with interactive elements
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section:has(button[data-testid='configure'])",
+ "requirements": ["exists-reftarget"],
+ "content": "Find configurable sections"
+}
```
### Combined Complex Selectors
@@ -195,89 +221,105 @@ Finds elements that contain specific descendant elements.
The most powerful feature: combining `:has()` and `:contains()` for precise targeting.
#### Service/Workload Lists
-```html
-
-
- Highlight checkout service item
-
-
-
-
- Find healthy running services
-
+```json
+// Find specific service by name
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-cy='wb-list-item']:has(p:contains('checkoutservice'))",
+ "requirements": ["exists-reftarget"],
+ "content": "Highlight checkout service item"
+}
+
+// Find service with specific status
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-service]:has(span:contains('Running')):has(span:contains('Healthy'))",
+ "requirements": ["exists-reftarget"],
+ "content": "Find healthy running services"
+}
```
#### Dashboard and Panel Selection
-```html
-
-
- Find production dashboard
-
-
-
-
- Find CPU usage panel
-
+```json
+// Find dashboard by title
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='dashboard-card']:has(h3:contains('Production'))",
+ "requirements": ["exists-reftarget"],
+ "content": "Find production dashboard"
+}
+
+// Find panel by title
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='panel']:has(h2:contains('CPU Usage'))",
+ "requirements": ["exists-reftarget"],
+ "content": "Find CPU usage panel"
+}
```
#### Form Error Handling
-```html
-
-
- Highlight login form with error
-
-
-
-
- Find required field errors
-
+```json
+// Find forms with specific errors
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "form:has(div:contains('Invalid credentials'))",
+ "requirements": ["exists-reftarget"],
+ "content": "Highlight login form with error"
+}
+
+// Find required fields with errors
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-field]:has(span:contains('required'))",
+ "requirements": ["exists-reftarget"],
+ "content": "Find required field errors"
+}
```
#### Hover + Complex Selector Patterns
-```html
-
-
-
-
- View checkout service dashboard
-
-
-
-
-
-
- Star the Kubernetes dashboard
-
+```json
+// Hover over specific service to reveal buttons
+{
+ "type": "multistep",
+ "content": "View checkout service dashboard",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-cy='wb-list-item']:has(p:contains('checkoutservice'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Dashboard",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
+
+// Hover over dashboard card to reveal actions
+{
+ "type": "multistep",
+ "content": "Star the Kubernetes dashboard",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-testid='dashboard-card']:has(h3:contains('Kubernetes'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Star",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
## Browser Compatibility
@@ -301,10 +343,13 @@ The system provides transparent JavaScript fallbacks:
- Logs fallback usage for debugging (in dev mode)
### No Configuration Required
-```html
-
-
+```json
+// Just use complex selectors - system handles compatibility
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div:has(p:contains('text'))"
+}
```
## Performance Optimization
@@ -312,20 +357,20 @@ The system provides transparent JavaScript fallbacks:
### Efficient Selector Strategies
#### Good Selectors (Fast)
-```html
-
+```
+// Specific base with complex refinement
div[data-cy="service-item"]:has(p:contains("checkout"))
div[data-testid="card"]:contains("Production")
section[id="services"]:has(button:contains("Configure"))
```
#### Poor Selectors (Slow)
-```html
-
+```
+// Too generic - searches entire DOM
div:contains("service")
div:has(button)
-
+// Overly complex nesting
div:has(ul:has(li:has(span:contains("text"))))
```
@@ -353,74 +398,96 @@ div:has(ul:has(li:has(span:contains("text"))))
### Application Observability Workload List
-```html
-
-
-
- -
-
-
- Open checkout service dashboard
-
-
-
+```json
+// Navigate to specific service
+{
+ "type": "section",
+ "id": "inspect-checkout-service",
+ "blocks": [
+ {
+ "type": "multistep",
+ "content": "Open checkout service dashboard",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-cy='wb-list-item']:has(p:contains('checkoutservice'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Dashboard",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+ }
+ ]
+}
```
### Kubernetes Workload Management
-```html
-
-
-
-
- View nginx pod logs
-
+```json
+// Interact with specific pod
+{
+ "type": "multistep",
+ "content": "View nginx pod logs",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "tr[data-resource='pod']:has(td:contains('nginx-deployment'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "View logs",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
### Dashboard Management
-```html
-
-
-
-
- Favorite the production metrics dashboard
-
+```json
+// Star specific dashboard
+{
+ "type": "multistep",
+ "content": "Favorite the production metrics dashboard",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-testid='dashboard-card']:has(h3:contains('Production Metrics'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Mark \"Production Metrics\" as favorite",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
### Alert Rules by Name
-```html
-
-
-
-
- Edit the high CPU alert rule
-
+```json
+// Edit specific alert rule
+{
+ "type": "multistep",
+ "content": "Edit the high CPU alert rule",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-testid='alert-rule-row']:has(span:contains('High CPU Alert'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "Edit",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
## Complex Selector Reference
@@ -433,21 +500,21 @@ div:has(ul:has(li:has(span:contains("text"))))
**Partial Match**: Yes
#### Examples
-```html
-
-
+```
+// Service names
+div:contains("checkoutservice")
-
-
+// Status indicators
+span:contains("Running")
-
-
+// Error messages
+p:contains("ERROR")
-
-
+// Dashboard titles
+h2:contains("Production")
-
-
+// Button labels
+button:contains("Configure")
```
### `:has()` Pseudo-Selector
@@ -457,21 +524,21 @@ div:has(ul:has(li:has(span:contains("text"))))
**Nesting**: Supports multiple levels (but limit to 2 for performance)
#### Examples
-```html
-
-
+```
+// Cards with descriptions
+div[data-cy="card"]:has(p)
-
-
+// Services with alerts
+div[data-service]:has(svg[data-icon="alert"])
-
-
+// Panels with queries
+div[data-panel]:has(textarea[data-testid="query-editor"])
-
-
+// Forms with errors
+form:has(span[role="alert"])
-
-
+// Lists with checkboxes
+ul:has(input[type="checkbox"])
```
### Combined Selectors
@@ -480,36 +547,36 @@ div:has(ul:has(li:has(span:contains("text"))))
**Power**: Most precise targeting for dynamic content
#### Examples
-```html
-
-
+```
+// Specific service item
+div[data-cy="wb-list-item"]:has(p:contains("checkoutservice"))
-
-
+// Dashboard with status
+div[data-testid="dashboard-card"]:has(span:contains("Active"))
-
-
+// Alert rule by name
+tr[data-alert-rule]:has(td:contains("High Memory"))
-
-
+// User row by email
+tr[data-user]:has(td:contains("admin@example.com"))
-
-
+// Panel by title
+div[data-panel-id]:has(h2:contains("CPU Usage"))
```
### Nested Complex Selectors
**Use Sparingly**: Performance impact increases with nesting depth
-```html
-
-
+```
+// Good: One level of complexity
+div[data-service]:has(span:contains("Running"))
-
-
+// Acceptable: Two levels of complexity
+div[data-service]:has(div[data-status]:contains("Healthy"))
-
-
+// Avoid: Three+ levels of complexity
+div:has(ul:has(li:has(span:contains("text"))))
```
## AI Generation Guidelines
@@ -568,96 +635,115 @@ Need to target element:
### Service List Interactions
-```html
-
-
-
-
- {{ACTION_DESCRIPTION}}
-
+```json
+// Pattern: Find service, hover to reveal, click action
+{
+ "type": "multistep",
+ "content": "{{ACTION_DESCRIPTION}}",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-cy='wb-list-item']:has(p:contains('{{SERVICE_NAME}}'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "{{ACTION_BUTTON}}",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
### Table Row Actions
-```html
-
-
-
-
- {{ACTION_DESCRIPTION}}
-
+```json
+// Pattern: Find row by content, hover, click action
+{
+ "type": "multistep",
+ "content": "{{ACTION_DESCRIPTION}}",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "tr:has(td:contains('{{ROW_IDENTIFIER}}'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "{{ACTION_BUTTON}}",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
### Card-Based UIs
-```html
-
-
-
-
- {{ACTION_DESCRIPTION}}
-
+```json
+// Pattern: Find card by title, hover, click action
+{
+ "type": "multistep",
+ "content": "{{ACTION_DESCRIPTION}}",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-card]:has(h3:contains('{{CARD_TITLE}}'))",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "{{ACTION_BUTTON}}",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
## Migration Examples
### Before: Limited Targeting
-```html
-
-
- Highlight first service (might not be the right one)
-
+```json
+// Old approach: Less precise
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-cy='wb-list-item']:first-of-type",
+ "content": "Highlight first service (might not be the right one)"
+}
```
### After: Precise Targeting
-```html
-
-
- Highlight checkout service (exact match)
-
-```
-
-### Before: Manual Hover Not Possible
-
-```html
-
-
+```json
+// New approach: Exact targeting
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-cy='wb-list-item']:has(p:contains('checkoutservice'))",
+ "requirements": ["exists-reftarget"],
+ "content": "Highlight checkout service (exact match)"
+}
```
### After: Hover Support
-```html
-
-
-
-
- Edit item
-
+```json
+// New: Full hover interaction support
+{
+ "type": "multistep",
+ "content": "Edit item",
+ "steps": [
+ {
+ "action": "hover",
+ "reftarget": "div[data-cy='item']"
+ },
+ {
+ "action": "button",
+ "reftarget": "Edit"
+ }
+ ]
+}
```
## Troubleshooting
@@ -719,4 +805,4 @@ Need to target element:
- ✅ Include appropriate page requirements
- ❌ Don't assume elements exist without checking
-This enhanced functionality makes interactive guides significantly more powerful and precise, especially for dynamic interfaces like Application Observability, Kubernetes monitoring, and dashboard management.
\ No newline at end of file
+This enhanced functionality makes interactive guides significantly more powerful and precise, especially for dynamic interfaces like Application Observability, Kubernetes monitoring, and dashboard management.
diff --git a/.cursor/edge-cases-and-troubleshooting.mdc b/.cursor/edge-cases-and-troubleshooting.mdc
index c0e7acb60..b7ef0471f 100644
--- a/.cursor/edge-cases-and-troubleshooting.mdc
+++ b/.cursor/edge-cases-and-troubleshooting.mdc
@@ -12,42 +12,46 @@ alwaysApply: true
**Cause**: Interactive action executes before DOM element is rendered
**Solution**: Include appropriate requirements and verification
-```html
-
-
- Save dashboard
-
-
-
-
- Save dashboard
-
+```json
+// Bad: No existence check
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save dashboard",
+ "content": "Save dashboard"
+}
+
+// Good: Includes existence check
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save dashboard",
+ "requirements": ["exists-reftarget", "on-page:/dashboard/edit"],
+ "content": "Save dashboard"
+}
```
#### Problem: Navigation Menu Not Open
**Cause**: Trying to interact with navigation elements when menu is closed
**Solution**: Always include `navmenu-open` requirement for nav interactions
-```html
-
-
- Click Connections
-
-
-
-
- Click Connections
-
+```json
+// Bad: Navigation element without menu requirement
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[href='/connections']",
+ "content": "Click Connections"
+}
+
+// Good: Includes navigation requirement
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[href='/connections']",
+ "requirements": ["navmenu-open", "exists-reftarget"],
+ "content": "Click Connections"
+}
```
### Permission and Access Issues
@@ -56,101 +60,107 @@ alwaysApply: true
**Cause**: Guide requires admin permissions but user doesn't have them
**Solution**: Make admin steps skippable or provide alternative paths
-```html
-
-
- Access plugin management (admin only)
-
-
-
-
-
- You can browse plugins here, but installation requires admin privileges.
- Contact your administrator to request plugin installations.
-
- Browse available plugins (view-only)
-
+```json
+// Option 1: Make skippable
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/admin/plugins",
+ "requirements": ["is-admin"],
+ "skippable": true,
+ "tooltip": "Admin access required - skip if you don't have permissions",
+ "content": "Access plugin management (admin only)"
+}
+
+// Option 2: Provide alternative
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='plugin-catalog']",
+ "requirements": ["has-role:viewer"],
+ "doIt": false,
+ "tooltip": "You can browse plugins here, but installation requires admin privileges. Contact your administrator to request plugin installations.",
+ "content": "Browse available plugins (view-only)"
+}
```
#### Problem: Data Source Dependencies
**Cause**: Guide assumes specific data source exists
**Solution**: Use objectives for auto-completion or include setup sections
-```html
-
-
-
-
-
-
-
- Enter Prometheus query
-
+```json
+// Option 1: Auto-complete if exists
+{
+ "type": "section",
+ "id": "setup-prometheus",
+ "title": "Setup Prometheus",
+ "objectives": ["has-datasource:type:prometheus"],
+ "tooltip": "Skips if Prometheus already configured",
+ "blocks": [
+ // Setup steps only run if Prometheus not configured
+ ]
+}
+
+// Option 2: Check before dependent actions
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "up",
+ "requirements": ["has-datasource:prometheus", "exists-reftarget"],
+ "content": "Enter Prometheus query"
+}
```
### Form Interaction Issues
#### Problem: React Controlled Inputs
**Cause**: React controlled inputs don't update with simple value assignment
-**Solution**: System handles this automatically, but verify with `data-verify`
-
-```html
-
-
- Set dashboard title
-
+**Solution**: System handles this automatically, but verify with `verify`
+
+```json
+// Good: Includes verification
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='dashboard-title']",
+ "targetvalue": "My Dashboard",
+ "requirements": ["exists-reftarget"],
+ "verify": "has-dashboard-named:My Dashboard",
+ "content": "Set dashboard title"
+}
```
#### Problem: ARIA Combobox Complexity
**Cause**: ARIA comboboxes require special tokenization and event handling
**Solution**: Use formfill action - system handles tokenization automatically
-```html
-
-
- Filter logs by job and level
-
+```json
+// Complex query tokenization handled automatically
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[role='combobox'][aria-autocomplete='list']",
+ "targetvalue": "job=\"prometheus\" level=\"error\"",
+ "requirements": ["exists-reftarget", "on-page:/explore"],
+ "content": "Filter logs by job and level"
+}
```
#### Problem: Monaco Editor Special Handling
**Cause**: Monaco editors need special event handling for React integration
**Solution**: System detects Monaco editors automatically
-```html
-
-
- Enter PromQL query
-
+```json
+// Monaco editor automatically detected by CSS classes
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea.inputarea.monaco-mouse-cursor-text",
+ "targetvalue": "rate(http_requests_total[5m])",
+ "requirements": ["exists-reftarget"],
+ "content": "Enter PromQL query"
+}
```
### Navigation and Routing Issues
@@ -159,37 +169,40 @@ alwaysApply: true
**Cause**: Navigation completes but target page content not yet loaded
**Solution**: Use verification to confirm page content is ready
-```html
-
-
- Navigate to create dashboard
-
-
-
-
- Add your first panel
-
+```json
+// Good: Verifies navigation completed
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/dashboard/new",
+ "requirements": ["has-datasources"],
+ "verify": "on-page:/dashboard/new,exists-reftarget",
+ "content": "Navigate to create dashboard"
+}
+
+// Follow-up action waits for page content
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Add visualization",
+ "requirements": ["exists-reftarget", "on-page:/dashboard/new"],
+ "content": "Add your first panel"
+}
```
#### Problem: External URL Handling
**Cause**: External URLs might be blocked by browser security
**Solution**: Use navigate action - system opens in new tab safely
-```html
-
-
- View Grafana documentation
-
+```json
+// External URLs handled automatically
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "https://grafana.com/docs/",
+ "tooltip": "Opens documentation in new tab",
+ "content": "View Grafana documentation"
+}
```
## Troubleshooting Patterns
@@ -197,37 +210,40 @@ alwaysApply: true
### Debugging Failed Requirements
#### Network/API Issues
-```html
-
-
- Test data source connection (skip if network issues)
-
+```json
+// Include fallback for network failures
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Test connection",
+ "requirements": ["exists-reftarget"],
+ "skippable": true,
+ "tooltip": "Skip if network connectivity issues",
+ "content": "Test data source connection (skip if network issues)"
+}
```
#### Plugin Availability Issues
-```html
-
-
- Use custom plugin features
-
-
-
-
- Use standard Grafana dashboards instead
-
+```json
+// Handle missing plugins gracefully
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/a/custom-plugin/",
+ "requirements": ["has-plugin:custom-plugin"],
+ "skippable": true,
+ "tooltip": "Requires custom plugin - skip if not installed",
+ "content": "Use custom plugin features"
+}
+
+// Alternative without plugin
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/dashboards",
+ "tooltip": "Standard dashboards work without additional plugins",
+ "content": "Use standard Grafana dashboards instead"
+}
```
### Selector Reliability Issues
@@ -236,932 +252,54 @@ alwaysApply: true
**Cause**: Grafana UI updates change DOM structure or attributes
**Solution**: Use multiple fallback selectors and stable attributes
-```html
-
-
- Save dashboard
-
-
-
-
- Save dashboard using stable selector
-
+```json
+// Primary selector with fallbacks
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save dashboard",
+ "requirements": ["exists-reftarget"],
+ "content": "Save dashboard"
+}
+
+// If button text changes, use attribute selector
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save-dashboard']",
+ "requirements": ["exists-reftarget"],
+ "content": "Save dashboard using stable selector"
+}
```
#### Problem: Multiple Element Matches
**Cause**: Selector matches multiple elements when only one intended
**Solution**: Use more specific selectors or pseudo-selectors
-```html
-
-
- Edit panel
-
-
-
-
- Edit the first panel
-
-
-
-
- Edit panel 1
-
-```
-
-### Sequential Flow Issues
-
-#### Problem: Steps Out of Order
-**Cause**: User completes steps manually outside guide flow
-**Solution**: Use objectives to handle already-completed states
-
-```html
-
-
- Name your data source
-
-```
-
-#### Problem: Section Dependencies
-**Cause**: User tries to do section 2 before completing section 1
-**Solution**: Use section-completed requirements
-
-```html
-
-
-
-```
-
-### Performance and Scalability Issues
-
-#### Problem: Too Many Requirements Checks
-**Cause**: Complex requirements causing performance issues
-**Solution**: Group related requirements and use caching
-
-```html
-
-
- Create new dashboard
-
-
-
-
- Step 1
-
-
- Step 2 (redundant check)
-
-```
-
-#### Problem: Expensive State Checks
-**Cause**: Requirements that make expensive API calls
-**Solution**: Use objectives for expensive checks that auto-complete
-
-```html
-
-
-
-
-```
-
-## Error Recovery Strategies
-
-### Graceful Degradation Patterns
-
-#### Network Connectivity Issues
-```html
-
-
- Test data source connection
-
-
-
-
-
- If connection testing fails, check your network connectivity
- and firewall settings. You can still configure the data source
- and test the connection later.
-
- Review connection status information
-
-```
-
-#### Missing Feature Fallbacks
-```html
-
-
- Use query library (if available)
-
-
-
-
- Or enter query manually in editor
-
-```
-
-### Error Message Patterns
-
-#### Helpful Error Messages
-```html
-
-
- Create monitoring alert
-
-
-
-
- Manage plugins (admin required)
-
-```
-
-#### Progressive Error Handling
-```html
-
-
-
- Click Connections in navigation
-
-
-
-
-
- If the navigation menu didn't open automatically, click the menu toggle
- button to open it manually.
-
- Manually open navigation menu if needed
-
-```
-
-## Browser and Environment Issues
-
-### Cross-Browser Compatibility
-
-#### Safari-Specific Issues
-```html
-
-
- Save changes
-
-
-
-
- Save using attribute selector
-
-```
-
-#### Mobile and Tablet Considerations
-```html
-
-
- Access mobile navigation menu
-
-```
-
-### Theme and Styling Issues
-
-#### Dark vs Light Theme
-```html
-
-
-
- The theme toggle switches between light and dark modes.
- All interactive guides work in both themes using stable selectors
- that don't depend on theme-specific styling.
-
- Notice the theme toggle option
-
-```
-
-## Version Compatibility Issues
-
-### Grafana Version Differences
-
-#### Version-Specific Features
-```html
-
-
- Use new scenes feature
-
-
-
-
- Create dashboard using standard interface
-
-```
-
-#### API Compatibility
-```html
-
-
- Access query library
-
-```
-
-### Plugin Compatibility
-```html
-
-
- Use plugin features
-
-```
-
-## Complex Workflow Edge Cases
-
-### Multi-Step Failures
-
-#### Problem: Mid-Sequence Failures
-**Cause**: One action in multistep fails, leaving partial state
-**Solution**: Include requirements for each internal action
-
-```html
-
-
-
-
-
- Add visualization, select data source, enter query
-
-```
-
-#### Problem: Section Execution Interruption
-**Cause**: User cancels section execution or browser/tab closes
-**Solution**: System provides resume functionality automatically
-
-```html
-
-
-
-
-```
-
-### State Synchronization Issues
-
-#### Problem: External State Changes
-**Cause**: User makes changes outside guide that affect requirements
-**Solution**: Use live requirement monitoring and reactive checks
-
-```html
-
-
- Edit the panel
-
-```
-
-#### Problem: Concurrent User Actions
-**Cause**: User performs actions while guide is running
-**Solution**: Use section blocking and cancellation
-
-```html
-
-
-
-
-```
-
-## Data Consistency Issues
-
-### Data Source State Issues
-
-#### Problem: Data Source Configuration Drift
-**Cause**: Data source settings change after guide creation
-**Solution**: Use type-based requirements instead of name-based
-
-```html
-
-
- Select my prometheus data source
-
-
-
-
- Select any Prometheus data source
-
-```
-
-#### Problem: Missing Test Data
-**Cause**: Guide assumes specific metrics/logs exist
-**Solution**: Use generic queries that work with minimal data
-
-```html
-
-
- Enter universal monitoring query
-
-
-
-
- Enter application-specific query
-
-```
-
-## Accessibility and Usability Edge Cases
-
-### Screen Reader Compatibility
-```html
-
-
- Save your dashboard
-
-
-
-
- Set dashboard title
-
-```
-
-### Keyboard Navigation
-```html
-
-
- Save dashboard (keyboard accessible)
-
-```
-
-## Testing and Validation Edge Cases
-
-### Automated Testing Considerations
-```html
-
-
- Save dashboard
-
-
-
-
- Save dashboard using test ID
-
-```
-
-### Load Testing Considerations
-```html
-
-
- Load dashboard (may take time)
-
-
-
-
- Save and test (with verification)
-
-```
-
-## Debugging Tools and Techniques
-
-### Browser Console Debugging
-```javascript
-// Check if selector works
-document.querySelector("button[data-testid='save']");
-
-// Test requirement checking
-const testRequirement = async (req) => {
- const checker = await import('./requirements-checker.utils');
- const result = await checker.checkRequirements({
- requirements: req,
- targetAction: 'button',
- refTarget: 'test'
- });
- console.log(result);
-};
-
-// Test specific requirements
-testRequirement('has-datasource:prometheus');
-testRequirement('is-admin');
-
-// Check current user state
-console.log('User:', window.grafanaBootData?.user);
-console.log('Features:', window.grafanaBootData?.settings?.featureToggles);
-```
-
-### Development Mode Features
-```javascript
-// Enable debug logging
-localStorage.setItem('grafana-docs-debug', 'true');
-
-// Check interactive element state
-const manager = window.SequentialRequirementsManager?.getInstance();
-if (manager) {
- manager.logCurrentState();
+```json
+// Bad: Might match multiple panels
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='panel']",
+ "content": "Edit panel"
}
-// Monitor requirement changes
-document.addEventListener('interactive-action-completed', (e) => {
- console.log('Action completed:', e.detail);
-});
-```
-
-### Common Debug Scenarios
-
-#### "Requirements never pass"
-1. Check browser console for error messages
-2. Verify requirement syntax exactly matches reference
-3. Test individual requirements in isolation
-4. Check if required data/state actually exists
-
-#### "Element not found"
-1. Verify selector in browser console
-2. Check if element exists in current page state
-3. Ensure navigation requirements are met
-4. Try alternative selectors
-
-#### "Action doesn't execute"
-1. Check if requirements are met
-2. Verify element is clickable/interactable
-3. Check browser console for JavaScript errors
-4. Test action manually to verify it's possible
-
-#### "Guide gets stuck"
-1. Check for JavaScript errors in console
-2. Verify network connectivity for API-dependent requirements
-3. Clear localStorage to reset section progress
-4. Check if user permissions changed
-
-### Recovery Procedures
-
-#### Reset Guide State
-```javascript
-// Clear all guide progress
-Object.keys(localStorage)
- .filter(key => key.startsWith('docsPlugin:completedSteps:'))
- .forEach(key => localStorage.removeItem(key));
-
-// Reload page to restart
-window.location.reload();
-```
-
-#### Skip Problematic Steps
-```html
-
-
- Perform action (skippable if problems)
-
-```
-
-#### Provide Manual Alternatives
-```html
-
-
-
-
- Use automatic configuration
-
-
-
-
- Or configure manually step-by-step
-
-```# Edge Cases and Troubleshooting for AI
-
-## Common Edge Cases
-
-### DOM Timing Issues
-
-#### Problem: Element Not Found
-**Cause**: Interactive action executes before DOM element is rendered
-**Solution**: Include appropriate requirements and verification
-
-```html
-
-
- Save dashboard
-
-
-
-
- Save dashboard
-
-```
-
-#### Problem: Navigation Menu Not Open
-**Cause**: Trying to interact with navigation elements when menu is closed
-**Solution**: Always include `navmenu-open` requirement for nav interactions
-
-```html
-
-
- Click Connections
-
-
-
-
- Click Connections
-
-```
-
-### Permission and Access Issues
-
-#### Problem: Admin Actions for Non-Admin Users
-**Cause**: Guide requires admin permissions but user doesn't have them
-**Solution**: Make admin steps skippable or provide alternative paths
-
-```html
-
-
- Access plugin management (admin only)
-
-
-
-
-
- You can browse plugins here, but installation requires admin privileges.
- Contact your administrator to request plugin installations.
-
- Browse available plugins (view-only)
-
-```
-
-#### Problem: Data Source Dependencies
-**Cause**: Guide assumes specific data source exists
-**Solution**: Use objectives for auto-completion or include setup sections
-
-```html
-
-
-
-
-
-
-
- Enter Prometheus query
-
-```
-
-### Form Interaction Issues
-
-#### Problem: React Controlled Inputs
-**Cause**: React controlled inputs don't update with simple value assignment
-**Solution**: System handles this automatically, but verify with `data-verify`
-
-```html
-
-
- Set dashboard title
-
-```
-
-#### Problem: ARIA Combobox Complexity
-**Cause**: ARIA comboboxes require special tokenization and event handling
-**Solution**: Use formfill action - system handles tokenization automatically
-
-```html
-
-
- Filter logs by job and level
-
-```
-
-#### Problem: Monaco Editor Special Handling
-**Cause**: Monaco editors need special event handling for React integration
-**Solution**: System detects Monaco editors automatically
-
-```html
-
-
- Enter PromQL query
-
-```
-
-### Navigation and Routing Issues
-
-#### Problem: SPA Navigation Timing
-**Cause**: Navigation completes but target page content not yet loaded
-**Solution**: Use verification to confirm page content is ready
-
-```html
-
-
- Navigate to create dashboard
-
-
-
-
- Add your first panel
-
-```
-
-#### Problem: External URL Handling
-**Cause**: External URLs might be blocked by browser security
-**Solution**: Use navigate action - system opens in new tab safely
-
-```html
-
-
- View Grafana documentation
-
-```
-
-## Troubleshooting Patterns
-
-### Debugging Failed Requirements
-
-#### Network/API Issues
-```html
-
-
- Test data source connection (skip if network issues)
-
-```
-
-#### Plugin Availability Issues
-```html
-
-
- Use custom plugin features
-
-
-
-
- Use standard Grafana dashboards instead
-
-```
-
-### Selector Reliability Issues
-
-#### Problem: Element Selector Changes
-**Cause**: Grafana UI updates change DOM structure or attributes
-**Solution**: Use multiple fallback selectors and stable attributes
-
-```html
-
-
- Save dashboard
-
-
-
-
- Save dashboard using stable selector
-
-```
-
-#### Problem: Multiple Element Matches
-**Cause**: Selector matches multiple elements when only one intended
-**Solution**: Use more specific selectors or pseudo-selectors
+// Good: Targets specific panel
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='panel']:first-of-type",
+ "content": "Edit the first panel"
+}
-```html
-
-
- Edit panel
-
-
-
-
- Edit the first panel
-
-
-
-
- Edit panel 1
-
+// Better: Use unique identifier if available
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-panel-id='panel-1']",
+ "content": "Edit panel 1"
+}
```
### Sequential Flow Issues
@@ -1170,30 +308,34 @@ window.location.reload();
**Cause**: User completes steps manually outside guide flow
**Solution**: Use objectives to handle already-completed states
-```html
-
-
- Name your data source
-
+```json
+// Auto-complete if already done
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='datasource-name']",
+ "targetvalue": "prometheus",
+ "objectives": ["has-datasource:prometheus"],
+ "requirements": ["exists-reftarget"],
+ "content": "Name your data source"
+}
```
#### Problem: Section Dependencies
**Cause**: User tries to do section 2 before completing section 1
**Solution**: Use section-completed requirements
-```html
-
-
-
+```json
+{
+ "type": "section",
+ "id": "section-2",
+ "title": "Section 2",
+ "requirements": ["section-completed:section-1"],
+ "tooltip": "Complete the previous section first",
+ "blocks": [
+ // Section 2 content
+ ]
+}
```
### Performance and Scalability Issues
@@ -1202,44 +344,52 @@ window.location.reload();
**Cause**: Complex requirements causing performance issues
**Solution**: Group related requirements and use caching
-```html
-
-
- Create new dashboard
-
-
-
-
- Step 1
-
-
- Step 2 (redundant check)
-
+```json
+// Good: Grouped related requirements
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Create dashboard",
+ "requirements": ["has-datasources", "has-role:editor", "on-page:/dashboards"],
+ "tooltip": "Groups related checks efficiently",
+ "content": "Create new dashboard"
+}
+
+// Bad: Separate similar checks
+// Step 1
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Create dashboard",
+ "requirements": ["has-datasource:prometheus"],
+ "content": "Step 1"
+}
+// Step 2 (redundant check)
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save dashboard",
+ "requirements": ["has-datasource:prometheus"],
+ "content": "Step 2"
+}
```
#### Problem: Expensive State Checks
**Cause**: Requirements that make expensive API calls
**Solution**: Use objectives for expensive checks that auto-complete
-```html
-
-
-
-
+```json
+// Use objective for expensive dashboard search
+{
+ "type": "section",
+ "id": "create-dashboard",
+ "title": "Create Dashboard",
+ "objectives": ["has-dashboard-named:Monitoring Dashboard"],
+ "tooltip": "Skips creation if dashboard already exists",
+ "blocks": [
+ // Creation steps
+ ]
+}
```
## Error Recovery Strategies
@@ -1247,100 +397,99 @@ window.location.reload();
### Graceful Degradation Patterns
#### Network Connectivity Issues
-```html
-
-
- Test data source connection
-
-
-
-
-
- If connection testing fails, check your network connectivity
- and firewall settings. You can still configure the data source
- and test the connection later.
-
- Review connection status information
-
+```json
+// Primary action with network dependency
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Test connection",
+ "requirements": ["exists-reftarget"],
+ "skippable": true,
+ "tooltip": "Skip if experiencing network connectivity issues",
+ "content": "Test data source connection"
+}
+
+// Offline alternative
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='connection-status']",
+ "doIt": false,
+ "tooltip": "If connection testing fails, check your network connectivity and firewall settings. You can still configure the data source and test the connection later.",
+ "content": "Review connection status information"
+}
```
#### Missing Feature Fallbacks
-```html
-
-
- Use query library (if available)
-
-
-
-
- Or enter query manually in editor
-
+```json
+// Modern feature with fallback
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Use query library",
+ "requirements": ["has-feature:queryLibrary", "exists-reftarget"],
+ "skippable": true,
+ "tooltip": "Query library feature - skip if not available",
+ "content": "Use query library (if available)"
+}
+
+// Traditional approach
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "rate(http_requests_total[5m])",
+ "requirements": ["exists-reftarget"],
+ "content": "Or enter query manually in editor"
+}
```
### Error Message Patterns
#### Helpful Error Messages
-```html
-
-
- Create monitoring alert
-
-
-
-
- Manage plugins (admin required)
-
+```json
+// Clear explanation with context
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Create alert",
+ "requirements": ["has-datasource:prometheus", "has-permission:alerting:write"],
+ "tooltip": "Requires Prometheus data source and alerting permissions to create alert rules",
+ "content": "Create monitoring alert"
+}
+
+// Specific guidance for resolution
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/admin/plugins",
+ "requirements": ["is-admin"],
+ "skippable": true,
+ "tooltip": "Plugin management requires admin role - contact your administrator if you need plugin access",
+ "content": "Manage plugins (admin required)"
+}
```
#### Progressive Error Handling
-```html
-
-
-
- Click Connections in navigation
-
-
-
-
-
- If the navigation menu didn't open automatically, click the menu toggle
- button to open it manually.
-
- Manually open navigation menu if needed
-
+```json
+// Try automatic fix first
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[href='/connections']",
+ "requirements": ["navmenu-open", "exists-reftarget"],
+ "content": "Click Connections in navigation"
+}
+
+// Manual alternative if auto-fix fails
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "#mega-menu-toggle",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "If the navigation menu didn't open automatically, click the menu toggle button to open it manually.",
+ "content": "Manually open navigation menu if needed"
+}
```
## Browser and Environment Issues
@@ -1348,54 +497,54 @@ window.location.reload();
### Cross-Browser Compatibility
#### Safari-Specific Issues
-```html
-
-
- Save changes
-
-
-
-
- Save using attribute selector
-
+```json
+// Safari has different button text handling
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Uses exact text matching for cross-browser compatibility",
+ "content": "Save changes"
+}
+
+// Fallback with selector
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save-button']",
+ "requirements": ["exists-reftarget"],
+ "content": "Save using attribute selector"
+}
```
#### Mobile and Tablet Considerations
-```html
-
-
- Access mobile navigation menu
-
+```json
+// Touch-friendly interactions
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='mobile-menu']",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Mobile navigation might use different menu structure",
+ "content": "Access mobile navigation menu"
+}
```
### Theme and Styling Issues
#### Dark vs Light Theme
-```html
-
-
-
- The theme toggle switches between light and dark modes.
- All interactive guides work in both themes using stable selectors
- that don't depend on theme-specific styling.
-
- Notice the theme toggle option
-
+```json
+// Theme-agnostic selectors
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='theme-toggle']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "tooltip": "The theme toggle switches between light and dark modes. All interactive guides work in both themes using stable selectors that don't depend on theme-specific styling.",
+ "content": "Notice the theme toggle option"
+}
```
## Version Compatibility Issues
@@ -1403,50 +552,54 @@ window.location.reload();
### Grafana Version Differences
#### Version-Specific Features
-```html
-
-
- Use new scenes feature
-
-
-
-
- Create dashboard using standard interface
-
+```json
+// Modern Grafana features
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "New scene",
+ "requirements": ["min-version:9.0.0", "exists-reftarget"],
+ "skippable": true,
+ "tooltip": "Scenes feature requires Grafana 9.0+",
+ "content": "Use new scenes feature"
+}
+
+// Fallback for older versions
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Create dashboard",
+ "requirements": ["exists-reftarget"],
+ "content": "Create dashboard using standard interface"
+}
```
#### API Compatibility
-```html
-
-
- Access query library
-
+```json
+// Check for API availability
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Query library",
+ "requirements": ["has-feature:queryLibrary", "min-version:8.5.0", "exists-reftarget"],
+ "skippable": true,
+ "tooltip": "Query library requires specific Grafana version and feature toggle",
+ "content": "Access query library"
+}
```
### Plugin Compatibility
-```html
-
-
- Use plugin features
-
+```json
+// Plugin version dependencies
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/a/plugin-app/",
+ "requirements": ["has-plugin:plugin-id", "min-version:9.0.0"],
+ "skippable": true,
+ "tooltip": "Plugin requires compatible Grafana version",
+ "content": "Use plugin features"
+}
```
## Complex Workflow Edge Cases
@@ -1457,39 +610,47 @@ window.location.reload();
**Cause**: One action in multistep fails, leaving partial state
**Solution**: Include requirements for each internal action
-```html
-
-
-
-
-
- Add visualization, select data source, enter query
-
+```json
+{
+ "type": "multistep",
+ "requirements": ["on-page:/dashboard/new"],
+ "content": "Add visualization, select data source, enter query",
+ "steps": [
+ {
+ "action": "button",
+ "reftarget": "Add visualization",
+ "requirements": ["exists-reftarget"]
+ },
+ {
+ "action": "button",
+ "reftarget": "prometheus-datasource",
+ "requirements": ["has-datasource:prometheus"]
+ },
+ {
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "up",
+ "requirements": ["exists-reftarget"]
+ }
+ ]
+}
```
#### Problem: Section Execution Interruption
**Cause**: User cancels section execution or browser/tab closes
**Solution**: System provides resume functionality automatically
-```html
-
-
-
-
+```json
+// Section automatically resumes from last completed step
+{
+ "type": "section",
+ "id": "long-workflow",
+ "title": "Long Workflow",
+ "tooltip": "Progress saved automatically - can resume if interrupted",
+ "blocks": [
+ // Steps will resume from where user left off
+ ]
+}
```
### State Synchronization Issues
@@ -1498,30 +659,33 @@ window.location.reload();
**Cause**: User makes changes outside guide that affect requirements
**Solution**: Use live requirement monitoring and reactive checks
-```html
-
-
- Edit the panel
-
+```json
+// Requirements automatically recheck when DOM changes
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Edit panel",
+ "requirements": ["exists-reftarget", "on-page:/dashboard"],
+ "tooltip": "Requirements automatically recheck if user navigates",
+ "content": "Edit the panel"
+}
```
#### Problem: Concurrent User Actions
**Cause**: User performs actions while guide is running
**Solution**: Use section blocking and cancellation
-```html
-
-
-
-
+```json
+// Section blocks other interactions during execution
+{
+ "type": "section",
+ "id": "atomic-workflow",
+ "title": "Atomic Workflow",
+ "tooltip": "Blocks other interactions during execution for consistency",
+ "blocks": [
+ // Steps execute without interference
+ ]
+}
```
## Data Consistency Issues
@@ -1532,127 +696,138 @@ window.location.reload();
**Cause**: Data source settings change after guide creation
**Solution**: Use type-based requirements instead of name-based
-```html
-
-
- Select my prometheus data source
-
-
-
-
- Select any Prometheus data source
-
+```json
+// Bad: Relies on specific name
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "my-prometheus",
+ "requirements": ["has-datasource:my-prometheus"],
+ "content": "Select my prometheus data source"
+}
+
+// Good: Uses type for flexibility
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "prometheus",
+ "requirements": ["has-datasource:type:prometheus"],
+ "tooltip": "Works with any Prometheus data source",
+ "content": "Select any Prometheus data source"
+}
```
#### Problem: Missing Test Data
**Cause**: Guide assumes specific metrics/logs exist
**Solution**: Use generic queries that work with minimal data
-```html
-
-
- Enter universal monitoring query
-
-
-
-
- Enter application-specific query
-
+```json
+// Good: Uses universal Prometheus metric
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "up",
+ "requirements": ["has-datasource:prometheus", "exists-reftarget"],
+ "tooltip": "'up' metric exists on all Prometheus instances",
+ "content": "Enter universal monitoring query"
+}
+
+// Avoid: Specific application metrics
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "my_custom_app_requests_total",
+ "tooltip": "Might not exist in all environments",
+ "content": "Enter application-specific query"
+}
```
## Accessibility and Usability Edge Cases
### Screen Reader Compatibility
-```html
-
-
- Save your dashboard
-
-
-
-
- Set dashboard title
-
+```json
+// Include helpful hints for screen readers
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save']",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Save button - preserves your dashboard configuration",
+ "content": "Save your dashboard"
+}
+
+// Use ARIA attributes in selectors when available
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[aria-label='Dashboard title']",
+ "targetvalue": "My Dashboard",
+ "requirements": ["exists-reftarget"],
+ "content": "Set dashboard title"
+}
```
### Keyboard Navigation
-```html
-
-
- Save dashboard (keyboard accessible)
-
+```json
+// Ensure interactive elements are keyboard accessible
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save'][tabindex='0']",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Accessible via keyboard navigation",
+ "content": "Save dashboard (keyboard accessible)"
+}
```
## Testing and Validation Edge Cases
### Automated Testing Considerations
-```html
-
-
- Save dashboard
-
-
-
-
- Save dashboard using test ID
-
+```json
+// Include test-friendly attributes
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save dashboard",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "Uses button text for reliable automated testing",
+ "content": "Save dashboard"
+}
+
+// Alternative with test ID
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='save-dashboard-btn']",
+ "requirements": ["exists-reftarget"],
+ "content": "Save dashboard using test ID"
+}
```
### Load Testing Considerations
-```html
-
-
- Load dashboard (may take time)
-
-
-
-
- Save and test (with verification)
-
+```json
+// Handle high-latency environments
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Load dashboard",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "May take longer in high-latency environments",
+ "content": "Load dashboard (may take time)"
+}
+
+// Include verification for slow operations
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save & test",
+ "requirements": ["exists-reftarget"],
+ "verify": "has-datasource:prometheus",
+ "tooltip": "Verification confirms operation completed successfully",
+ "content": "Save and test (with verification)"
+}
```
## Debugging Tools and Techniques
@@ -1739,33 +914,43 @@ window.location.reload();
```
#### Skip Problematic Steps
-```html
-
-
- Perform action (skippable if problems)
-
+```json
+// Make problematic steps skippable
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Problematic action",
+ "requirements": ["complex-requirement"],
+ "skippable": true,
+ "tooltip": "Skip if experiencing issues",
+ "content": "Perform action (skippable if problems)"
+}
```
#### Provide Manual Alternatives
-```html
-
-
-
-
- Use automatic configuration
-
-
-
-
- Or configure manually step-by-step
-
-```
\ No newline at end of file
+```json
+// Automated approach
+{
+ "type": "multistep",
+ "skippable": true,
+ "content": "Use automatic configuration",
+ "steps": [
+ {
+ "action": "navigate",
+ "reftarget": "/setup"
+ },
+ {
+ "action": "button",
+ "reftarget": "Auto configure"
+ }
+ ]
+}
+
+// Manual fallback
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/manual-setup",
+ "content": "Or configure manually step-by-step"
+}
+```
diff --git a/.cursor/requirements-quick-reference.mdc b/.cursor/requirements-quick-reference.mdc
index bac6eb679..1b218cbbd 100644
--- a/.cursor/requirements-quick-reference.mdc
+++ b/.cursor/requirements-quick-reference.mdc
@@ -4,10 +4,10 @@ alwaysApply: true
# Requirements and Objectives Quick Reference for AI
## Syntax Rules
-- **Requirements**: `data-requirements="req1,req2,req3"` (ALL must pass)
-- **Objectives**: `data-objectives="obj1,obj2,obj3"` (ALL must pass, auto-completes when met)
+- **Requirements**: `requirements: ["req1", "req2", "req3"]` (ALL must pass)
+- **Objectives**: `objectives: ["obj1", "obj2", "obj3"]` (ALL must pass, auto-completes when met)
- **Priority**: Objectives always win over requirements
-- **Verification**: `data-verify="condition"` (checked after action execution)
+- **Verification**: `verify: "condition"` (checked after action execution)
## Essential Requirements (Use These Frequently)
@@ -35,28 +35,28 @@ alwaysApply: true
## Common Requirement Combinations
### Navigation Actions
-```html
-data-requirements="navmenu-open,exists-reftarget"
+```json
+"requirements": ["navmenu-open", "exists-reftarget"]
```
### Admin Actions
-```html
-data-requirements="is-admin,navmenu-open,exists-reftarget"
+```json
+"requirements": ["is-admin", "navmenu-open", "exists-reftarget"]
```
### Data Source Actions
-```html
-data-requirements="has-datasource:prometheus,on-page:/explore,exists-reftarget"
+```json
+"requirements": ["has-datasource:prometheus", "on-page:/explore", "exists-reftarget"]
```
### Dashboard Actions
-```html
-data-requirements="has-datasources,on-page:/dashboard,exists-reftarget"
+```json
+"requirements": ["has-datasources", "on-page:/dashboard", "exists-reftarget"]
```
### Plugin Actions
-```html
-data-requirements="has-plugin:plugin-id,is-admin,exists-reftarget"
+```json
+"requirements": ["has-plugin:plugin-id", "is-admin", "exists-reftarget"]
```
## Objectives Patterns
@@ -314,77 +314,94 @@ data-objectives="has-dashboard-named:My Dashboard"
```
### Section-Level Auto-Completion
-```html
-
-
-
-
+```json
+// Entire section skipped if objective met
+{
+ "type": "section",
+ "id": "setup-prometheus",
+ "title": "Setup Prometheus",
+ "objectives": ["has-datasource:type:prometheus"],
+ "blocks": [
+ // All child steps marked complete if Prometheus exists
+ ]
+}
```
## AI Generation Templates
### Basic Step Template
-```html
-
-
- {Interactive comment if complex UI element}
- Human-readable step description
-
+```json
+{
+ "type": "interactive",
+ "action": "ACTION_TYPE",
+ "reftarget": "TARGET_REFERENCE",
+ "targetvalue": "VALUE_FOR_FORMFILL",
+ "requirements": ["REQUIREMENTS_LIST"],
+ "objectives": ["OBJECTIVES_LIST"],
+ "verify": "VERIFICATION_CONDITION",
+ "tooltip": "USER_HELPFUL_DESCRIPTION",
+ "skippable": true,
+ "doIt": false,
+ "content": "Human-readable step description"
+}
```
### Section Template
-```html
-
-
- {Section Title}
- {Section description explaining goals}
-
-
- {Child interactive steps}
-
-
+```json
+{
+ "type": "section",
+ "id": "unique-section-id",
+ "title": "Section Title",
+ "requirements": ["SECTION_REQUIREMENTS"],
+ "objectives": ["SECTION_OBJECTIVES"],
+ "tooltip": "SECTION_DESCRIPTION",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Section description explaining goals"
+ },
+ {
+ "type": "interactive",
+ "action": "..."
+ }
+ ]
+}
```
### Multi-step Template
-```html
-
-
- {Internal action spans - not rendered visually}
-
-
-
- {User-visible description of what happens}
-
+```json
+{
+ "type": "multistep",
+ "requirements": ["OVERALL_REQUIREMENTS"],
+ "objectives": ["OVERALL_OBJECTIVES"],
+ "tooltip": "WHAT_THIS_ACCOMPLISHES",
+ "content": "User-visible description of what happens",
+ "steps": [
+ {
+ "action": "TYPE",
+ "reftarget": "TARGET",
+ "requirements": ["REQ"]
+ },
+ {
+ "action": "TYPE",
+ "reftarget": "TARGET",
+ "requirements": ["REQ"]
+ }
+ ]
+}
```
### Interactive Comment Template
-```html
-
- The {UI_ELEMENT_NAME} {purpose/function explanation}.
- {Context about why it's important}. Use it for {technical_features}
- to {user_benefit_or_goal}.
-
+```json
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "SELECTOR",
+ "doIt": false,
+ "requirements": ["exists-reftarget"],
+ "tooltip": "The UI_ELEMENT_NAME purpose/function explanation. Context about why it's important. Use it for technical_features to user_benefit_or_goal.",
+ "content": "Learn about UI_ELEMENT_NAME"
+}
```
## Stable Selector Library
@@ -438,7 +455,7 @@ Prometheus Type: a[href='/connections/datasources/prometheus']
- `on-page:/path` - Shows message about navigating to correct page
### Skippable Requirements
-- Use `data-skippable="true"` when requirements might legitimately fail
+- Use `skippable: true` when requirements might legitimately fail
- Common for admin-only features, plugin-dependent features
- Shows "Skip" button when requirements not met
@@ -449,7 +466,7 @@ Prometheus Type: a[href='/connections/datasources/prometheus']
❌ **Slow**: `.class1 .class2 .class3`, `div > div > button`, `[class*='partial']`
### Requirement Optimization
-- **Group related requirements**: `navmenu-open,exists-reftarget`
+- **Group related requirements**: `navmenu-open`, `exists-reftarget`
- **Use specific requirements**: `has-datasource:prometheus` vs `has-datasources`
- **Cache expensive checks**: Use objectives for expensive state checks
- **Avoid redundant checks**: Don't duplicate requirements across steps
@@ -459,8 +476,8 @@ Prometheus Type: a[href='/connections/datasources/prometheus']
### For Every Interactive Element
- [ ] Includes appropriate requirements for action type
- [ ] Uses stable, testable selectors
-- [ ] Has helpful hint text for users
-- [ ] Includes verification for state-changing actions
+- [ ] Has helpful hint text for users (`tooltip`)
+- [ ] Includes verification for state-changing actions (`verify`)
- [ ] Handles error cases gracefully
### For Sections
@@ -475,4 +492,4 @@ Prometheus Type: a[href='/connections/datasources/prometheus']
- [ ] Multi-steps are truly atomic operations
- [ ] Error messages are specific and actionable
- [ ] Alternative paths provided for different user states
-- [ ] Performance impact is reasonable
\ No newline at end of file
+- [ ] Performance impact is reasonable
diff --git a/.cursor/selector-library.mdc b/.cursor/selector-library.mdc
index c8e2d3084..e73846640 100644
--- a/.cursor/selector-library.mdc
+++ b/.cursor/selector-library.mdc
@@ -31,7 +31,7 @@ alwaysApply: true
## Core Navigation Selectors
### Main Navigation Menu
-```html
+```
Home: a[data-testid='data-testid Nav menu item'][href='/']
Dashboards: a[data-testid='data-testid Nav menu item'][href='/dashboards']
@@ -52,7 +52,7 @@ Explore: a[href='/explore']
```
### Admin Subsections
-```html
+```
Users: a[data-testid='data-testid Nav menu item'][href='/admin/users']
Teams: a[data-testid='data-testid Nav menu item'][href='/admin/teams']
@@ -67,7 +67,7 @@ Plugins: a[href='/admin/plugins']
```
### Alerting Subsections
-```html
+```
Alert Rules: a[data-testid='data-testid Nav menu item'][href='/alerting/list']
Contact Points: a[data-testid='data-testid Nav menu item'][href='/alerting/notifications']
@@ -83,7 +83,7 @@ Contact Points: a[href='/alerting/notifications']
## Dashboard and Panel Selectors
### Dashboard Management
-```html
+```
New Dashboard: button[data-testid='new-dashboard']
Save Dashboard: button[data-testid='save-dashboard']
@@ -103,7 +103,7 @@ Dashboard Settings: "Settings", "Dashboard settings"
```
### Panel Management
-```html
+```
Add Panel: button[data-testid='add-panel']
Add Visualization: button[data-testid='add-visualization']
@@ -122,7 +122,7 @@ Panel Title: input[aria-label*='title'], input[placeholder*='title']
```
### Visualization and Query Editor
-```html
+```
Query Editor: textarea[data-testid='query-editor']
Monaco Editor: textarea.inputarea.monaco-mouse-cursor-text
@@ -150,7 +150,7 @@ Run Query: "Run query", "Refresh", "Execute"
## Data Source Configuration Selectors
### General Data Source Fields
-```html
+```
Data Source Name: input[id='basic-settings-name']
Connection URL: input[id='connection-url']
@@ -180,7 +180,7 @@ Save & Test: "Save & test", "Save and test", "Test connection"
```
### Prometheus Specific
-```html
+```
Prometheus Type: a[href='/connections/datasources/prometheus']
@@ -197,7 +197,7 @@ Query Timeout: "60s"
```
### Loki Specific
-```html
+```
Loki Type: a[href='/connections/datasources/loki']
@@ -213,7 +213,7 @@ Timeout: "60s"
```
### InfluxDB Specific
-```html
+```
InfluxDB Type: a[href='/connections/datasources/influxdb']
@@ -232,7 +232,7 @@ User: "admin"
## Form Element Patterns
### Input Field Types
-```html
+```
Text Input by ID: input[id='{field-id}']
Text Input by TestID: input[data-testid='{field-testid}']
@@ -264,52 +264,57 @@ Color Picker: input[type='color']
```
### Form Interaction Patterns
-```html
-
-
- Set dashboard name
-
-
-
-
- Enable alerting
-
-
-
-
- Set refresh interval
-
-
-
-
- Enter PromQL query
-
-
-
-
- Filter by job label
-
+```json
+// Simple text entry
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='dashboard-name']",
+ "targetvalue": "My Dashboard",
+ "content": "Set dashboard name"
+}
+
+// Checkbox selection
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[type='checkbox'][id='enable-alerts']",
+ "targetvalue": "true",
+ "content": "Enable alerting"
+}
+
+// Dropdown selection
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "select[data-testid='refresh-interval']",
+ "targetvalue": "5s",
+ "content": "Set refresh interval"
+}
+
+// Complex query entry
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea.inputarea",
+ "targetvalue": "rate(http_requests_total[5m])",
+ "content": "Enter PromQL query"
+}
+
+// ARIA combobox (label filters)
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[role='combobox'][aria-autocomplete='list']",
+ "targetvalue": "job=\"prometheus\"",
+ "content": "Filter by job label"
+}
```
## Button Text Library
### Common Button Patterns
-```html
+```
Save: "Save", "Save dashboard", "Save changes"
Create: "Create", "Create dashboard", "Create new"
@@ -344,7 +349,7 @@ Configure: "Configure", "Configuration"
```
### Context-Specific Buttons
-```html
+```
"Add panel" - when on dashboard edit page
"Save dashboard" - when editing dashboard
@@ -371,7 +376,7 @@ Configure: "Configure", "Configuration"
## Specialized Component Selectors
### Time and Date Controls
-```html
+```
Time Range Button: button[data-testid='time-range-picker']
Absolute Time: button[data-testid='absolute-time']
@@ -389,7 +394,7 @@ To Time: input[data-testid='time-to']
```
### Search and Filter Elements
-```html
+```
Global Search: input[data-testid='search-input']
Search Button: button[data-testid='search-button']
@@ -408,7 +413,7 @@ Data Source Filter: select[data-testid='data-source-filter']
```
### Modal and Dialog Selectors
-```html
+```
Modal Dialog: div[role='dialog']
Modal Header: div[data-testid='modal-header']
@@ -428,7 +433,7 @@ Confirm Save: button[data-testid='confirm-save']
## Advanced Selector Patterns
### Pseudo-Selector Usage
-```html
+```
First Panel: div[data-testid='panel-container']:first-of-type
Last Panel: div[data-testid='panel-container']:last-of-type
@@ -447,7 +452,7 @@ Checked Checkbox: input[type='checkbox']:checked
```
### Attribute Combination Patterns
-```html
+```
Active Nav Item: a[data-testid='nav-item'][aria-current='page']
Enabled Button: button[data-testid='action-btn']:not([disabled])
@@ -464,7 +469,7 @@ Delete Button: button[data-testid='delete-btn'][aria-label*='delete']
```
### Hierarchical Selection
-```html
+```
Nav Menu Link: nav[data-testid='navigation'] a[href='/dashboards']
Panel Editor Button: div[data-testid='panel-editor'] button[data-testid='save']
@@ -479,7 +484,7 @@ Alert Form: form[data-testid='alert-form'] input[data-testid='rule-name']
## Query Editor Specific Selectors
### Query Editor Components
-```html
+```
Query Editor: textarea[data-testid='query-editor']
Monaco Query Editor: textarea.inputarea.monaco-mouse-cursor-text
@@ -503,7 +508,7 @@ Relative Time: input[data-testid='relative-time']
```
### Data Source Specific Query Elements
-```html
+```
PromQL Editor: textarea[data-testid='prometheus-query-editor']
Prometheus Metrics Browser: button[data-testid='metrics-browser']
@@ -523,7 +528,7 @@ Field Select: select[data-testid='field-select']
## Plugin and App Selectors
### Plugin Management
-```html
+```
Plugin Catalog: div[data-testid='plugin-catalog']
Plugin Search: input[data-testid='plugin-search']
@@ -544,7 +549,7 @@ Plugin Author: span[data-testid='plugin-author']
```
### Common App Plugin Selectors
-```html
+```
Synthetic Monitoring: a[href='/a/grafana-synthetic-monitoring-app/']
SM Checks: div[data-testid='synthetic-monitoring-checks']
@@ -564,7 +569,7 @@ Create Job: button[data-testid='create-ml-job']
## Alerting System Selectors
### Alert Rule Management
-```html
+```
Alert Rules List: div[data-testid='alert-rules-list']
Alert Rule Row: div[data-testid='alert-rule-row']
@@ -584,7 +589,7 @@ Delete Rule: button[data-testid='delete-alert-rule']
```
### Contact Points and Notifications
-```html
+```
Contact Points List: div[data-testid='contact-points-list']
New Contact Point: button[data-testid='new-contact-point']
@@ -601,7 +606,7 @@ Webhook URL: input[data-testid='webhook-url']
## User and Team Management Selectors
### User Management
-```html
+```
Users List: table[data-testid='users-table']
User Row: tr[data-testid='user-row']
@@ -621,7 +626,7 @@ Reset Password: button[data-testid='reset-password']
```
### Team Management
-```html
+```
Teams List: div[data-testid='teams-list']
Team Card: div[data-testid='team-card']
@@ -641,7 +646,7 @@ Add Member: button[data-testid='add-team-member']
## Performance-Optimized Selectors
### Fast Selectors (Prefer These)
-```html
+```
#unique-element-id
@@ -657,7 +662,7 @@ div[role='dialog']
```
### Moderate Performance Selectors
-```html
+```
input[type='text'][data-testid='field']
button[data-testid='action'][aria-label='Save']
@@ -670,7 +675,7 @@ input[data-testid='field']:nth-of-type(2)
```
### Avoid These (Slow) Selectors
-```html
+```
.container .row .col .panel .header .title
@@ -778,7 +783,7 @@ measureSelector(".complex .nested .selector"); // Avoid if > 5ms
## Core Navigation Selectors
### Main Navigation Menu
-```html
+```
Home: a[data-testid='data-testid Nav menu item'][href='/']
Dashboards: a[data-testid='data-testid Nav menu item'][href='/dashboards']
@@ -799,7 +804,7 @@ Explore: a[href='/explore']
```
### Admin Subsections
-```html
+```
Users: a[data-testid='data-testid Nav menu item'][href='/admin/users']
Teams: a[data-testid='data-testid Nav menu item'][href='/admin/teams']
@@ -814,7 +819,7 @@ Plugins: a[href='/admin/plugins']
```
### Alerting Subsections
-```html
+```
Alert Rules: a[data-testid='data-testid Nav menu item'][href='/alerting/list']
Contact Points: a[data-testid='data-testid Nav menu item'][href='/alerting/notifications']
@@ -830,7 +835,7 @@ Contact Points: a[href='/alerting/notifications']
## Dashboard and Panel Selectors
### Dashboard Management
-```html
+```
New Dashboard: button[data-testid='new-dashboard']
Save Dashboard: button[data-testid='save-dashboard']
@@ -850,7 +855,7 @@ Dashboard Settings: "Settings", "Dashboard settings"
```
### Panel Management
-```html
+```
Add Panel: button[data-testid='add-panel']
Add Visualization: button[data-testid='add-visualization']
@@ -869,7 +874,7 @@ Panel Title: input[aria-label*='title'], input[placeholder*='title']
```
### Visualization and Query Editor
-```html
+```
Query Editor: textarea[data-testid='query-editor']
Monaco Editor: textarea.inputarea.monaco-mouse-cursor-text
@@ -897,7 +902,7 @@ Run Query: "Run query", "Refresh", "Execute"
## Data Source Configuration Selectors
### General Data Source Fields
-```html
+```
Data Source Name: input[id='basic-settings-name']
Connection URL: input[id='connection-url']
@@ -927,7 +932,7 @@ Save & Test: "Save & test", "Save and test", "Test connection"
```
### Prometheus Specific
-```html
+```
Prometheus Type: a[href='/connections/datasources/prometheus']
@@ -944,7 +949,7 @@ Query Timeout: "60s"
```
### Loki Specific
-```html
+```
Loki Type: a[href='/connections/datasources/loki']
@@ -960,7 +965,7 @@ Timeout: "60s"
```
### InfluxDB Specific
-```html
+```
InfluxDB Type: a[href='/connections/datasources/influxdb']
@@ -979,7 +984,7 @@ User: "admin"
## Form Element Patterns
### Input Field Types
-```html
+```
Text Input by ID: input[id='{field-id}']
Text Input by TestID: input[data-testid='{field-testid}']
@@ -1011,52 +1016,57 @@ Color Picker: input[type='color']
```
### Form Interaction Patterns
-```html
-
-
- Set dashboard name
-
-
-
-
- Enable alerting
-
-
-
-
- Set refresh interval
-
-
-
-
- Enter PromQL query
-
-
-
-
- Filter by job label
-
+```json
+// Simple text entry
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='dashboard-name']",
+ "targetvalue": "My Dashboard",
+ "content": "Set dashboard name"
+}
+
+// Checkbox selection
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[type='checkbox'][id='enable-alerts']",
+ "targetvalue": "true",
+ "content": "Enable alerting"
+}
+
+// Dropdown selection
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "select[data-testid='refresh-interval']",
+ "targetvalue": "5s",
+ "content": "Set refresh interval"
+}
+
+// Complex query entry
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea.inputarea",
+ "targetvalue": "rate(http_requests_total[5m])",
+ "content": "Enter PromQL query"
+}
+
+// ARIA combobox (label filters)
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[role='combobox'][aria-autocomplete='list']",
+ "targetvalue": "job=\"prometheus\"",
+ "content": "Filter by job label"
+}
```
## Button Text Library
### Common Button Patterns
-```html
+```
Save: "Save", "Save dashboard", "Save changes"
Create: "Create", "Create dashboard", "Create new"
@@ -1091,7 +1101,7 @@ Configure: "Configure", "Configuration"
```
### Context-Specific Buttons
-```html
+```
"Add panel" - when on dashboard edit page
"Save dashboard" - when editing dashboard
@@ -1118,7 +1128,7 @@ Configure: "Configure", "Configuration"
## Specialized Component Selectors
### Time and Date Controls
-```html
+```
Time Range Button: button[data-testid='time-range-picker']
Absolute Time: button[data-testid='absolute-time']
@@ -1136,7 +1146,7 @@ To Time: input[data-testid='time-to']
```
### Search and Filter Elements
-```html
+```
Global Search: input[data-testid='search-input']
Search Button: button[data-testid='search-button']
@@ -1155,7 +1165,7 @@ Data Source Filter: select[data-testid='data-source-filter']
```
### Modal and Dialog Selectors
-```html
+```
Modal Dialog: div[role='dialog']
Modal Header: div[data-testid='modal-header']
@@ -1175,7 +1185,7 @@ Confirm Save: button[data-testid='confirm-save']
## Advanced Selector Patterns
### Pseudo-Selector Usage
-```html
+```
First Panel: div[data-testid='panel-container']:first-of-type
Last Panel: div[data-testid='panel-container']:last-of-type
@@ -1194,7 +1204,7 @@ Checked Checkbox: input[type='checkbox']:checked
```
### Attribute Combination Patterns
-```html
+```
Active Nav Item: a[data-testid='nav-item'][aria-current='page']
Enabled Button: button[data-testid='action-btn']:not([disabled])
@@ -1211,7 +1221,7 @@ Delete Button: button[data-testid='delete-btn'][aria-label*='delete']
```
### Hierarchical Selection
-```html
+```
Nav Menu Link: nav[data-testid='navigation'] a[href='/dashboards']
Panel Editor Button: div[data-testid='panel-editor'] button[data-testid='save']
@@ -1226,7 +1236,7 @@ Alert Form: form[data-testid='alert-form'] input[data-testid='rule-name']
## Query Editor Specific Selectors
### Query Editor Components
-```html
+```
Query Editor: textarea[data-testid='query-editor']
Monaco Query Editor: textarea.inputarea.monaco-mouse-cursor-text
@@ -1250,7 +1260,7 @@ Relative Time: input[data-testid='relative-time']
```
### Data Source Specific Query Elements
-```html
+```
PromQL Editor: textarea[data-testid='prometheus-query-editor']
Prometheus Metrics Browser: button[data-testid='metrics-browser']
@@ -1270,7 +1280,7 @@ Field Select: select[data-testid='field-select']
## Plugin and App Selectors
### Plugin Management
-```html
+```
Plugin Catalog: div[data-testid='plugin-catalog']
Plugin Search: input[data-testid='plugin-search']
@@ -1291,7 +1301,7 @@ Plugin Author: span[data-testid='plugin-author']
```
### Common App Plugin Selectors
-```html
+```
Synthetic Monitoring: a[href='/a/grafana-synthetic-monitoring-app/']
SM Checks: div[data-testid='synthetic-monitoring-checks']
@@ -1311,7 +1321,7 @@ Create Job: button[data-testid='create-ml-job']
## Alerting System Selectors
### Alert Rule Management
-```html
+```
Alert Rules List: div[data-testid='alert-rules-list']
Alert Rule Row: div[data-testid='alert-rule-row']
@@ -1331,7 +1341,7 @@ Delete Rule: button[data-testid='delete-alert-rule']
```
### Contact Points and Notifications
-```html
+```
Contact Points List: div[data-testid='contact-points-list']
New Contact Point: button[data-testid='new-contact-point']
@@ -1348,7 +1358,7 @@ Webhook URL: input[data-testid='webhook-url']
## User and Team Management Selectors
### User Management
-```html
+```
Users List: table[data-testid='users-table']
User Row: tr[data-testid='user-row']
@@ -1368,7 +1378,7 @@ Reset Password: button[data-testid='reset-password']
```
### Team Management
-```html
+```
Teams List: div[data-testid='teams-list']
Team Card: div[data-testid='team-card']
@@ -1388,7 +1398,7 @@ Add Member: button[data-testid='add-team-member']
## Performance-Optimized Selectors
### Fast Selectors (Prefer These)
-```html
+```
#unique-element-id
@@ -1404,7 +1414,7 @@ div[role='dialog']
```
### Moderate Performance Selectors
-```html
+```
input[type='text'][data-testid='field']
button[data-testid='action'][aria-label='Save']
@@ -1417,7 +1427,7 @@ input[data-testid='field']:nth-of-type(2)
```
### Avoid These (Slow) Selectors
-```html
+```
.container .row .col .panel .header .title
diff --git a/.cursor/system-architecture.mdc b/.cursor/system-architecture.mdc
index 5c19cf046..8db4038e9 100644
--- a/.cursor/system-architecture.mdc
+++ b/.cursor/system-architecture.mdc
@@ -1,13 +1,13 @@
# Interactive Tutorial System Architecture
## Overview
-The interactive tutorial system is a React-based framework for creating guided, executable documentation within Grafana. It transforms static HTML documentation into interactive experiences with real Grafana UI manipulation.
+The interactive tutorial system is a React-based framework for creating guided, executable documentation within Grafana. It transforms structured JSON documentation into interactive experiences with real Grafana UI manipulation.
## Core Components
-### HTML Processing Pipeline
-1. **HTML Input**: Raw HTML with interactive attributes
-2. **HTML Parser** (`html-parser.ts`): Converts HTML to React component data
+### Content Processing Pipeline
+1. **JSON Input**: Structured JSON with interactive properties
+2. **Content Parser**: Converts JSON structure to React component data
3. **Content Renderer** (`content-renderer.tsx`): Renders React components
4. **Interactive Components**: Execute real actions in Grafana UI
@@ -105,7 +105,7 @@ ContentRenderer
### Adding New Action Types
1. Create action handler class implementing standard interface
2. Add action type to `executeInteractiveAction` switch statement
-3. Update HTML parser to recognize new action attributes
+3. Update content parser to recognize new action types
4. Add React component if specialized rendering needed
### Adding New Requirements
@@ -115,7 +115,7 @@ ContentRenderer
4. Test with existing interactive elements
### Adding New UI Features
-1. Extend HTML parser to recognize new attributes
+1. Extend content schema to support new features
2. Add React component props for new features
3. Implement rendering logic in content renderer
4. Add CSS styling in appropriate style files
@@ -140,10 +140,10 @@ ContentRenderer
- **Inline Styles**: Uses CSS custom properties instead of inline styles
- **Script Execution**: No dynamic script execution in tutorial content
- **External Resources**: External URLs opened with security attributes
-- **HTML Sanitization**: Interactive comments support limited, safe HTML subset
+- **Markdown Content**: Uses safe Markdown rendering for text content
### User Safety
- **Action Validation**: All actions validated before execution
- **Permission Checking**: User permissions verified before privileged actions
- **State Isolation**: Tutorial execution doesn't interfere with user work
-- **Graceful Failure**: Failed actions don't leave system in broken state
\ No newline at end of file
+- **Graceful Failure**: Failed actions don't leave system in broken state
diff --git a/.cursor/tutorial-patterns.mdc b/.cursor/tutorial-patterns.mdc
index 23820dea0..e6dea7b2c 100644
--- a/.cursor/tutorial-patterns.mdc
+++ b/.cursor/tutorial-patterns.mdc
@@ -4,60 +4,65 @@ alwaysApply: true
# Interactive Guide Patterns for AI Generation
-The term "guide" is preferred over "guide" throughout this documentation.
+The term "guide" is preferred over "tutorial" throughout this documentation.
## Guide Structure Patterns
### Complete Guide Template
-```html
-
-
-
- {Guide Title}
-
-
- {Guide Title}
-
- {Introduction explaining what user will learn}
-
- - {Learning objective 1}
- - {Learning objective 2}
- - {Learning objective 3}
-
-
- {Section 1}
- {Section 2}
- {Section N}
-
- 🎉 Congratulations!
- {Summary of what was accomplished}
-
- - ✅ {Achievement 1}
- - ✅ {Achievement 2}
- - ✅ {Achievement 3}
-
-
- Next: {Link to next guide or suggested actions}
-
-
+```json
+{
+ "id": "unique-guide-id",
+ "title": "Guide Title",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# Guide Title\n\nIntroduction explaining what user will learn.\n\n- Learning objective 1\n- Learning objective 2\n- Learning objective 3"
+ },
+ {
+ "type": "section",
+ "id": "section-1",
+ "title": "Section 1 Title",
+ "blocks": [
+ // Section 1 steps
+ ]
+ },
+ {
+ "type": "section",
+ "id": "section-2",
+ "title": "Section 2 Title",
+ "blocks": [
+ // Section 2 steps
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## 🎉 Congratulations!\n\nSummary of what was accomplished.\n\n- ✅ Achievement 1\n- ✅ Achievement 2\n- ✅ Achievement 3\n\n**Next:** Link to next guide or suggested actions"
+ }
+ ]
+}
```
### Section Structure Pattern
-```html
-Section {N}: {Section Title}
-{Section description and context}
-
-
-
- {Interactive steps}
-
-
+```json
+{
+ "type": "section",
+ "id": "section-id",
+ "title": "Section Title",
+ "requirements": ["section-requirements"],
+ "objectives": ["section-objectives"],
+ "tooltip": "section-description",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Section description and context"
+ },
+ {
+ "type": "interactive",
+ "action": "...",
+ "content": "Step 1"
+ }
+ ]
+}
```
## Common Guide Types
@@ -67,35 +72,31 @@ The term "guide" is preferred over "guide" throughout this documentation.
**Pattern**: Show-only highlights with rich comments
**Sections**: Navigation, Dashboard basics, Key features
-```html
-
-
- -
-
- The Home page is your Grafana dashboard hub.
- It shows recent dashboards, starred favorites,
- and quick access to common tasks.
-
- Start with the Home page
-
-
- -
-
- Dashboards are collections of panels displaying your data.
- Create
time series, stats, tables
- and more to visualize your monitoring data.
-
- Explore the Dashboards section
-
-
-
+```json
+{
+ "type": "section",
+ "id": "grafana-tour",
+ "title": "Grafana Tour",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='Nav menu item'][href='/']",
+ "requirements": ["navmenu-open"],
+ "doIt": false,
+ "tooltip": "The Home page is your Grafana dashboard hub. It shows recent dashboards, starred favorites, and quick access to common tasks.",
+ "content": "Start with the Home page"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='Nav menu item'][href='/dashboards']",
+ "doIt": false,
+ "tooltip": "Dashboards are collections of panels displaying your data. Create time series, stats, tables and more to visualize your monitoring data.",
+ "content": "Explore the Dashboards section"
+ }
+ ]
+}
```
### 2. Setup/Configuration Guide
@@ -103,72 +104,86 @@ The term "guide" is preferred over "guide" throughout this documentation.
**Pattern**: Sections with verification and objectives
**Sections**: Prerequisites, Configuration, Testing, Usage
-```html
-Section 1: Set Up Data Source
-
-
- -
- Navigate to data sources
-
-
- -
- Add new data source
-
-
- -
- Select Prometheus
-
-
- -
- Name the data source
-
-
- -
- Set server URL
-
-
- -
- Save and test connection
-
-
-
-
-Section 2: Create Dashboard
-
-
-
+```json
+{
+ "id": "setup-guide",
+ "title": "Setup Guide",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "## Section 1: Set Up Data Source"
+ },
+ {
+ "type": "section",
+ "id": "setup-datasource",
+ "title": "Set Up Data Source",
+ "requirements": ["is-admin"],
+ "objectives": ["has-datasource:prometheus"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/connections/datasources",
+ "requirements": ["navmenu-open"],
+ "verify": "on-page:/connections",
+ "content": "Navigate to data sources"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Add new data source",
+ "requirements": ["exists-reftarget"],
+ "content": "Add new data source"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[href='/connections/datasources/prometheus']",
+ "requirements": ["exists-reftarget"],
+ "content": "Select Prometheus"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='basic-settings-name']",
+ "targetvalue": "prometheus-datasource",
+ "requirements": ["exists-reftarget"],
+ "content": "Name the data source"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='connection-url']",
+ "targetvalue": "http://prometheus:9090",
+ "requirements": ["exists-reftarget"],
+ "content": "Set server URL"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save & test",
+ "requirements": ["exists-reftarget"],
+ "verify": "has-datasource:prometheus-datasource",
+ "content": "Save and test connection"
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## Section 2: Create Dashboard"
+ },
+ {
+ "type": "section",
+ "id": "create-dashboard",
+ "title": "Create Dashboard",
+ "requirements": ["section-completed:setup-datasource"],
+ "objectives": ["has-dashboard-named:Monitoring Dashboard"],
+ "blocks": [
+ // Dashboard creation steps
+ ]
+ }
+ ]
+}
```
### 3. Feature Deep-Dive Guide
@@ -176,33 +191,42 @@ The term "guide" is preferred over "guide" throughout this documentation.
**Pattern**: Mix of education (show-only) and practice (regular actions)
**Sections**: Concept intro, Basic usage, Advanced features
-```html
-Understanding Grafana Alerting
-
-
-
-
- -
-
- Alert rules continuously monitor your metrics.
- When conditions like
CPU > 80% are met, they trigger
- notifications to keep your team informed.
-
- Explore the alert rules interface
-
-
-
-
-
-
-
-
+```json
+{
+ "id": "feature-guide",
+ "title": "Understanding Grafana Alerting",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "## Understanding Grafana Alerting"
+ },
+ {
+ "type": "section",
+ "id": "learn-alerting",
+ "title": "Learn Alerting",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='alert-rules-list']",
+ "requirements": ["on-page:/alerting"],
+ "doIt": false,
+ "tooltip": "Alert rules continuously monitor your metrics. When conditions like CPU > 80% are met, they trigger notifications to keep your team informed.",
+ "content": "Explore the alert rules interface"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "create-alert",
+ "title": "Create Alert",
+ "requirements": ["section-completed:learn-alerting", "has-datasource:prometheus"],
+ "blocks": [
+ // Actual alert creation steps
+ ]
+ }
+ ]
+}
```
### 4. Workflow Guide
@@ -210,144 +234,206 @@ The term "guide" is preferred over "guide" throughout this documentation.
**Pattern**: Sequential sections building toward final goal
**Sections**: Setup, Configuration, Implementation, Validation
-```html
-Complete Monitoring Setup
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+```json
+{
+ "id": "workflow-guide",
+ "title": "Complete Monitoring Setup",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# Complete Monitoring Setup"
+ },
+ {
+ "type": "section",
+ "id": "setup-monitoring-data",
+ "title": "Setup Monitoring Data",
+ "objectives": ["has-datasource:type:prometheus"],
+ "blocks": [
+ // Data source setup
+ ]
+ },
+ {
+ "type": "section",
+ "id": "create-monitoring-dashboard",
+ "title": "Create Monitoring Dashboard",
+ "requirements": ["section-completed:setup-monitoring-data"],
+ "objectives": ["has-dashboard-named:System Monitoring"],
+ "blocks": [
+ // Dashboard creation
+ ]
+ },
+ {
+ "type": "section",
+ "id": "setup-monitoring-alerts",
+ "title": "Setup Monitoring Alerts",
+ "requirements": ["section-completed:create-monitoring-dashboard"],
+ "objectives": ["exists-reftarget"], // Check for alert rules
+ "blocks": [
+ // Alert setup
+ ]
+ }
+ ]
+}
```
## Content Writing Patterns
### Step Description Patterns
-```html
-
-
- Save your dashboard changes
-
-
-
-
- Set the Prometheus server URL to connect to your metrics
-
-
-
-
-
- This panel displays your metrics in real-time...
-
- Examine how panels display your monitoring data
-
+```json
+// Action-focused descriptions
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save",
+ "content": "Save your dashboard changes"
+}
+
+// Context-rich descriptions
+{
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[id='url']",
+ "targetvalue": "http://prometheus:9090",
+ "content": "Set the Prometheus server URL to connect to your metrics"
+}
+
+// Educational descriptions
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='panel']",
+ "doIt": false,
+ "tooltip": "This panel displays your metrics in real-time...",
+ "content": "Examine how panels display your monitoring data"
+}
```
### Section Introduction Patterns
-```html
-
-Section 1: Configure Prometheus Data Source
-In this section, we'll connect Grafana to your Prometheus server so you can query and visualize your metrics.
-
-
-Section 2: Create Your First Dashboard
-Now that your data source is configured, let's create a dashboard to display your Prometheus metrics in meaningful visualizations.
-
-
-Section 3: Set Up Alerting
-Dashboards show you what happened, but alerts tell you when something is happening. Let's create alert rules to monitor your system proactively.
+```json
+// Goal-oriented
+{
+ "type": "markdown",
+ "content": "## Section 1: Configure Prometheus Data Source\n\nIn this section, we'll connect Grafana to your Prometheus server so you can query and visualize your metrics."
+}
+
+// Context-setting
+{
+ "type": "markdown",
+ "content": "## Section 2: Create Your First Dashboard\n\nNow that your data source is configured, let's create a dashboard to display your Prometheus metrics in meaningful visualizations."
+}
+
+// Problem-solving
+{
+ "type": "markdown",
+ "content": "## Section 3: Set Up Alerting\n\nDashboards show you what happened, but alerts tell you when something is happening. Let's create alert rules to monitor your system proactively."
+}
```
## Advanced Patterns
### Conditional Workflows
-```html
-
-
-
-
-
-
-
-
+```json
+// Different paths based on user state
+{
+ "type": "section",
+ "id": "admin-setup",
+ "title": "Admin Setup",
+ "requirements": ["is-admin"],
+ "tooltip": "Admin-specific setup process",
+ "blocks": [
+ // Admin workflow
+ ]
+}
+
+{
+ "type": "section",
+ "id": "user-setup",
+ "title": "User Setup",
+ "requirements": ["has-role:viewer"],
+ "tooltip": "Non-admin workflow",
+ "blocks": [
+ // Limited user workflow
+ ]
+}
```
### Progressive Complexity
-```html
-
-
-
- Enter basic "up" query
-
-
-
-
-
-
- Enter rate calculation query
-
-
-
-
-
-
- Enter aggregated rate query
-
-
+```json
+// Basic level
+{
+ "type": "section",
+ "id": "basic-query",
+ "title": "Basic Query",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea",
+ "targetvalue": "up",
+ "content": "Enter basic 'up' query"
+ }
+ ]
+}
+
+// Intermediate level
+{
+ "type": "section",
+ "id": "intermediate-query",
+ "title": "Intermediate Query",
+ "requirements": ["section-completed:basic-query"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea",
+ "targetvalue": "rate(http_requests_total[5m])",
+ "content": "Enter rate calculation query"
+ }
+ ]
+}
+
+// Advanced level
+{
+ "type": "section",
+ "id": "advanced-query",
+ "title": "Advanced Query",
+ "requirements": ["section-completed:intermediate-query", "has-feature:expressions"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea",
+ "targetvalue": "sum(rate(http_requests_total[5m])) by (status)",
+ "content": "Enter aggregated rate query"
+ }
+ ]
+}
```
### Error Recovery Workflows
-```html
-
-
-
-
-
-
-
-
-
+```json
+// Primary workflow
+{
+ "type": "section",
+ "id": "primary-setup",
+ "title": "Primary Setup",
+ "objectives": ["has-datasource:prometheus"],
+ "blocks": [
+ // Normal setup steps
+ ]
+}
+
+// Alternative workflow
+{
+ "type": "section",
+ "id": "alternative-setup",
+ "title": "Alternative Setup",
+ "requirements": ["section-completed:primary-setup"],
+ "skippable": true,
+ "blocks": [
+ // Alternative if primary fails
+ ]
+}
```
## AI Generation Decision Trees
@@ -359,8 +445,8 @@ User request analysis:
"Click [element_description]" → highlight action
"Enter [value]" → formfill action
"Go to [page]" → navigate action
- "Do [multiple things]" → sequence or multistep
- "Show [element]" → highlight with data-doit="false"
+ "Do [multiple things]" → sequence (as section) or multistep
+ "Show [element]" → highlight with doIt: false
```
### Choose Requirements
@@ -380,225 +466,214 @@ Action context analysis:
Content complexity analysis:
Single action → individual step
Related actions → multistep
- Multiple checkpoints → sequence
+ Multiple checkpoints → section
Educational content → show-only with comments
- Complex workflow → sequence with mixed step types
+ Complex workflow → section with mixed step types
```
## Common Guide Scenarios
### Scenario: "Show me how to create a dashboard"
-```html
-
-
- Create Your First Dashboard
-
-
- -
- Navigate to create new dashboard
-
-
- -
- Add your first visualization
-
-
- -
- Select your data source
-
-
- -
- Enter a basic query
-
-
- -
- Set panel title
-
-
- -
- Save the dashboard
-
-
-
+```json
+{
+ "type": "section",
+ "id": "create-dashboard-guide",
+ "title": "Create Your First Dashboard",
+ "requirements": ["has-datasources"],
+ "objectives": ["has-dashboard-named:My First Dashboard"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/dashboard/new",
+ "requirements": ["navmenu-open"],
+ "verify": "on-page:/dashboard/new",
+ "content": "Navigate to create new dashboard"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Add visualization",
+ "requirements": ["exists-reftarget"],
+ "content": "Add your first visualization"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "prometheus-datasource",
+ "requirements": ["has-datasource:prometheus"],
+ "content": "Select your data source"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "textarea[data-testid='query-editor']",
+ "targetvalue": "up",
+ "requirements": ["exists-reftarget"],
+ "content": "Enter a basic query"
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='Panel editor option pane field input Title']",
+ "targetvalue": "System Status",
+ "requirements": ["exists-reftarget"],
+ "content": "Set panel title"
+ },
+ {
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Save dashboard",
+ "requirements": ["exists-reftarget"],
+ "verify": "has-dashboard-named:My First Dashboard",
+ "content": "Save the dashboard"
+ }
+ ]
+}
```
### Scenario: "Set up Prometheus monitoring"
-```html
-Prometheus + Grafana Setup
-
-
-
-
- Configure Prometheus Data Source
-
-
-
-
-
-
- Create Prometheus Dashboard
-
-
-
-
-
-
- Configure Prometheus Alerts
-
-
+```json
+{
+ "id": "prometheus-setup",
+ "title": "Prometheus + Grafana Setup",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# Prometheus + Grafana Setup"
+ },
+ {
+ "type": "section",
+ "id": "setup-prometheus-datasource",
+ "title": "Configure Prometheus Data Source",
+ "requirements": ["is-admin"],
+ "objectives": ["has-datasource:type:prometheus"],
+ "blocks": [
+ // Data source setup steps
+ ]
+ },
+ {
+ "type": "section",
+ "id": "create-prometheus-dashboard",
+ "title": "Create Prometheus Dashboard",
+ "requirements": ["section-completed:setup-prometheus-datasource"],
+ "blocks": [
+ // Dashboard creation steps
+ ]
+ },
+ {
+ "type": "section",
+ "id": "setup-prometheus-alerts",
+ "title": "Configure Prometheus Alerts",
+ "requirements": ["section-completed:create-prometheus-dashboard"],
+ "blocks": [
+ // Alert setup steps
+ ]
+ }
+ ]
+}
```
### Scenario: "Explain this interface element"
-```html
-
-
-
- The query editor is where you write queries in your data source's
- native language. For Prometheus, use PromQL. For Loki, use LogQL.
- The editor provides syntax highlighting and auto-completion to help you write effective queries.
-
-
- Learn about the query editor interface
-
+```json
+{
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='query-editor-container']",
+ "requirements": ["on-page:/explore"],
+ "doIt": false,
+ "tooltip": "The query editor is where you write queries in your data source's native language. For Prometheus, use PromQL. For Loki, use LogQL. The editor provides syntax highlighting and auto-completion to help you write effective queries.",
+ "content": "Learn about the query editor interface"
+}
```
## Interactive Comment Guidelines
### Content Structure Template
-```html
-
- The {UI_ELEMENT_NAME} {what_it_does}.
- {why_its_important_or_context}. {specific_features_or_capabilities}
- {user_benefit_or_outcome}.
-
+```json
+{
+ "tooltip": "The UI_ELEMENT_NAME purpose/function explanation. Context about why it's important. Use it for technical_features to user_benefit_or_outcome."
+}
```
### Applied Examples
#### Feature Explanation
-```html
-
- The visualization picker lets you choose how to display your data.
- Different chart types tell different stories about your metrics.
- Choose time series for trends, stat panels for current values,
- and tables for detailed breakdowns.
-
+```json
+{
+ "tooltip": "The visualization picker lets you choose how to display your data. Different chart types tell different stories about your metrics. Choose time series for trends, stat panels for current values, and tables for detailed breakdowns."
+}
```
#### Process Guidance
-```html
-
- Save & test validates your data source configuration and saves it.
- A green success message confirms everything works correctly,
- while red error messages help you troubleshoot connection issues.
-
+```json
+{
+ "tooltip": "Save & test validates your data source configuration and saves it. A green success message confirms everything works correctly, while red error messages help you troubleshoot connection issues."
+}
```
#### Context Building
-```html
-
- This metrics panel shows your application's performance in real-time.
- The time series chart reveals trends and patterns, helping you
- identify performance bottlenecks and capacity planning needs.
-
+```json
+{
+ "tooltip": "This metrics panel shows your application's performance in real-time. The time series chart reveals trends and patterns, helping you identify performance bottlenecks and capacity planning needs."
+}
```
## Error Handling Patterns
### Graceful Degradation
-```html
-
-
- Use quick setup wizard (skip if not available)
-
-
-
-
- Or set up data source manually
-
+```json
+// Primary action with fallback
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Quick setup",
+ "requirements": ["has-plugin:setup-wizard"],
+ "skippable": true,
+ "tooltip": "Uses setup wizard if available, can skip if not installed",
+ "content": "Use quick setup wizard (skip if not available)"
+}
+
+// Manual fallback
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/connections/datasources/new",
+ "requirements": ["is-admin"],
+ "content": "Or set up data source manually"
+}
```
### Permission-Aware Guides
-```html
-
-
- Install Plugin (Admin)
-
-
-
-
-
- Request Plugin Installation
-
- -
-
- You can browse available plugins here, but installation requires admin privileges.
- Contact your
Grafana administrator to request plugin installations.
-
- Browse available plugins (view-only)
-
-
-
+```json
+// Admin path
+{
+ "type": "section",
+ "id": "admin-plugin-setup",
+ "title": "Install Plugin (Admin)",
+ "requirements": ["is-admin"],
+ "blocks": [
+ // Admin-specific steps
+ ]
+}
+
+// Non-admin alternative
+{
+ "type": "section",
+ "id": "user-plugin-info",
+ "title": "Request Plugin Installation",
+ "requirements": ["has-role:viewer"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='plugin-catalog']",
+ "doIt": false,
+ "tooltip": "You can browse available plugins here, but installation requires admin privileges. Contact your Grafana administrator to request plugin installations.",
+ "content": "Browse available plugins (view-only)"
+ }
+ ]
+}
```
## Quality Guidelines for AI
@@ -615,7 +690,7 @@ Content complexity analysis:
- [ ] All DOM interactions include `exists-reftarget`
- [ ] Navigation interactions include `navmenu-open`
- [ ] Page-specific actions include `on-page:/path`
-- [ ] State-changing actions include `data-verify`
+- [ ] State-changing actions include `verify`
- [ ] Admin actions include appropriate permission requirements
- [ ] Sections have unique, stable IDs
@@ -629,705 +704,46 @@ Content complexity analysis:
## Maintenance Patterns
### Version Compatibility
-```html
-
-
- Use new scenes feature (skip if older version)
-
-
-
-
- Create dashboard using standard interface
-
+```json
+// Version-specific features
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "New scene",
+ "requirements": ["min-version:9.0.0", "exists-reftarget"],
+ "skippable": true,
+ "tooltip": "Scenes feature requires Grafana 9.0+",
+ "content": "Use new scenes feature (skip if older version)"
+}
+
+// Fallback for older versions
+{
+ "type": "interactive",
+ "action": "button",
+ "reftarget": "Create dashboard",
+ "requirements": ["exists-reftarget"],
+ "content": "Create dashboard using standard interface"
+}
```
### Environment Adaptation
-```html
-
-
- Access cloud-specific setup
-
-
-
-
- Configure on-premise settings
-
-```# Interactive Guide Patterns for AI Generation
-
-## Guide Structure Patterns
-
-### Complete Guide Template
-```html
-
-
-
- {Guide Title}
-
-
- {Guide Title}
-
- {Introduction explaining what user will learn}
-
- - {Learning objective 1}
- - {Learning objective 2}
- - {Learning objective 3}
-
-
- {Section 1}
- {Section 2}
- {Section N}
-
- 🎉 Congratulations!
- {Summary of what was accomplished}
-
- - ✅ {Achievement 1}
- - ✅ {Achievement 2}
- - ✅ {Achievement 3}
-
-
- Next: {Link to next guide or suggested actions}
-
-
+```json
+// Cloud-specific
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/a/cloud-setup",
+ "requirements": ["in-environment:cloud"],
+ "skippable": true,
+ "content": "Access cloud-specific setup"
+}
+
+// On-premise alternative
+{
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/admin/settings",
+ "requirements": ["is-admin", "in-environment:production"],
+ "content": "Configure on-premise settings"
+}
```
-
-### Section Structure Pattern
-```html
-Section {N}: {Section Title}
-{Section description and context}
-
-
-
- {Interactive steps}
-
-
-```
-
-## Common Guide Types
-
-### 1. Product Tour / Onboarding
-**Goal**: Familiarize users with Grafana interface
-**Pattern**: Show-only highlights with rich comments
-**Sections**: Navigation, Dashboard basics, Key features
-
-```html
-
-
- -
-
- The Home page is your Grafana dashboard hub.
- It shows recent dashboards, starred favorites,
- and quick access to common tasks.
-
- Start with the Home page
-
-
- -
-
- Dashboards are collections of panels displaying your data.
- Create
time series, stats, tables
- and more to visualize your monitoring data.
-
- Explore the Dashboards section
-
-
-
-```
-
-### 2. Setup/Configuration Guide
-**Goal**: Configure a specific feature or integration
-**Pattern**: Sections with verification and objectives
-**Sections**: Prerequisites, Configuration, Testing, Usage
-
-```html
-Section 1: Set Up Data Source
-
-
- -
- Navigate to data sources
-
-
- -
- Add new data source
-
-
- -
- Select Prometheus
-
-
- -
- Name the data source
-
-
- -
- Set server URL
-
-
- -
- Save and test connection
-
-
-
-
-Section 2: Create Dashboard
-
-
-
-```
-
-### 3. Feature Deep-Dive Guide
-**Goal**: Teach specific Grafana feature in depth
-**Pattern**: Mix of education (show-only) and practice (regular actions)
-**Sections**: Concept intro, Basic usage, Advanced features
-
-```html
-Understanding Grafana Alerting
-
-
-
-
- -
-
- Alert rules continuously monitor your metrics.
- When conditions like
CPU > 80% are met, they trigger
- notifications to keep your team informed.
-
- Explore the alert rules interface
-
-
-
-
-
-
-
-
-```
-
-### 4. Workflow Guide
-**Goal**: Complete a real-world task end-to-end
-**Pattern**: Sequential sections building toward final goal
-**Sections**: Setup, Configuration, Implementation, Validation
-
-```html
-Complete Monitoring Setup
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-```
-
-## Content Writing Patterns
-
-### Step Description Patterns
-```html
-
-
- Save your dashboard changes
-
-
-
-
- Set the Prometheus server URL to connect to your metrics
-
-
-
-
-
- This panel displays your metrics in real-time...
-
- Examine how panels display your monitoring data
-
-```
-
-### Section Introduction Patterns
-```html
-
-Section 1: Configure Prometheus Data Source
-In this section, we'll connect Grafana to your Prometheus server so you can query and visualize your metrics.
-
-
-Section 2: Create Your First Dashboard
-Now that your data source is configured, let's create a dashboard to display your Prometheus metrics in meaningful visualizations.
-
-
-Section 3: Set Up Alerting
-Dashboards show you what happened, but alerts tell you when something is happening. Let's create alert rules to monitor your system proactively.
-```
-
-## Advanced Patterns
-
-### Conditional Workflows
-```html
-
-
-
-
-
-
-
-
-```
-
-### Progressive Complexity
-```html
-
-
-
- Enter basic "up" query
-
-
-
-
-
-
- Enter rate calculation query
-
-
-
-
-
-
- Enter aggregated rate query
-
-
-```
-
-### Error Recovery Workflows
-```html
-
-
-
-
-
-
-
-
-
-```
-
-## AI Generation Decision Trees
-
-### Choose Action Type
-```
-User request analysis:
- "Click [button_text]" → button action
- "Click [element_description]" → highlight action
- "Enter [value]" → formfill action
- "Go to [page]" → navigate action
- "Do [multiple things]" → sequence or multistep
- "Show [element]" → highlight with data-doit="false"
-```
-
-### Choose Requirements
-```
-Action context analysis:
- DOM interaction → add "exists-reftarget"
- Navigation menu → add "navmenu-open"
- Specific page → add "on-page:/path"
- Admin feature → add "is-admin"
- Data source needed → add "has-datasource:type"
- Plugin needed → add "has-plugin:id"
- Previous section → add "section-completed:id"
-```
-
-### Choose Structure
-```
-Content complexity analysis:
- Single action → individual step
- Related actions → multistep
- Multiple checkpoints → sequence
- Educational content → show-only with comments
- Complex workflow → sequence with mixed step types
-```
-
-## Common Guide Scenarios
-
-### Scenario: "Show me how to create a dashboard"
-```html
-
-
- Create Your First Dashboard
-
-
- -
- Navigate to create new dashboard
-
-
- -
- Add your first visualization
-
-
- -
- Select your data source
-
-
- -
- Enter a basic query
-
-
- -
- Set panel title
-
-
- -
- Save the dashboard
-
-
-
-```
-
-### Scenario: "Set up Prometheus monitoring"
-```html
-Prometheus + Grafana Setup
-
-
-
-
- Configure Prometheus Data Source
-
-
-
-
-
-
- Create Prometheus Dashboard
-
-
-
-
-
-
- Configure Prometheus Alerts
-
-
-```
-
-### Scenario: "Explain this interface element"
-```html
-
-
-
- The query editor is where you write queries in your data source's
- native language. For Prometheus, use PromQL. For Loki, use LogQL.
- The editor provides syntax highlighting and auto-completion to help you write effective queries.
-
-
- Learn about the query editor interface
-
-```
-
-## Interactive Comment Guidelines
-
-### Content Structure Template
-```html
-
- The {UI_ELEMENT_NAME} {what_it_does}.
- {why_its_important_or_context}. {specific_features_or_capabilities}
- {user_benefit_or_outcome}.
-
-```
-
-### Applied Examples
-
-#### Feature Explanation
-```html
-
- The visualization picker lets you choose how to display your data.
- Different chart types tell different stories about your metrics.
- Choose time series for trends, stat panels for current values,
- and tables for detailed breakdowns.
-
-```
-
-#### Process Guidance
-```html
-
- Save & test validates your data source configuration and saves it.
- A green success message confirms everything works correctly,
- while red error messages help you troubleshoot connection issues.
-
-```
-
-#### Context Building
-```html
-
- This metrics panel shows your application's performance in real-time.
- The time series chart reveals trends and patterns, helping you
- identify performance bottlenecks and capacity planning needs.
-
-```
-
-## Error Handling Patterns
-
-### Graceful Degradation
-```html
-
-
- Use quick setup wizard (skip if not available)
-
-
-
-
- Or set up data source manually
-
-```
-
-### Permission-Aware Guides
-```html
-
-
- Install Plugin (Admin)
-
-
-
-
-
- Request Plugin Installation
-
- -
-
- You can browse available plugins here, but installation requires admin privileges.
- Contact your
Grafana administrator to request plugin installations.
-
- Browse available plugins (view-only)
-
-
-
-```
-
-## Quality Guidelines for AI
-
-### Content Quality Checklist
-- [ ] Guide has clear learning objectives
-- [ ] Steps progress logically toward goal
-- [ ] Requirements are appropriate for each action
-- [ ] Error cases are handled gracefully
-- [ ] Interactive comments add educational value
-- [ ] Section structure supports resumable progress
-
-### Technical Quality Checklist
-- [ ] All DOM interactions include `exists-reftarget`
-- [ ] Navigation interactions include `navmenu-open`
-- [ ] Page-specific actions include `on-page:/path`
-- [ ] State-changing actions include `data-verify`
-- [ ] Admin actions include appropriate permission requirements
-- [ ] Sections have unique, stable IDs
-
-### User Experience Checklist
-- [ ] Steps can be completed by intended user audience
-- [ ] Error messages are helpful and actionable
-- [ ] Guide works across different Grafana setups
-- [ ] Progress can be resumed after interruption
-- [ ] Alternative paths provided for different user states
-
-## Maintenance Patterns
-
-### Version Compatibility
-```html
-
-
- Use new scenes feature (skip if older version)
-
-
-
-
- Create dashboard using standard interface
-
-```
-
-### Environment Adaptation
-```html
-
-
- Access cloud-specific setup
-
-
-
-
- Configure on-premise settings
-
-```
\ No newline at end of file
diff --git a/.github/workflows/validate-json.yml b/.github/workflows/validate-json.yml
index 0a3384fd4..21a5bf453 100644
--- a/.github/workflows/validate-json.yml
+++ b/.github/workflows/validate-json.yml
@@ -1,4 +1,4 @@
-name: Validate JSON
+name: Validate JSON Files
on:
push:
@@ -6,7 +6,8 @@ on:
workflow_dispatch:
jobs:
- validate-json:
+ validate-recommender-rules:
+ name: Validate Recommender Rules (index.json)
runs-on: ubuntu-latest
permissions:
contents: read
@@ -47,3 +48,76 @@ jobs:
echo "❌ JSON validation failed!"
exit 1
fi
+
+ validate-guides:
+ name: Validate Interactive Guides (content.json)
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+ with:
+ persist-credentials: false
+ submodules: false
+
+ - name: Checkout pathfinder-app CLI
+ uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+ with:
+ repository: grafana/grafana-pathfinder-app
+ ref: main
+ path: pathfinder-app
+ persist-credentials: false
+
+ - name: Setup Node.js
+ uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+ with:
+ node-version: '22'
+ cache: 'npm'
+ cache-dependency-path: pathfinder-app/package-lock.json
+
+ - name: Install dependencies
+ working-directory: pathfinder-app
+ run: npm ci
+
+ - name: Build CLI
+ working-directory: pathfinder-app
+ run: npm run build:cli
+
+ - name: Validate guides
+ run: |
+ echo "🔍 Finding and validating content.json files..."
+ echo ""
+
+ PASSED=0
+ FAILED=0
+
+ # Find and iterate through each content.json file
+ while IFS= read -r file; do
+ if [ -n "$file" ]; then
+ echo "📄 Validating: $file"
+
+ if node pathfinder-app/dist/cli/cli/index.js validate --strict "$file"; then
+ PASSED=$((PASSED + 1))
+ else
+ echo "❌ Validation failed for: $file"
+ echo ""
+ FAILED=$((FAILED + 1))
+ fi
+ fi
+ done < <(find . -name "content.json" -type f -not -path "./pathfinder-app/*")
+
+ echo ""
+ echo "📊 Validation Summary:"
+ echo " ✅ Passed: $PASSED"
+ echo " ❌ Failed: $FAILED"
+
+ if [ $FAILED -gt 0 ]; then
+ echo ""
+ echo "❌ $FAILED guide(s) failed validation!"
+ exit 1
+ else
+ echo ""
+ echo "🎉 All $PASSED guide(s) validated successfully!"
+ fi
diff --git a/AGENTS.md b/AGENTS.md
index 2712b50ff..bb111b400 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -108,47 +108,6 @@ Plugin needed → has-plugin:id
Sequential dependency → section-completed:id
```
-### Common Patterns
-```html
-
-
- Save changes
-
-
-
-
- {steps}
-
-
-
-
- {explanation}
- {description}
-
-
-
-
-
-
- {description}
-
-
-
-
- {description}
-
-```
-
-This documentation provides everything needed to understand and generate high-quality interactive Grafana guides.
# AI Interactive Reference Documentation
This folder contains structured reference documentation specifically designed for AI systems to understand and generate interactive Grafana guides.
@@ -241,45 +200,3 @@ Data source needed → has-datasource:type
Plugin needed → has-plugin:id
Sequential dependency → section-completed:id
```
-
-### Common Patterns
-```html
-
-
- Save changes
-
-
-
-
- {steps}
-
-
-
-
- {explanation}
- {description}
-
-
-
-
-
-
- {description}
-
-
-
-
- {description}
-
-```
-
-This documentation provides everything needed to understand and generate high-quality interactive Grafana guides.
diff --git a/first-dashboard/content.json b/first-dashboard/content.json
index 7c4d04bd4..474070ec0 100644
--- a/first-dashboard/content.json
+++ b/first-dashboard/content.json
@@ -1,10 +1,10 @@
{
"id": "first-dashboard",
- "title": "Make your First Dashboard (JSON)",
+ "title": "Make your first dashboard (JSON)",
"blocks": [
{
"type": "markdown",
- "content": "# Make your First Dashboard\n\nIn this tutorial, we'll make your first dashboard, of Grafana news. To do this, we'll learn the following parts of Grafana in sequence:\n\n- Installing plugins to get access to data (in our case, RSS feeds)\n- Creating data sources, so we have something to visualize\n- Creating a dashboard that uses that datasource\n- Setting up basic Alerting"
+ "content": "# Make your first dashboard\n\nIn this tutorial, we'll make your first dashboard, of Grafana news. To do this, we'll learn the following parts of Grafana in sequence:\n\n- Installing plugins to get access to data (in our case, RSS feeds)\n- Creating data sources, so we have something to visualize\n- Creating a dashboard that uses that data source\n- Setting up basic Alerting"
},
{
"type": "markdown",
@@ -49,18 +49,18 @@
"reftarget": "Install",
"requirements": ["is-admin"],
"hint": "You'll need to be logged in, and an administrator",
- "content": "Click the Install Button"
+ "content": "Click the Install button"
}
]
},
{
"type": "markdown",
- "content": "## Step 2: Create a Datasource\n\nA datasource lets us specify which feed we want to use, so we can query it in a dashboard."
+ "content": "## Step 2: Create a data source\n\nA data source lets us specify which feed we want to use, so we can query it in a dashboard."
},
{
"type": "section",
"id": "create-datasource",
- "title": "Create a Datasource",
+ "title": "Create a data source",
"requirements": ["navmenu-open", "has-plugin:volkovlabs-rss-datasource"],
"objectives": ["has-datasource:volkovlabs-rss-datasource"],
"blocks": [
@@ -113,12 +113,12 @@
},
{
"type": "markdown",
- "content": "## Step 3: Create a Dashboard\n\nIn this section, we'll use the datasource we created to create a visualization."
+ "content": "## Step 3: Create a dashboard\n\nIn this section, we'll use the data source we created to create a visualization."
},
{
"type": "section",
"id": "create-dashboard",
- "title": "Create a Dashboard",
+ "title": "Create a dashboard",
"requirements": ["has-datasource:volkovlabs-rss-datasource"],
"blocks": [
{
diff --git a/index.json b/index.json
index 0e4944c96..ccaeb2a51 100644
--- a/index.json
+++ b/index.json
@@ -1,5 +1,21 @@
{
"rules": [
+ {
+ "title": "Tour of Grafana Visualizations",
+ "url": "https://interactive-learning.grafana.net/guides/tour-of-visualizations",
+ "description": "A quick tour of Grafana's visualization types—when to use each one, with live examples.",
+ "type": "docs-page",
+ "match": {
+ "and": [
+ {
+ "urlPrefix": "/d/ma79mqp/visualization-examples"
+ },
+ {
+ "source": "play.grafana.org"
+ }
+ ]
+ }
+ },
{
"title": "Interactive Guide: Explore Drilldowns 101",
"url": "https://interactive-learning.grafana.net/guides/explore-drilldowns-101",
@@ -134,6 +150,54 @@
}
]
}
+ },
+ {
+ "title": "Interactive Guide: CPU Usage in Kubernetes",
+ "url": "https://interactive-learning.grafana.net/guides/k8s-cpu",
+ "description": "Hands-on guide: Explore CPU usage in Kubernetes Monitoring, from namespaces to containers.",
+ "type": "docs-page",
+ "match": {
+ "and": [
+ {
+ "urlPrefix": "/a/grafana-k8s-app"
+ },
+ {
+ "source": "play.grafana.org"
+ }
+ ]
+ }
+ },
+ {
+ "title": "Interactive Guide: Memory Usage in Kubernetes",
+ "url": "https://interactive-learning.grafana.net/guides/k8s-mem",
+ "description": "Hands-on guide: Explore memory usage in Kubernetes Monitoring, from namespaces to containers.",
+ "type": "docs-page",
+ "match": {
+ "and": [
+ {
+ "urlPrefix": "/a/grafana-k8s-app"
+ },
+ {
+ "source": "play.grafana.org"
+ }
+ ]
+ }
+ },
+ {
+ "title": "Interactive Guide: Network Diagnostics in Kubernetes",
+ "url": "https://interactive-learning.grafana.net/guides/k8s-network",
+ "description": "Hands-on guide: Diagnose network issues in Kubernetes Monitoring using bandwidth and saturation metrics.",
+ "type": "docs-page",
+ "match": {
+ "and": [
+ {
+ "urlPrefix": "/a/grafana-k8s-app"
+ },
+ {
+ "source": "play.grafana.org"
+ }
+ ]
+ }
}
]
}
diff --git a/irm-configuration/content.json b/irm-configuration/content.json
index a4de01f56..c8cd25824 100644
--- a/irm-configuration/content.json
+++ b/irm-configuration/content.json
@@ -12,9 +12,7 @@
},
{
"type": "guided",
- "id": "create-schedule",
"content": "Create a new, empty on-call schedule.",
- "reftarget": "a[data-testid=\"data-testid Nav menu item\"][href=\"/a/grafana-irm-app/schedules\"]",
"requirements": ["navmenu-open", "exists-reftarget"],
"stepTimeout": 45000,
"steps": [
@@ -78,9 +76,7 @@
},
{
"type": "guided",
- "id": "create-escalation-chain",
"content": "Create a new escalation chain.",
- "reftarget": "a[data-testid=\"data-testid Nav menu item\"][href=\"/a/grafana-irm-app/escalations\"]",
"requirements": ["navmenu-open", "exists-reftarget"],
"stepTimeout": 45000,
"steps": [
@@ -158,7 +154,6 @@
{
"type": "guided",
"content": "Create a new Grafana Alerting integration.",
- "reftarget": "a[data-testid=\"data-testid Nav menu item\"][href=\"/a/grafana-irm-app/integrations\"]",
"requirements": ["navmenu-open", "exists-reftarget"],
"stepTimeout": 45000,
"steps": [
diff --git a/k8s-cpu/content.json b/k8s-cpu/content.json
new file mode 100644
index 000000000..427d8a5be
--- /dev/null
+++ b/k8s-cpu/content.json
@@ -0,0 +1,148 @@
+{
+ "id": "k8s-cpu",
+ "title": "CPU usage in Namespaces (JSON)",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# Explore CPU usage in Kubernetes Monitoring\n\n Namespaces often map to teams, projects, environments (dev, staging, prod), or business units. When you Monitor CPU usage by namespace, you learn the usage patterns of each group. Then you can plan for capacity and forecast for scaling the cluster or reallocating resources.\n\n### What you will learn\n\n- Navigate from namespaces through the Kubernetes hierarchy to individual containers.\n- Review key panels to understand CPU usage.\n- Locate panels that show throttling, restarts, and termination trends at the container level."
+ },
+ {
+ "type": "section",
+ "id": "namespace-cpu-detail",
+ "title": "Namespace CPU details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Nav menu item'][href='/a/grafana-k8s-app/navigation/namespace']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click **Namespaces** in the main menu to view the list of namespaces in your environment."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "Select the first namespace in the list to open its detail view."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Tab CPU']",
+ "requirements": ["exists-reftarget"],
+ "content": "This is an overview of the CPU and memory usage in the namespace.\n\nClick the **CPU** tab to view more detail about the CPU usage in the namespace."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='uplot-main-div']:nth-match(6)",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "Notice how many containers in the **Scheduling: Containers with CPU requests set** panel have requests set. Pods without CPU requests are assigned **BestEffort** quality of service, and they are evicted first when nodes reclaim CPU.\n\nReview how requests compare to actual CPU usage for workloads in the namespace. Ideally, each workload should have approximately 60-90% CPU usage."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "workload-cpu-detail",
+ "title": "Workload CPU details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[role='gridcell'][aria-colindex='1'] a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "Open the first workload in the list to see details about the workload."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Alignment: Pod Usage/Requests (%)'] > div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "Review the Alignment graph for Pod CPU usage compared to requests.\n\nDetermine if Pods are running over or too close to their CPU requests."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "pod-cpu-detail",
+ "title": "Pod CPU details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[role='gridcell'][aria-colindex='1'] a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "Select the first Pod in the Pods list."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid*='Alignment: Container Usage/Requests']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "Notice the Alignment: Container Usage/Requests (%) panel, compare actual container CPU usage against the CPU requests.\n\nIf usage exceeds 100%, containers in the Pod are using more CPU than requested. This can cause CPU throttling, leading to performance degradation. Consider increasing the CPU requests in the Pod specification.\n\nIf usage is between 80-100%, containers are using a healthy amount of CPU. If usage is less than 50%, containers are over-provisioned."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "container-cpu-detail",
+ "title": "Container CPU details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[role='row'][aria-rowindex='2'] div[role='gridcell'][aria-colindex='1'] a[data-testid='data-testid Data link']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click the first container in the list to view container details."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "canvas:nth-of-type(2):nth-match(3)",
+ "requirements": ["exists-reftarget"],
+ "content": "At the Container detail page, scroll to the **CPU requests sizing** section.\n\nNotice on either side of the gauge, there are two numbers. The number on the left is the currently set CPU requests. The number on the right is the recommended CPU requests. You can use the recommendation to adjust your CPU requests for this container."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header CPU throttling']",
+ "requirements": ["exists-reftarget"],
+ "content": "Scroll further to view the **CPU throttling** panel.\n\nThis panel shows how much time your container is being artificially slowed down because it's trying to use more CPU than its configured limits allow.\n\nWhy it matters:\n\n- Performance impact: High throttling means your application is running slower than it could, directly affecting user experience.\n- Right-sizing: Helps you identify if CPU limits are too restrictive. You might need to increase them.\n- Cost optimization: If throttling is zero or very low, you might have over-provisioned CPU limits and can reduce costs.\n- Application behavior: Sudden throttling spikes can correlate with slow response times or timeout errors."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Last terminated reason'] > div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "content": "Notice the **Last terminated reason** panel.\n\nThis view tells you exactly why Kubernetes last stopped the container, giving you clues to resolve instability.\n\n- **Root cause:** Last termination reason points to the underlying trigger (OOMKilled, CrashLoopBackOff, and so on).\n- **Resilience:** Helps you fix recurring issues before they cascade into bigger outages.\n- **Alerting:** Use these reasons to fine-tune alerts and spot regressions faster."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Container restart history'] > div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "content": "Review the **Container restart history** panel.\n\nThis timeline shows how often the container has restarted, helping you detect flapping workloads.\n\n- **Stability check:** Frequent restarts indicate crashing code, resource starvation, or readiness issues.\n- **Trend insight:** Recent spikes can pinpoint deployments or config changes that destabilized the service.\n- **Mitigation planning:** Correlate restarts with logs and metrics to prioritize fixes and improve uptime."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Container restarts'] > div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "content": "Examine the **Container restarts** panel for a point-in-time view of restart counts.\n\n- **Health indicator:** High restart counts signal unstable workloads that need investigation.\n- **Operational visibility:** Provides a quick glance at which containers are repeatedly crashing.\n- **Actionable data:** Use the restart tally to correlate with logs and metrics for faster remediation."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "### What you have learned\n\nYou have learned how to:\n\n- Navigate from namespaces to individual containers to look at CPU usage.\n- Interpret container CPU usage, throttling, restart history, and termination reasons.\n- Turn insights and CPU request recommendations into improved resource sizing and workload reliability."
+ }
+ ]
+}
+
diff --git a/k8s-cpu/unstyled.html b/k8s-cpu/unstyled.html
new file mode 100644
index 000000000..1c6e0b136
--- /dev/null
+++ b/k8s-cpu/unstyled.html
@@ -0,0 +1,257 @@
+
+
+
+
+
+ CPU usage in Namespaces
+
+
+ Explore CPU usage in Kubernetes Monitoring
+
+
+ Namespaces often map to teams, projects, environments (dev, staging, prod), or business units.
+ When you Monitor CPU usage by namespace, you learn the usage patterns of each group.
+ Then you can plan for capacity and forecast for scaling the cluster or reallocating resources.
+
+
+ What you will learn
+
+ -
+ Navigate from namespaces through the Kubernetes hierarchy to individual
+ containers within a namespace.
+
+ - Review key panels to understand CPU usage.
+ - Locate panels that show throttling, restarts, and termination trends at the container level.
+
+
+
+ Namespace CPU details
+
+ -
+ Click Namespaces in the main menu to view the list of
+ namespaces in your environment.
+
+
+ -
+ Select the first namespace in the list to open its detail view.
+
+
+ -
+ This is an overview of the CPU and memory usage in the namespace.
+ Click the CPU tab to view more detail about the CPU
+ usage in the namespace.
+
+
+ -
+
Workload CPU details
+
+ -
+ Open the first workload in the list to see details about the workload.
+
+
+ -
+ Review the Alignment graph for Pod CPU usage compared to requests.
+ Determine if Pods are running over or too close to their CPU requests.
+
+
+
+
+
+ Pod CPU details
+
+ -
+ Select the first Pod in the Pods list.
+
+ -
+ Notice the Alignment: Container Usage/Requests (%) panel, compare actual container CPU usage against the CPU requests.
+ If usage exceeds 100%, containers in the Pod are using more CPU than requested. This can cause CPU throttling, leading to performance degradation. Consider increasing the CPU requests in the Pod specification.
+ If usage is between 80-100%, containers are using a healthy amount of CPU.
+ If usage is less than 50%, containers are over-provisioned.
+
+
+
+
+
+ Container CPU details
+
+ -
+ Click the first container in the list to view container details.
+
+
+ -
+ At the Container detail page, scroll to the "CPU requests sizing section.
+ Notice on either side of the gauge, there are two numbers. The number on the left is the currently set CPU requests. The number on the right is the recommended CPU requests. You can use the recommendation to adjust your CPU requests for this container.
+
+
+ -
+ Scroll further to view the CPU throttling panel.
+ This panel shows how much time your container is being artificially slowed down because it's trying to use more CPU than its configured limits allow.
+
+ Why it matters:
+
+
+ - Performance impact: High throttling means your application is running slower than it could, directly affecting user experience.
+ - Right-sizing: Helps you identify if CPU limits are too restrictive. You might need to increase them.
+ - Cost optimization: If throttling is zero or very low, you might have over-provisioned CPU limits and can reduce costs.
+ - Application behavior: Sudden throttling spikes can correlate with slow response times or timeout errors.
+
+
+
+ -
+ Notice the Last terminated reason panel.
+ This view tells you exactly why Kubernetes last stopped the container, giving you clues to resolve instability.
+
+ - Root cause: Last termination reason points to the underlying trigger (OOMKilled, CrashLoopBackOff, and so on).
+ - Resilience: Helps you fix recurring issues before they cascade into bigger outages.
+ - Alerting: Use these reasons to fine-tune alerts and spot regressions faster.
+
+
+
+ -
+ Review the Container restart history panel.
+ This timeline shows how often the container has restarted, helping you detect flapping workloads.
+
+ - Stability check: Frequent restarts indicate crashing code, resource starvation, or readiness issues.
+ - Trend insight: Recent spikes can pinpoint deployments or config changes that destabilized the service.
+ - Mitigation planning: Correlate restarts with logs and metrics to prioritize fixes and improve uptime.
+
+
+
+ -
+ Examine the Container restarts panel for a point-in-time view of restart counts.
+
+ - Health indicator: High restart counts signal unstable workloads that need investigation.
+ - Operational visibility: Provides a quick glance at which containers are repeatedly crashing.
+ - Actionable data: Use the restart tally to correlate with logs and metrics for faster remediation.
+
+
+
+
+
+ What you have learned
+ You have learned how to:
+
+ -
+ Navigate from namespaces to individual containers to look at CPU usage.
+
+ -
+ Interpret container CPU usage, throttling, restart history, and termination reasons.
+
+ -
+ Turn insights and CPU request recommendations into improved resource sizing and workload reliability.
+
+
+
+
diff --git a/k8s-mem/content.json b/k8s-mem/content.json
new file mode 100644
index 000000000..566f2c2fd
--- /dev/null
+++ b/k8s-mem/content.json
@@ -0,0 +1,149 @@
+{
+ "id": "k8s-mem",
+ "title": "Memory usage in Kubernetes namespaces (JSON)",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# Memory usage in Kubernetes namespaces\n\nTravel through Kubernetes Monitoring to explore memory usage and any associated issues within a namespace, starting at the namespace level.\n\n### What you will learn\n\n- Navigate from namespaces through the Kubernetes hierarchy to individual containers within a namespace.\n- Review key panels to understand memory usage.\n- The importance of setting memory requests and limits."
+ },
+ {
+ "type": "section",
+ "id": "namespace-detail",
+ "title": "Namespace memory details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Nav menu item'][href='/a/grafana-k8s-app/navigation/namespace']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click **Namespaces** in the main menu to view the list of namespaces in your environment."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "Select the first namespace in the list to open its detail view."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Tab Memory']",
+ "requirements": ["exists-reftarget"],
+ "content": "This is the namespace detail page showing an overview of the CPU and memory usage in the namespace.\n\nClick the **Memory** tab to view more detail about memory usage in the namespace."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Scheduling: Containers with Memory requests set (p95)'] > div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "Notice the panel titled **Scheduling: Containers with Memory requests set**. If all memory requests are set for all containers in this namespace, then the percentage would be 100%.\n\nWhen memory requests are not set, this creates a significant operational risk that affects scheduling efficiency, pod stability, cluster capacity planning, and cost optimization. Always set requests based on observed usage patterns."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Alignment: usage/requests (p95)'] > div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "Notice the **Alignment: usage/requests** panel.\n\nIf all memory requests are set for all containers in this namespace, total memory usage should fall between the 60-90% range of requests."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='uplot-main-div']:nth-match(5)",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "The **Distribution: Workload usage** panel helps visualise which workloads are contributing the most to the overall namespace memory usage."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[data-testid='uplot-main-div']:nth-match(6)",
+ "requirements": ["exists-reftarget"],
+ "content": "Focus on the **Alignment: usage/requests** panel.\n\nEach workload should see approximately 60-90% memory usage. Workloads that fall outside of this range could be considered as incorrectly sized, or they have containers with memory requests and limits that are not well configured."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "workload-detail",
+ "title": "Workload memory details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[role='gridcell'][aria-colindex='1'] a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "Scroll down the list of workloads in this namespace. Click the first workload in the list to see details about the workload."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Alignment: Pod Usage/Requests (%)'] > div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "This is the workload detail page.\n\nReview the Alignment graph for Pod memory usage compared to requests.\n\nThe target range should be around 60-80% utilization of requests to provide headroom for bursts while avoiding waste."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "pod-detail",
+ "title": "Pod memory details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[role='gridcell'][aria-colindex='1'] a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "Select the first Pod in the Pods list."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid*='Alignment: Container Usage/Requests']",
+ "requirements": ["exists-reftarget"],
+ "content": "Notice the Alignment: usage/requests panel.\n\nIdeally, each container should have around 60-90% memory usage. Containers that fall outside of this range could have memory that is incorrectly configured."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "container-detail",
+ "title": "Container memory details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[role='row'][aria-rowindex='2'] div[role='gridcell'][aria-colindex='1'] a[data-testid='data-testid Data link']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click the first container in the list of containers in this Pod to view container details."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "canvas:nth-of-type(2):nth-match(2)",
+ "requirements": ["exists-reftarget"],
+ "content": "At the Container detail page, scroll to the **Memory sizing limits** section.\n\nThe number on the left side of the gauge is the currently set memory sizing limits. The number on the right is the recommended memory sizing limits. You can use the recommendation to adjust your memory limits for this container.\n\nWithout memory limits, a container can consume all available memory on the node, potentially causing:\n\n- Node-wide OOM events, which can kill other workloads or system components.\n- Pod eviction when the node runs low on memory.\n- Resource starvation for other pods on the node, degrading cluster performance."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "canvas:nth-of-type(2):nth-match(4)",
+ "requirements": ["exists-reftarget"],
+ "content": "Next, focus on the **Memory requests sizing** panel.\n\nThe number on the left side of the gauge is the currently set memory requests. The number on the right is the recommended setting for memory requests. You can use the recommendation to adjust your memory requests for this container.\n\nWhen requests are too high, it can cause:\n\n- Wasted capacity: Kubernetes reserves more memory than actually needed, leaving nodes artificially \"full\" even when memory sits unused.\n- Scheduling failures: Pods can't be scheduled even when nodes have available memory, because the scheduler sees insufficient requestable capacity.\n- Higher costs: You need more nodes to run the same workload due to over-reservation.\n\nWhen requests are too low, it can cause:\n\n- Pod evictions: Under memory pressure, Kubernetes evicts pods exceeding their requests first—your pod becomes a target even when running normally.\n- Unpredictable performance: The kubelet may throttle or kill processes on memory-pressured nodes, causing instability.\n- Wrong QoS class: Without appropriate limits, pods drop into BestEffort (first to be evicted) instead of Burstable or Guaranteed."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "### What you have learned\n\nYou have learned how to:\n\n- Navigate from namespaces to individual containers to look at memory usage, requests, and limits.\n- Review container memory usage, limits, requests, and recommendations.\n- Turn insights and memory request recommendations into improved resource sizing and reliability."
+ }
+ ]
+}
+
diff --git a/k8s-mem/unstyled.html b/k8s-mem/unstyled.html
new file mode 100644
index 000000000..703990baf
--- /dev/null
+++ b/k8s-mem/unstyled.html
@@ -0,0 +1,251 @@
+
+
+
+
+
+ Memory usage
+
+
+ Memory usage in Kubernetes namespaces
+
+
+ Travel through Kubernetes Monitoring to explore memory usage and any associated issues within a namespace,
+ starting at the namespace level.
+
+
+ What you will learn
+
+ -
+ Navigate from namespaces through the Kubernetes hierarchy to individual
+ containers within a namespace.
+
+ - Review key panels to understand memory usage.
+ - The importance of setting memory requests and limits.
+
+
+
+ Namespace memory details
+
+ -
+ Click Namespaces in the main menu to view the list of
+ namespaces in your environment.
+
+
+ -
+ Select the first namespace in the list to open its detail view.
+
+
+ -
+ This is the namespace detail page showing an overview of the CPU and memory usage in the namespace.
+ Click the Memory tab to view more detail about
+ memory usage in the namespace.
+
+
+ -
+ Notice the panel titled Scheduling: Containers with Memory requests set .
+ If all memory requests are set for all containers in this namespace, then the percentage would be 100%.
+ When memory requests are not set, this creates a significant operational risk that affects scheduling efficiency, pod stability, cluster capacity planning, and cost optimization. Always set requests based on observed usage patterns.
+
+
+ -
+ Notice the Alignment: usage/requests panel.
+ If all memory requests are set for all containers in this namespace, total memory usage should fall between the 60-90% range of requests.
+
+
+ -
+ The Distribution: Workload usage panel helps visualise which workloads are contributing the most to the overall namespace memory usage.
+
+ -
+ Focus on the Alignment: usage/requests panel.
+ Each workload should see approximately 60-90% memory usage.
+ Workloads that fall outside of this range could be considered as incorrectly sized, or they have containers with memory requests and limits that are not well configured.
+
+
+
+
+
+ Workload memory details
+
+ -
+ Scroll down the list of workloads in this namespace.
+ Click the first workload in the list to see details about the workload.
+
+
+ -
+ This is the workload detail page.
+ Review the Alignment graph for Pod memory usage compared to requests.
+ The target range should be around 60-80% utilization of requests to provide headroom for bursts while avoiding waste.
+
+
+
+
+
+ Pod memory details
+
+ -
+ Select the first Pod in the Pods list.
+
+ -
+ Notice the Alignment: usage/requests panel.
+ Ideally, each container should have around 60-90% memory usage.
+ Containers that fall outside of this range could be have memory that is incorrectly configured.
+
+
+
+
+ Container memory details
+
+ -
+ Click the first container in the list of containers in this Pod to view container details.
+
+
+ -
+ At the Container detail page, scroll to the "Memory sizing limits section.
+ The number on the left side of the guage is the currently set memory sizing limits.
+ The number on the right is the recommended memory sizing limits.
+ You can use the recommendation to adjust your memory limits for this container.
+
+ Without memory limits, a container can consume all available memory on the node, potentially causing:
+
+ - Node-wide OOM events, which can kill other workloads or system components.
+ - Pod eviction when the node runs low on memory.
+ - Resource starvation for other pods on the node, degrading cluster performance.
+
+
+ -
+ Next, focus on the "Memory requests sizing panel.
+ The number on the left side of the guage is the currently set memory requests.
+ The number on the right is the recommended setting for memory requests.
+ You can use the recommendation to adjust your memory requests for this container.
+ When requests are too high, it can cause:
+
+ - Wasted capacity: Kubernetes reserves more memory than actually needed, leaving nodes artificially "full" even when memory sits unused.
+ - Scheduling failures: Pods can't be scheduled even when nodes have available memory, because the scheduler sees insufficient requestable capacity.
+ - Higher costs: You need more nodes to run the same workload due to over-reservation.
+
+
+ When requests are too low, it can cause:
+
+ - Pod evictions: Under memory pressure, Kubernetes evicts pods exceeding their requests first—your pod becomes a target even when running normally.
+ - Unpredictable performance: The kubelet may throttle or kill processes on memory-pressured nodes, causing instability.
+ - Wrong QoS class: Without appropriate limits, pods drop into BestEffort (first to be evicted) instead of Burstable or Guaranteed.
+
+
+
+
+
+ What you have learned
+ You have learned how to:
+
+ -
+ Navigate from namespaces to individual containers to look at memory usage, requests, and limits.
+
+ -
+ Review container memory usage, limits, requests, and recommendations.
+
+ -
+ Turn insights and memory request recommendations into improved resource sizing and reliability.
+
+
+
+
\ No newline at end of file
diff --git a/k8s-network/content.json b/k8s-network/content.json
new file mode 100644
index 000000000..a1ed31592
--- /dev/null
+++ b/k8s-network/content.json
@@ -0,0 +1,198 @@
+{
+ "id": "k8s-network",
+ "title": "Network diagnostics in Kubernetes Monitoring",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# Diagnose network issues in Kubernetes Monitoring\n\nNetwork performance directly impacts application responsiveness, reliability, and user experience. When applications are slow or experience connectivity issues, network metrics can help you determine whether the network is the bottleneck or if issues lie elsewhere.\n\n### What you will learn\n\n- Navigate to the Network tab and understand network bandwidth and saturation metrics.\n- Identify network performance issues like high traffic, packet loss, and saturation.\n- Use the pod and interface breakdown views to pinpoint which workloads are consuming bandwidth or experiencing problems.\n- Apply diagnostic workflows to troubleshoot common network scenarios."
+ },
+ {
+ "type": "section",
+ "id": "namespace-network-overview",
+ "title": "Namespace network overview",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Nav menu item'][href='/a/grafana-k8s-app/navigation/namespace']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click **Namespaces** in the main menu to view the list of namespaces in your environment."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "Select the first namespace in the list to open its detail view."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Tab Network']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click the **Network** tab to view network performance metrics for this namespace.\n\nThe Network tab provides visibility into network bandwidth usage and saturation (packet loss) across your namespace."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "network-bandwidth-panel",
+ "title": "Understanding Network Bandwidth",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Bandwidth']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "The **Network Bandwidth** panel shows how much data is flowing in and out of your namespace over time.\n\n- **Rx (white/gray line)**: Receiving traffic - data coming into the namespace\n- **Tx (blue line)**: Transmitting traffic - data going out of the namespace\n\nThe table below the graph shows Min, 90th percentile, and Max values to help you understand traffic patterns."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Bandwidth'] div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "**How to interpret the patterns:**\n\n- **Steady traffic**: Indicates consistent workload behavior\n- **Regular spikes**: Often normal. Spikes could be scheduled jobs, health checks, or metrics collection\n- **Sudden sustained increase**: May indicate new load, deployments (image pulls), or potential issues\n- **Unexpected drops**: Could signal pod crashes, network partitions, or configuration problems\n- **Asymmetric Rx/Tx**: Large differences are normal for certain workloads like log shipping or data ingestion"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "network-saturation-panel",
+ "title": "Understanding Network Saturation",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Saturation']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "The **Network Saturation** panel shows whether your network is being overwhelmed by displaying dropped packets.\n\n- **Rx dropped packets**: Incoming packets that couldn't be processed\n- **Tx dropped packets**: Outgoing packets that couldn't be sent\n\nMeasured in packets per second (p/s)."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Saturation'] div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "**Why this matters:**\n\n- **Zero is ideal**: No dropped packets means the network has sufficient capacity\n- **Non-zero values**: Indicate network saturation - the network cannot handle current traffic volume\n- **User impact**: Dropped packets cause application timeouts, retries, slow performance, and failed requests\n- **Root cause indicator**: Helps determine if network capacity is the bottleneck\n\n**Action**: If you see dropped packets, consider increasing network limits, optimizing traffic patterns, or implementing network QoS policies."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "network-by-pod",
+ "title": "Network Bandwidth by pod",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Bandwidth by pod']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "The **Network Bandwidth by pod** panel breaks down network traffic by individual pods.\n\nThis stacked visualization shows:\n- Which pods are consuming the most bandwidth\n- How each pod contributes to total namespace traffic\n- Traffic patterns for specific workloads over time"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Bandwidth by pod'] div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "**Use this panel to:**\n\n- **Identify noisy neighbors**: Find which pods consume excessive bandwidth\n- **Troubleshoot performance**: Correlate high traffic pods with application slowness\n- **Capacity planning**: Understand which services need network resources\n- **Detect anomalies**: Spot pods with unusual traffic patterns\n- **Resource allocation**: Determine if specific pods need network limits or QoS\n\nClick on pod names in the legend to view individual pod traffic or review the table below for Min/90th percentile/Max statistics per pod."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "saturation-by-pod",
+ "title": "Network Saturation by pod",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Saturation by pod']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "The **Network Saturation by pod** panel shows packet loss for each individual pod.\n\nThis helps you pinpoint exactly which pod is experiencing network congestion rather than just knowing the namespace has issues."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Saturation by pod'] div[data-testid='data-testid panel content']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "**Diagnostic workflow:**\n\n1. If you see dropped packets in the namespace-level saturation panel, check this panel to identify which specific pod is affected\n2. Compare dropped packets against bandwidth - high bandwidth + dropped packets = capacity issue\n3. Zero dropped packets across all pods = healthy network configuration\n\n**Common scenarios:**\n- **One pod dropping packets**: That pod's network limits may be too restrictive\n- **Multiple pods dropping packets**: Namespace or node-level network saturation\n- **Intermittent drops**: May indicate temporary bursts exceeding capacity"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "pod-network-detail",
+ "title": "Pod-level network details",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "div[role='gridcell'][aria-colindex='1'] a[data-testid='data-testid Data link']:nth-match(1)",
+ "requirements": ["exists-reftarget"],
+ "content": "To investigate a specific pod's network performance, select the first pod in the list.\n\nThis drills down to pod-level details where you can see network metrics for individual containers and interfaces."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Tab Network']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click the **Network** tab to view the pod's network performance.\n\nAt the pod level, you'll see the same four panels but specific to this pod:\n- Network Bandwidth (pod level)\n- Network Saturation (pod level)\n- Network Bandwidth by interface (eth0, etc.)\n- Network Saturation by interface"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Bandwidth']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "Review the pod's **Network Bandwidth** to understand its traffic patterns.\n\n**Traffic scale matters:**\n- Traffic in **KiB/s** or **B/s**: Low-bandwidth workload (monitoring agents, sidecars)\n- Traffic in **MiB/s**: Moderate workload (typical application traffic)\n- Traffic in **GiB/s**: High-bandwidth workload (data processing, large file transfers)\n\n**Pattern recognition:**\n- **Minimal baseline with periodic spikes**: Often metrics reporting, log shipping, or health checks\n- **Sustained high traffic**: Data-intensive operations\n- **Regular spike pattern**: Scheduled operations or batch jobs"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "network-by-interface",
+ "title": "Network by interface",
+ "requirements": ["navmenu-open", "on-page:/a/grafana-k8s-app"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Bandwidth by interface']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "The **Network Bandwidth by interface** panel shows traffic broken down by network interface (typically eth0).\n\n**When this is useful:**\n- Pods with multiple network interfaces (service mesh, CNI plugins)\n- Identifying if a specific interface has issues\n- Troubleshooting network plugin or CNI problems\n- Understanding traffic routing through different interfaces"
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "section[data-testid='data-testid Panel header Network Saturation by interface']",
+ "requirements": ["exists-reftarget"],
+ "doIt": false,
+ "content": "The **Network Saturation by interface** panel shows dropped packets per network interface.\n\n**Diagnostic value:**\n- Identifies if packet loss is interface-specific\n- Helps isolate hardware or driver issues\n- Useful for troubleshooting CNI plugin configuration\n- Can reveal if one interface is overloaded while others are healthy"
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## Common diagnostic scenarios\n\n### Scenario 1: Application is slow\n\n**Workflow:**\n1. Check namespace Network Bandwidth - is traffic unusually high?\n2. Check Network Saturation - are packets being dropped?\n3. Review Network Bandwidth by pod - is one pod consuming excessive bandwidth?\n4. If saturation is high, increase network limits or optimize data transfer\n5. If saturation is zero, the issue is likely application-level, not network\n\n### Scenario 2: Intermittent connectivity issues\n\n**Workflow:**\n1. Look for periodic drops in bandwidth (indicates flapping)\n2. Check for saturation spikes (temporary overload)\n3. Review by interface view - is a specific interface failing?\n4. Investigate pod restarts, network policy changes, or infrastructure issues\n\n### Scenario 3: High network costs\n\n**Workflow:**\n1. Check total bandwidth over time to identify trends\n2. Use by pod breakdown to find data-intensive services\n3. Compare Rx vs Tx - are you sending/receiving more than expected?\n4. Optimize data transfers, implement caching, or review service mesh overhead\n\n### Scenario 4: New deployment causing issues\n\n**Workflow:**\n1. Check for bandwidth spike during deployment (image pulls, init containers)\n2. Compare traffic before/after deployment\n3. Check if saturation occurred (did deployment cause network stress?)\n4. Consider staggering deployments, pre-pulling images, or increasing capacity"
+ },
+ {
+ "type": "markdown",
+ "content": "### What you have learned\n\nYou have learned how to:\n\n- Navigate to network metrics at the namespace and pod level.\n- Interpret Network Bandwidth panels to understand traffic patterns and identify anomalies.\n- Use Network Saturation panels to detect packet loss and network capacity issues.\n- Drill down from namespace to pod to interface to isolate network problems.\n- Apply diagnostic workflows to troubleshoot common network performance scenarios.\n- Distinguish between network-level issues and application-level problems.\n\n**Next steps:**\n- Establish baseline patterns for your namespaces and pods\n- Set up alerts for non-zero dropped packets\n- Correlate network metrics with CPU, memory, and application metrics\n- Document normal traffic patterns for capacity planning"
+ }
+ ]
+}
+
diff --git a/k8s-network/ntwkpanels.png b/k8s-network/ntwkpanels.png
new file mode 100644
index 000000000..7a1208c58
Binary files /dev/null and b/k8s-network/ntwkpanels.png differ
diff --git a/k8s-network/unstyled.html b/k8s-network/unstyled.html
new file mode 100644
index 000000000..1a9276b14
--- /dev/null
+++ b/k8s-network/unstyled.html
@@ -0,0 +1,151 @@
+
+
+
+
+
+ Network usage trends in Kubernetes
+
+
+ Recognizing network performance trends
+
+
+ Network performance directly impacts application responsiveness, reliability, and user experience.
+ When applications are slow or experience connectivity issues, network metrics can help you determine
+ whether the network is the bottleneck or if the issues caused by something else.
+ Another statement goes here about planning for capacity and forecasting for scaling the cluster or reallocating resources.
+
+
+ What you will learn
+
+ - Navigate to the Network tab and understand network bandwidth and saturation metrics.
+ - Identify network performance issues like high traffic, packet loss, and saturation.
+ - Use the pod and interface breakdown views to pinpoint which workloads are consuming bandwidth or experiencing problems.
+ - Apply diagnostic workflows to troubleshoot common network scenarios.
+
+
+
+ Cluster network details
+
+
+ -
+ data-targetaction="highlight"
+ data-requirements="exists-reftarget"
+ >
+ Click Clusters in the main menu to view the list of
+ Clusters in your environment.
+
+
+ -
+ data-targetaction="highlight"
+ data-requirements="exists-reftarget"
+ >
+ Select the first Cluster in the list to open its detail view.
+
+
+
+ -
+ Navigate to the Network tab for more detail on bandwidth and saturation.
+
+
+
+
+ -
+
+ Notice **Network Bandwidth** shows how much data is flowing in and out of your workloads:
+
+
+ - Rx (Receive): Incoming traffic, which is data coming into the namespace/pod
+ - Tx (Transmit): Outgoing traffic, which is data going out of the namespace/pod
+
+
+
+
+Network details
+
+ Network Bandwidth
+
+ Network bandwidth shows how much data is flowing in and out of your workloads:
+
+
+ Network Bandwidth
+
+ Network bandwidth shows how much data is flowing in and out of your workloads:
+
+
+ - Rx (Receive): Incoming traffic - data coming into the namespace/pod
+ - Tx (Transmit): Outgoing traffic - data going out of the namespace/pod
+
+
+ Network Saturation
+
+ Network saturation indicates whether your network is overwhelmed by showing dropped packets.
+ Zero dropped packets is ideal - any non-zero value indicates network stress that can cause
+ application timeouts, retries, and performance degradation.
+
+
+ Diagnostic scenarios
+
+ Scenario 1: Application is slow
+
+ - Check namespace Network Bandwidth - is traffic unusually high?
+ - Check Network Saturation - are packets being dropped?
+ - Review Network Bandwidth by pod - is one pod consuming excessive bandwidth?
+ - If saturation is high, increase network limits or optimize data transfer
+ - If saturation is zero, the issue is likely application-level, not network
+
+
+ Scenario 2: Intermittent connectivity issues
+
+ - Look for periodic drops in bandwidth (indicates flapping)
+ - Check for saturation spikes (temporary overload)
+ - Review by interface view - is a specific interface failing?
+ - Investigate pod restarts, network policy changes, or infrastructure issues
+
+
+ Scenario 3: High network costs
+
+ - Check total bandwidth over time to identify trends
+ - Use by pod breakdown to find data-intensive services
+ - Compare Rx vs Tx - are you sending/receiving more than expected?
+ - Optimize data transfers, implement caching, or review service mesh overhead
+
+
+ Scenario 4: New deployment causing issues
+
+ - Check for bandwidth spike during deployment (image pulls, init containers)
+ - Compare traffic before/after deployment
+ - Check if saturation occurred (did deployment cause network stress?)
+ - Consider staggering deployments, pre-pulling images, or increasing capacity
+
+
+ What you have learned
+ By the end of this guide, you will be able to:
+
+ - Navigate to network metrics at the namespace and pod level
+ - Interpret Network Bandwidth panels to understand traffic patterns and identify anomalies
+ - Use Network Saturation panels to detect packet loss and network capacity issues
+ - Drill down from namespace to pod to interface to isolate network problems
+ - Apply diagnostic workflows to troubleshoot common network performance scenarios
+ - Distinguish between network-level issues and application-level problems
+
+
+
+
diff --git a/logql-101/content.json b/logql-101/content.json
index 4c10c6306..55af4bfc3 100644
--- a/logql-101/content.json
+++ b/logql-101/content.json
@@ -26,7 +26,6 @@
{
"type": "multistep",
"requirements": ["exists-reftarget"],
- "tooltip": "The **data source picker** allows you to select which Loki data source to query. In Grafana, you can have multiple Loki instances configured (e.g., production logs, development logs, different regions). The **Loki Demo Kit (loki_nginx)** data source contains sample logs that we'll use for this tutorial. Selecting this data source will connect you to the specific Loki instance where you can explore and query logs.",
"content": "Click on the **data source picker**, then select the **Loki Demo Kit (loki_nginx)** data source.",
"steps": [
{
@@ -50,7 +49,6 @@
"id": "first-query",
"title": "Write Your First LogQL Query",
"requirements": ["section-completed:select-datasource"],
- "hint": "Learn to write basic LogQL queries using label selectors",
"blocks": [
{
"type": "interactive",
@@ -71,7 +69,7 @@
},
{
"type": "interactive",
- "action": "click",
+ "action": "highlight",
"reftarget": "button[aria-label=\"Run query\"]",
"requirements": ["exists-reftarget"],
"tooltip": "The **Run query** button executes your LogQL query and displays the results. This is how you see the actual log data that matches your query criteria.",
@@ -101,7 +99,7 @@
},
{
"type": "interactive",
- "action": "click",
+ "action": "highlight",
"reftarget": "button[data-testid=\"data-testid RefreshPicker run button\"]",
"requirements": ["exists-reftarget"],
"tooltip": "Now let's execute this refined query to see the filtered results.",
@@ -122,7 +120,7 @@
},
{
"type": "interactive",
- "action": "click",
+ "action": "highlight",
"reftarget": "button[data-testid=\"data-testid RefreshPicker run button\"]",
"requirements": ["exists-reftarget"],
"tooltip": "Now let's execute this combined query to see the filtered results that contain \"500\" but not \"200\".",
@@ -139,7 +137,6 @@
"id": "json-query",
"title": "Use JSON parsing for precise filtering",
"requirements": ["section-completed:first-query"],
- "hint": "Learn to use JSON parsing for more precise log filtering",
"blocks": [
{
"type": "interactive",
@@ -152,7 +149,7 @@
},
{
"type": "interactive",
- "action": "click",
+ "action": "highlight",
"reftarget": "button[data-testid=\"data-testid RefreshPicker run button\"]",
"requirements": ["exists-reftarget"],
"tooltip": "Now let's execute this JSON-based query to see the precise HTTP 500 error logs.",
diff --git a/sm-setting-up-your-first-check/content.json b/sm-setting-up-your-first-check/content.json
new file mode 100644
index 000000000..f691fabb0
--- /dev/null
+++ b/sm-setting-up-your-first-check/content.json
@@ -0,0 +1,197 @@
+{
+ "id": "sm-setting-up-your-first-check",
+ "title": "How to set up your first Synthetic Monitoring check",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "# How to set up your first Synthetic Monitoring check\n\nIn this interactive guide you'll learn how to set up and run an HTTP check in Grafana Cloud Synthetic Monitoring. You will:\n\n- Know how to create and configure HTTP checks\n- Understand how Synthetic Monitoring helps you track uptime and performance\n- Learn how to set up alerts to stay informed about your service status"
+ },
+ {
+ "type": "markdown",
+ "content": "## Section 1: Navigate to adding a new HTTP check\n\nLet's start by navigating to the Testing & Synthetics section. This is where you'll create and manage your synthetic checks."
+ },
+ {
+ "type": "section",
+ "id": "navigate-synthetics",
+ "title": "Navigate to adding a new HTTP check",
+ "objectives": ["on-page:/a/grafana-synthetic-monitoring-app/checks/new/api-endpoint"],
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='data-testid Nav menu item'][href='/testing-and-synthetics']",
+ "requirements": ["navmenu-open"],
+ "content": "In the main menu, navigate to **Testing & synthetics**."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "[id='pageContent'] a[href='/a/grafana-synthetic-monitoring-app/home']",
+ "requirements": ["exists-reftarget"],
+ "objectives": ["on-page:/a/grafana-synthetic-monitoring-app/home"],
+ "content": "Next, click **Synthetics**."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[data-testid='action create check']",
+ "requirements": ["exists-reftarget"],
+ "content": "Click **Create new check**."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "a[href='/a/grafana-synthetic-monitoring-app/checks/new/api-endpoint']",
+ "requirements": ["exists-reftarget"],
+ "content": "Choose **API Endpoint** as the check type."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## Section 2: Configure the target of the Synthetic Monitoring check\n\nIn this section you will configure the Synthetic Monitoring check's parameters."
+ },
+ {
+ "type": "section",
+ "id": "create-check",
+ "title": "Configure the target",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='checkEditor form job']",
+ "targetvalue": "Grafana: HTTP Check",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "All your logs and metrics generated by this check will contain a **job** label with this value.",
+ "content": "Enter **Grafana: HTTP Check** in the Job Name field."
+ },
+ {
+ "type": "interactive",
+ "action": "formfill",
+ "reftarget": "input[data-testid='checkEditor form instance']",
+ "targetvalue": "https://grafana.com",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "They will also contain an **instance** label with this value.",
+ "content": "Set **URL: https://grafana.com**."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## Section 3: Review Optional Parameters for the check\n\nIn this section you can define uptime parameters for the check."
+ },
+ {
+ "type": "section",
+ "id": "configure-check-uptime",
+ "title": "Review Optional Parameters",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='checkEditor navigation uptime']",
+ "requirements": ["exists-reftarget"],
+ "tooltip": "This is the form stepper for configuring your check. You can freely move between sections whenever you want.",
+ "content": "Click **Uptime** to move to the next section of the check configuration."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "input[data-testid='checkEditor form validStatusCodes']",
+ "doIt": false,
+ "skippable": true,
+ "tooltip": "Status codes in the 2xx range are the default, so we can skip this step.",
+ "content": "Set **Valid status codes** if required."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='checkEditor navigation labels']",
+ "content": "Move to the **Labels** section."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "[data-testid='checkEditor genericLabelContent']",
+ "skippable": true,
+ "doIt": false,
+ "tooltip": "This is optional; but if you have many checks, this can help you organize them and route your alerts to the right team. Common labels include 'environment', 'service', and 'team' but you are free to use any label you want.",
+ "content": "Set label names and values if required."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## Section 4: Execution\n\nSetup probe location and frequency for the check."
+ },
+ {
+ "type": "section",
+ "id": "configure-execution",
+ "title": "Configure Execution",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='checkEditor navigation execution']",
+ "content": "Move to the **Execution** section."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "label[data-testid='checkEditor form probeLabel']:first-of-type",
+ "tooltip": "There are multiple probe locations to choose from. It is good practice to run checks from multiple locations to ensure the check is reliable.",
+ "content": "Select a **probe location** to run the check from."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "input[id^='option-60000-radiogroup-']",
+ "skippable": true,
+ "doIt": false,
+ "tooltip": "The default probe frequency is 1 minute which is suitable for most checks. Less frequent means fewer executions, but longer lag times before an alert notifying you of an issue.",
+ "content": "Set the desired probe frequency."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## Section 5: Configure Alerting\n\nConfigure alerting for the check.\n\nFinally, you'll configure alerting for the check."
+ },
+ {
+ "type": "section",
+ "id": "configure-alerting",
+ "title": "Configure Alerting",
+ "blocks": [
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='checkEditor navigation alerting']",
+ "content": "Move to the **Alerting** section."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "input[data-testid='checkEditor alerts ProbeFailedExecutionsTooHigh selectedCheckbox']",
+ "tooltip": "The failed check alert will be triggered if the check fails more than the configured number of times.",
+ "content": "Click the checkbox to enable the failed check alert."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='checkEditor feat-adhoc-check testButton']",
+ "skippable": true,
+ "content": "You can click **Test** to see if the check is working as expected."
+ },
+ {
+ "type": "interactive",
+ "action": "highlight",
+ "reftarget": "button[data-testid='checkEditor form submit']",
+ "content": "Click **Save** to create the check."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "## 🎉 Congratulations!\n\nYou have completed the HTTP check tutorial in Grafana Cloud Synthetic Monitoring. You have successfully:\n\n- Created and configured an HTTP check to monitor uptime and performance\n- Added a probe location and frequency to the check\n- Set up an alert to stay informed about service issues"
+ }
+ ]
+}
diff --git a/tour-of-visualizations/content.json b/tour-of-visualizations/content.json
new file mode 100644
index 000000000..432b1653b
--- /dev/null
+++ b/tour-of-visualizations/content.json
@@ -0,0 +1,209 @@
+{
+ "id": "tour-of-visualizations",
+ "title": "Tour of Grafana Visualizations",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "**What you will learn:** Which panel type to pick for your data.\n\nEach stop links to a live example on Grafana Play—click through and explore!"
+ },
+ {
+ "type": "section",
+ "id": "time-based-visualizations",
+ "title": "Time-Based Visualizations",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "The bread and butter of monitoring—showing how things change over time."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/000000016/time-series-graphs",
+ "content": "**Time Series** — The workhorse. Use this when you want to see metrics over time—CPU usage, request rates, temperatures, you name it."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/qD-rVv6Mz/state-timeline-and-status-history",
+ "content": "**State Timeline & Status History** — When you care about *what state* something was in, not just numbers. Perfect for tracking service status, deployments, or on/off states."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "single-value-displays",
+ "title": "Single Value Displays",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Sometimes you just need one big number that tells you what's happening *right now*."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/Zb3f4veGk/stats",
+ "content": "**Stats** — Big numbers with optional sparklines. Use these when a single value tells the whole story: total users, current latency, error count."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/KIhkVD6Gk/gauges",
+ "content": "**Gauges** — When you need to show how close a value is to a threshold. Think: disk usage at 87%, CPU approaching danger zone."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "tables-structured-data",
+ "title": "Tables & Structured Data",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "When you need to see the actual data, not just a pretty picture."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/OhR1ID6Mk/table",
+ "content": "**Tables** — For when you need rows and columns. Great for top-N lists, detailed breakdowns, or any time you want to see exact values side by side."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "categorical-distribution-charts",
+ "title": "Categorical & Distribution Charts",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Comparing things across categories or understanding how values are distributed."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/ktMs4D6Mk/bar-charts-and-pie-charts",
+ "content": "**Bar Charts & Pie Charts** — Comparing categories. Bar charts for \"which is bigger?\", pie charts for \"what's the proportion?\""
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/histogram_tests/histogram-examples",
+ "content": "**Histograms** — When you want to understand distribution. How are response times spread out? Where do most values fall?"
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "specialized-analytics",
+ "title": "Specialized Analytics",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "More advanced panels for specific analytical needs."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/heatmap-calculate-log/grafana-heatmaps",
+ "content": "**Heatmaps** — Visualizing density and patterns in two dimensions. Perfect for spotting \"hot\" time periods or understanding where values cluster."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/candlestick/candlestick",
+ "content": "**Candlestick** — The classic financial chart. Use it when you're tracking price movements, trades, or any data with open/high/low/close semantics."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "observability-specific",
+ "title": "Observability-Specific",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Built for the unique needs of logs and performance profiling."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/6NmftOxZz/logs-panel",
+ "content": "**Logs Panel** — For viewing log lines directly in your dashboard. Search, filter, and correlate logs alongside your metrics."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/cdl34qv4zzg8wa/flame-graphs",
+ "content": "**Flame Graphs** — For performance profiling. See where your application is spending its time, function by function."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "geospatial",
+ "title": "Geospatial",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "When location matters."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/panel-geomap/geomap-examples",
+ "content": "**Geomaps** — Plot your data on a map. Server locations, regional metrics, delivery routes—anything with latitude and longitude."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "content-navigation-widgets",
+ "title": "Content & Navigation Widgets",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "Helpers for building better dashboards."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/adl33bxy1ih34b/text-panel",
+ "content": "**Text Panels** — Add context to your dashboards with markdown, HTML, or dynamic text. Great for instructions, links, or explanations."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/fdlojrg7daebka/dashboard-list-visualization",
+ "content": "**Dashboard List** — A panel that links to other dashboards. Build navigation hubs or group related dashboards together."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/bdodlcyou483ke/alert-list",
+ "content": "**Alert List** — Show active or recent alerts right in your dashboard. Keep an eye on what's firing without leaving the page."
+ }
+ ]
+ },
+ {
+ "type": "section",
+ "id": "custom-layouts",
+ "title": "Custom Layouts",
+ "blocks": [
+ {
+ "type": "markdown",
+ "content": "When standard panels aren't enough—design your own."
+ },
+ {
+ "type": "interactive",
+ "action": "navigate",
+ "reftarget": "/d/c9ea65f5-ed5a-45cf-8fb7-f82af7c3afdf/canvas-visualization",
+ "content": "**Canvas** — Your blank slate. Place shapes, icons, images, and metrics anywhere you want. Perfect for network diagrams, floor plans, custom status boards, or any layout that doesn't fit a traditional chart."
+ }
+ ]
+ },
+ {
+ "type": "markdown",
+ "content": "**What you have learned:** Grafana's panel library—each one designed for a specific job. Pick the right one, and your data tells its own story. Now go build something awesome!"
+ }
+ ]
+}
diff --git a/welcome-to-play/main-page/content.json b/welcome-to-play/main-page/content.json
index 1a868df4a..71c3fab1f 100644
--- a/welcome-to-play/main-page/content.json
+++ b/welcome-to-play/main-page/content.json
@@ -38,9 +38,13 @@
"type": "interactive",
"action": "highlight",
"reftarget": "a[href*=\"/d/ma79mqp/visualization-examples\"]",
- "completeEarly": true,
+ "content": "Examine the **Visualization Examples** panel showing the wide variety of chart types available.",
"tooltip": "The **Visualization Examples** panel showcases Grafana's extensive visualization library. From *time series* for trend analysis to *bar charts* for comparisons, *heatmaps* for distributions, *geomaps* for location data, and *flame graphs* for performance profiling - Grafana provides the right visualization for every data story. Each link leads to a dedicated dashboard demonstrating that visualization type with real data.",
- "content": "Examine the **Visualization Examples** panel showing the wide variety of chart types available."
+ "requirements": [
+ "on-page:/d/to6j8mh/grafana-play-home",
+ "exists-reftarget"
+ ],
+ "completeEarly": true
}
]
},
@@ -57,9 +61,13 @@
"type": "interactive",
"action": "highlight",
"reftarget": "a[href*=\"/d/mamnq22/data-source-examples\"]",
- "completeEarly": true,
+ "content": "Explore the **Data Source Examples** panel showcasing Grafana's extensive connectivity options.",
"tooltip": "The **Data Source Examples** panel demonstrates Grafana's extensive data source ecosystem. From traditional databases like `PostgreSQL` and `MySQL` to modern observability tools like `Prometheus` and `Loki`, cloud services like `InfluxDB`, and even APIs through the `Infinity` plugin - Grafana connects to virtually any data source. Each example shows real-world use cases and query patterns.",
- "content": "Explore the **Data Source Examples** panel showcasing Grafana's extensive connectivity options."
+ "requirements": [
+ "on-page:/d/to6j8mh/grafana-play-home",
+ "exists-reftarget"
+ ],
+ "completeEarly": true
}
]
},
@@ -76,8 +84,12 @@
"type": "interactive",
"action": "highlight",
"reftarget": "a[href*=\"/d/mabjzp6/grafana-arcade\"]",
+ "content": "Click on the **Grafana Arcade** to explore Grafana's collection of interactive games.",
"tooltip": "The **Grafana Arcade** section includes beloved games like **Doom** and **SuperGrot**, all built with Grafana's powerful visualization capabilities.",
- "content": "Click on the **Grafana Arcade** to explore Grafana's collection of interactive games."
+ "requirements": [
+ "on-page:/d/to6j8mh/grafana-play-home",
+ "exists-reftarget"
+ ]
},
{
"type": "interactive",
@@ -101,8 +113,12 @@
"type": "interactive",
"action": "highlight",
"reftarget": "a[href*=\"a/grafana-k8s-app\"]",
+ "content": "Explore the **Kubernetes Monitoring App** for comprehensive cluster observability.",
"tooltip": "The **Grafana Kubernetes App** provides comprehensive monitoring for Kubernetes clusters. It includes pre-built dashboards for cluster overview, node monitoring, pod performance, namespace usage, and workload analysis. The app automatically discovers your cluster topology and provides intelligent alerting rules based on Kubernetes best practices.",
- "content": "Explore the **Kubernetes Monitoring App** for comprehensive cluster observability."
+ "requirements": [
+ "on-page:/d/to6j8mh/grafana-play-home",
+ "exists-reftarget"
+ ]
}
]
},
@@ -119,8 +135,12 @@
"type": "interactive",
"action": "highlight",
"reftarget": "a[href*=\"a/grafana-app-observability-app\"]",
+ "content": "Visit the **Application Observability App** for end-to-end application monitoring.",
"tooltip": "The **Application Observability App** brings together metrics, logs, and traces to provide complete visibility into application performance. It includes service maps, error tracking, performance monitoring, and user experience analytics. This unified view helps developers and SREs quickly identify and resolve application issues.",
- "content": "Visit the **Application Observability App** for end-to-end application monitoring."
+ "requirements": [
+ "on-page:/d/to6j8mh/grafana-play-home",
+ "exists-reftarget"
+ ]
}
]
},
@@ -137,7 +157,9 @@
"type": "interactive",
"action": "highlight",
"reftarget": "a[data-testid=\"data-testid Nav menu item\"][href=\"/drilldown\"]",
- "requirements": ["navmenu-open"],
+ "requirements": [
+ "navmenu-open"
+ ],
"tooltip": "**Drilldowns** enable contextual navigation between dashboards and data views. When you click on a data point, graph, or table row, you can automatically navigate to related dashboards with relevant filters and time ranges applied. This creates a seamless exploration experience where you can move from high-level overviews to detailed investigations without losing context.",
"content": "Navigate to the **Drilldowns** section to learn about advanced data exploration."
}
@@ -148,5 +170,4 @@
"content": "## 🎉 Congratulations!\n\nYou've completed the comprehensive tour of Grafana Play! You've discovered:\n\n- 📊 **Visualization variety** - From time series to geomaps\n- 🔌 **Data source flexibility** - Connect to anything\n- 🔍 **Advanced exploration** - Drilldowns and contextual navigation\n- ☸️ **Kubernetes monitoring** - Complete cluster observability\n- 📱 **Application insights** - End-to-end observability\n- 🎮 **Creative possibilities** - Even gaming in Grafana!\n\nGrafana Play is your sandbox for exploring these features with real data and no setup required. Feel free to continue exploring, create your own dashboards, and discover what makes Grafana the leading observability platform trusted by millions of users worldwide.\n\n**Next steps:** Try creating your own dashboard, explore more data sources, or dive deeper into any of the features that caught your interest. The possibilities are endless! 🚀"
}
]
-}
-
+}
\ No newline at end of file