Skip to main content
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

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
Common issues:
  • Missing quotes around strings
  • Trailing commas in JSON
  • Incorrect bracket matching
  • Use a JSON validator to check syntax
The |distinct modifier only works with Count aggregate type. Change your aggregate type to “Count”.

Build docs developers (and LLMs) love

Get started for freeTalk to us