Dashboards and Graphs

Create custom dashboards with charts to visualize your Ralph data

Ralph’s dashboard system provides a flexible mechanism for displaying data via bar charts and pie charts, helping you visualize key metrics about your infrastructure.

Overview

Dashboards allow you to:

• Create custom graphs from any Ralph model data
• Display data as vertical bars, horizontal bars, or pie charts
• Aggregate and filter data with complex queries
• Push metrics to statsd for external monitoring
• Build multiple graphs into unified dashboards

Getting Started

This tutorial will walk through creating a dashboard showing asset quantities across data centers.

Demo Data

To experiment with dashboards, generate sample data:

ralph make_demo_data

Creating Your First Dashboard

1. Create Dashboard Object

   Navigate to Dashboards → Dashboards and click Add new dashboard.

   Give your dashboard a name and description.

2. Create a Graph

   Click Add Graph and configure it with:

   • Name: “DC Capacity”
   • Model: Select the model to query (e.g., DataCenterAsset)
   • Chart Type: Choose Vertical Bar, Horizontal Bar, or Pie Chart
   • Aggregate Type: Count, Sum, Max, etc.
3. Configure Graph Parameters

   Add the JSON configuration in the Params field (see below).

4. Assign Graph to Dashboard

   After saving the graph, edit your dashboard and select the graph from the Graphs field.

5. View Your Dashboard

   Go to Dashboards → Dashboards list view and click the Link icon to view your dashboard.

Graph Configuration

Graphs are configured using JSON in the Params field.

Required Fields

{
  "labels": "name",
  "series": "rack",
  "filters": {
    "status": "active"
  }
}

• labels - Field to use for string representation (x-axis labels)
• series - Field to aggregate by
• filters - Django ORM-style filter conditions

Optional Fields

{
  "excludes": {
    "name__exact": null
  },
  "aggregate_expression": "id",
  "limit": 10,
  "sort": "-series"
}

• excludes - Exclude items from results (opposite of filters)
• aggregate_expression - Override default aggregation field
• limit - Limit number of results
• sort - Order results by field

Target Options

Change the clickable graph behavior:

{
  "target": {
    "model": "datacenterasset",
    "filter": "rack__id__in",
    "value": "rack__id"
  }
}

Advanced Aggregation

Distinct Values

Count distinct values using the |distinct modifier:

{
  "labels": "name",
  "series": "serverroom__rack|distinct",
  "filters": {
    "series__lt": 5
  }
}

Ratio Calculations

Calculate ratios between two fields:

{
  "labels": "service_env__service__name",
  "series": [
    "securityscan__is_patched",
    "id"
  ]
}

Set Aggregate Type to “Ratio” for this to work.

Date-Based Grouping

Group by parts of dates:

{
  "labels": "service_env__service__name",
  "series": "created|year"
}

Available modifiers: year, month, day, hour, minute, second

Special Filters

Series Filter

Filter on aggregated values:

{
  "labels": "name",
  "series": "serverroom__rack",
  "filters": {
    "series__lt": 5
  }
}

This shows only labels where the count is less than 5.

OR and AND Operators

{
  "labels": "name",
  "series": "serverroom__rack",
  "excludes": {
    "name__exact|or": [null, ""]
  }
}

Accepts a list of values to match.

Time-Relative Filters

Filter by relative time using from_now:

{
  "labels": "name",
  "series": "serverroom__rack__datacenterasset",
  "filters": {
    "created__gt|from_now": "-1y"
  }
}

Time units:

• y - years
• m - months
• d - days

Example: "-1y" means one year ago to now.

Example Configurations

Assets by Data Center

{
  "labels": "rack__server_room__data_center__name",
  "series": "id",
  "filters": {
    "status": 2
  }
}

Services by Environment

{
  "labels": "service_env__environment__name",
  "series": "id",
  "excludes": {
    "service_env__isnull": true
  }
}

Asset Age Distribution

{
  "labels": "invoice_date|year",
  "series": "id",
  "filters": {
    "invoice_date__isnull": false
  },
  "sort": "invoice_date|year"
}

Integration with Statsd

Push graph data to statsd for external monitoring systems.

1. Configure Settings

   Add to your Ralph settings:

   STATSD_GRAPHS_PREFIX = 'ralph.graphs'
   ALLOW_PUSH_GRAPHS_DATA_TO_STATSD = True
   COLLECT_METRICS = True
   
2. Enable on Graph

   Check Push to statsd on your graph configuration.

3. Push Data

   Run the management command:

   ralph push_graphs_to_statsd
   

Set up a cron job to push data regularly.

REST API

Access dashboard data via the REST API:

# Get all graphs
curl https://<YOUR-RALPH-URL>/api/graph/ | python -m json.tool

# Get specific graph details
curl https://<YOUR-RALPH-URL>/api/graph/1/ | python -m json.tool

All endpoints are read-only.

Tips and Best Practices

Start Simple: Begin with basic label/series configurations before adding complex filters.

Test Filters: Use Django’s ORM query syntax. Test complex queries in the Django shell first.

Performance: Use limit to restrict large result sets and improve rendering speed.

Complex aggregations with multiple joins can be slow. Test performance with production data volumes.

Troubleshooting

Graph shows no data

Check:

• Your filters might be too restrictive
• The model has data matching your criteria
• Field names are correct (use Django model field names)
• JSON syntax is valid

JSON parsing error

Common issues:

• Missing quotes around strings
• Trailing commas in JSON
• Incorrect bracket matching
• Use a JSON validator to check syntax

Distinct aggregation not working

The |distinct modifier only works with Count aggregate type. Change your aggregate type to “Count”.

Related Documentation

• Custom Fields - Add custom data to visualize
• DCIM - Data center asset data