Dashboards and Visualization in GitLab

Overview

GitLab provides comprehensive dashboard capabilities for visualizing metrics, logs, traces, and analytics. Dashboards help teams monitor system health, track performance trends, and make data-driven decisions.

Dashboard Types in GitLab

1. Analytics Dashboards

Custom dashboards for project and group metrics.

Access: Analyze Analytics dashboards

Features:

• Custom visualizations
• Multiple data sources
• Shareable across teams
• Version-controlled configuration

2. Value Streams Dashboard

Single source of truth (SSOT) for DevOps metrics.

Access: Analyze Value streams dashboard

Features:

• DORA metrics
• Cycle time analysis
• Deployment frequency
• Change failure rate

3. Operations Dashboards (Deprecated)

Legacy metric dashboards being migrated to Analytics Dashboards.

Note: Use Analytics Dashboards for new implementations.

Creating Analytics Dashboards

Dashboard Configuration

Dashboards are defined in YAML files stored in your repository:

project/
 .gitlab/
    analytics/
        dashboards/
            overview.yaml
            performance.yaml
            visualizations/
                error_rate.yaml
                latency.yaml
                throughput.yaml

Basic Dashboard Structure

# .gitlab/analytics/dashboards/overview.yaml
title: System Overview Dashboard
description: High-level system metrics and performance indicators

visualizations:
  - ref: visualizations/error_rate.yaml
  - ref: visualizations/latency.yaml
  - ref: visualizations/throughput.yaml

Visualization Configuration

# .gitlab/analytics/dashboards/visualizations/error_rate.yaml
type: single_stat
title: Error Rate
description: Percentage of failed requests

data:
  type: cube_analytics
  query:
    measures:
      - Requests.errorRate
    timeDimensions:
      - dimension: Requests.timestamp
        dateRange: last 30 days

options:
  decimalPlaces: 2
  unit: percentage

Visualization Types

1. Single Stat

Display a single metric value:

type: single_stat
title: Total Users
data:
  type: cube_analytics
  query:
    measures:
      - Users.count
options:
  decimalPlaces: 0
  unit: users

2. Line Chart

Time-series trends:

type: line_chart
title: Request Rate Over Time
data:
  type: cube_analytics
  query:
    measures:
      - Requests.count
    timeDimensions:
      - dimension: Requests.timestamp
        dateRange: last 7 days
        granularity: hour
options:
  xAxis:
    name: Time
  yAxis:
    name: Requests per hour

3. Bar Chart

Compare values across categories:

type: bar_chart
title: Requests by Endpoint
data:
  type: cube_analytics
  query:
    measures:
      - Requests.count
    dimensions:
      - Requests.endpoint
    order:
      Requests.count: desc
    limit: 10
options:
  xAxis:
    name: Endpoint
  yAxis:
    name: Request Count

4. Pie Chart

Show proportional distribution:

type: pie_chart
title: Error Distribution by Type
data:
  type: cube_analytics
  query:
    measures:
      - Errors.count
    dimensions:
      - Errors.type
options:
  showLegend: true
  showLabels: true

5. Table

Display tabular data:

type: table
title: Slowest Endpoints
data:
  type: cube_analytics
  query:
    measures:
      - Requests.avgDuration
      - Requests.count
    dimensions:
      - Requests.endpoint
    order:
      Requests.avgDuration: desc
    limit: 20
options:
  columns:
    - name: Endpoint
      field: Requests.endpoint
    - name: Avg Duration (ms)
      field: Requests.avgDuration
      type: number
      decimalPlaces: 0
    - name: Request Count
      field: Requests.count
      type: number

Data Sources

Cube Analytics

Query structured data using Cube.js:

data:
  type: cube_analytics
  query:
    measures:
      - Orders.count
      - Orders.totalRevenue
    dimensions:
      - Orders.status
    timeDimensions:
      - dimension: Orders.createdAt
        dateRange: this month
    filters:
      - member: Orders.status
        operator: equals
        values: ['completed']

Product Analytics

GitLab's built-in product analytics:

data:
  type: product_analytics
  query:
    event: page_view
    groupBy: page_path
    aggregation: count
    dateRange: last 30 days

Example Dashboards

System Health Dashboard

# .gitlab/analytics/dashboards/system-health.yaml
title: System Health Dashboard
description: Real-time system health and performance metrics

layout:
  rows:
    - title: Overview
      panels:
        - ref: visualizations/uptime.yaml
        - ref: visualizations/error_rate.yaml
        - ref: visualizations/response_time.yaml
        - ref: visualizations/throughput.yaml

    - title: Performance
      panels:
        - ref: visualizations/latency_distribution.yaml
        - ref: visualizations/slowest_endpoints.yaml

    - title: Resources
      panels:
        - ref: visualizations/cpu_usage.yaml
        - ref: visualizations/memory_usage.yaml
        - ref: visualizations/disk_usage.yaml

Uptime Visualization

# visualizations/uptime.yaml
type: single_stat
title: Uptime
description: System availability percentage

data:
  type: cube_analytics
  query:
    measures:
      - Uptime.percentage
    timeDimensions:
      - dimension: Uptime.timestamp
        dateRange: last 30 days

options:
  decimalPlaces: 3
  unit: percentage
  thresholds:
    - value: 99.9
      color: green
    - value: 99.0
      color: yellow
    - value: 0
      color: red

Latency Distribution

# visualizations/latency_distribution.yaml
type: histogram
title: Response Time Distribution
description: P50, P95, P99 latencies

data:
  type: cube_analytics
  query:
    measures:
      - Requests.p50Latency
      - Requests.p95Latency
      - Requests.p99Latency
    timeDimensions:
      - dimension: Requests.timestamp
        dateRange: last 24 hours
        granularity: hour

options:
  yAxis:
    name: Latency (ms)
  series:
    - name: P50
      color: green
    - name: P95
      color: yellow
    - name: P99
      color: red

Business Metrics Dashboard

# .gitlab/analytics/dashboards/business-metrics.yaml
title: Business Metrics Dashboard
description: Key business KPIs and revenue metrics

layout:
  rows:
    - title: Revenue
      panels:
        - ref: visualizations/daily_revenue.yaml
        - ref: visualizations/revenue_by_product.yaml

    - title: Users
      panels:
        - ref: visualizations/active_users.yaml
        - ref: visualizations/new_signups.yaml
        - ref: visualizations/churn_rate.yaml

    - title: Engagement
      panels:
        - ref: visualizations/dau_mau_ratio.yaml
        - ref: visualizations/session_duration.yaml

CI/CD Performance Dashboard

# .gitlab/analytics/dashboards/cicd-performance.yaml
title: CI/CD Performance Dashboard
description: Pipeline and deployment metrics

visualizations:
  - ref: visualizations/pipeline_success_rate.yaml
  - ref: visualizations/pipeline_duration.yaml
  - ref: visualizations/deployment_frequency.yaml
  - ref: visualizations/failed_jobs.yaml

Prometheus Integration

Connecting Prometheus

Configure Prometheus as a data source:

1. Navigate to Settings Monitor Metrics
2. Add Prometheus endpoint
3. Configure authentication

Querying Prometheus

# visualizations/http_requests.yaml
type: line_chart
title: HTTP Request Rate

data:
  type: prometheus
  query: rate(http_requests_total[5m])
  legend: "{{ method }} {{ status }}"

options:
  yAxis:
    name: Requests/second

Common Prometheus Queries

Request Rate

data:
  type: prometheus
  query: |
    sum(rate(http_requests_total[5m])) by (status)
  legend: "Status {{ status }}"

Error Rate

data:
  type: prometheus
  query: |
    sum(rate(http_requests_total{status=~"5.."}[5m]))
    /
    sum(rate(http_requests_total[5m]))
  legend: "Error Rate"

P95 Latency

data:
  type: prometheus
  query: |
    histogram_quantile(0.95,
      rate(http_request_duration_seconds_bucket[5m])
    )
  legend: "P95 Latency"

CPU Usage

data:
  type: prometheus
  query: |
    100 - (avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
  legend: "{{ instance }}"

Grafana Integration

Connecting GitLab to Grafana

1. Add Prometheus data source in Grafana
2. Configure data source:

   name: GitLab Prometheus
   type: prometheus
   url: https://gitlab.com/-/metrics
   access: proxy
   basicAuth: true
   basicAuthUser: gitlab
   basicAuthPassword: <token>

GitLab Dashboard Templates

Import pre-built dashboards:

{
  "dashboard": {
    "title": "GitLab CI/CD Performance",
    "uid": "gitlab-cicd",
    "panels": [
      {
        "title": "Pipeline Success Rate",
        "type": "stat",
        "targets": [
          {
            "expr": "sum(rate(gitlab_ci_pipeline_status{status=\"success\"}[1h])) / sum(rate(gitlab_ci_pipeline_status[1h]))",
            "legendFormat": "Success Rate"
          }
        ]
      },
      {
        "title": "Pipeline Duration",
        "type": "graph",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(gitlab_ci_pipeline_duration_seconds_bucket[5m]))",
            "legendFormat": "P95 Duration"
          }
        ]
      }
    ]
  }
}

Advanced Grafana Panel

{
  "title": "Request Rate by Endpoint",
  "type": "graph",
  "datasource": "GitLab Prometheus",
  "targets": [
    {
      "expr": "sum(rate(http_requests_total[5m])) by (endpoint)",
      "legendFormat": "{{ endpoint }}"
    }
  ],
  "yaxes": [
    {
      "label": "Requests/sec",
      "format": "reqps"
    }
  ],
  "legend": {
    "show": true,
    "values": true,
    "current": true,
    "avg": true,
    "max": true
  },
  "tooltip": {
    "shared": true,
    "sort": 2
  }
}

Dashboard Best Practices

1. Design Principles

Hierarchy of Information:

• Most important metrics at the top
• Group related metrics together
• Use consistent color schemes

Progressive Disclosure:

High-level Overview
 Critical Metrics (Red/Yellow/Green status)
 Trend Charts (Last 24 hours)
 Detailed Breakdowns (Click for more detail)

2. Metric Selection

Focus on Actionable Metrics:

• Error rate Can investigate and fix
• P95 latency Can optimize
• Total requests Interesting but not actionable

Use Golden Signals (Google SRE):

• Latency
• Traffic
• Errors
• Saturation

3. Visual Design

Color Coding:

thresholds:
  - value: 0
    color: green    # Good performance
  - value: 50
    color: yellow   # Warning
  - value: 80
    color: red      # Critical

Chart Types:

• Single stats: Current values, totals
• Line charts: Trends over time
• Bar charts: Comparisons
• Pie charts: Proportions (use sparingly)
• Tables: Detailed breakdowns

4. Time Ranges

Provide multiple time range options:

• Last 15 minutes (real-time monitoring)
• Last hour (recent activity)
• Last 24 hours (daily patterns)
• Last 7 days (weekly trends)
• Last 30 days (monthly overview)

5. Performance Optimization

Limit Query Complexity:

# Bad: Expensive aggregation
query: |
  sum(rate(http_requests_total[5m])) by (method, endpoint, status, user)

# Good: Focused aggregation
query: |
  sum(rate(http_requests_total[5m])) by (status)

Use Recording Rules for complex queries:

# Prometheus recording rule
groups:
  - name: dashboard_rules
    interval: 30s
    rules:
      - record: job:http_requests:rate5m
        expr: sum(rate(http_requests_total[5m])) by (job)

Sharing Dashboards

Project-Level Sharing

Dashboards in .gitlab/analytics/dashboards/ are visible to all project members.

Group-Level Sharing

Create shared dashboards for multiple projects:

# .gitlab/analytics/dashboards/shared-metrics.yaml
title: Group-Wide Metrics
description: Shared metrics across all projects

scope: group  # Available to all group projects

visualizations:
  - ref: visualizations/group_deployment_frequency.yaml
  - ref: visualizations/group_error_rate.yaml

Public Dashboards

Share dashboards externally:

1. Navigate to dashboard
2. Click Share
3. Enable Public access
4. Copy public URL

Security Note: Only share non-sensitive metrics publicly.

Embedding Dashboards

Embed in GitLab Pages

<!-- docs/index.html -->
<!DOCTYPE html>
<html>
<head>
  <title>System Metrics</title>
</head>
<body>
  <h1>Live System Metrics</h1>
  <iframe
    src="https://gitlab.com/my-org/my-project/-/analytics/dashboards/overview"
    width="100%"
    height="800px"
    frameborder="0">
  </iframe>
</body>
</html>

Embed in External Sites

<!-- External website -->
<iframe
  src="https://gitlab.com/my-org/my-project/-/analytics/dashboards/public/abc123"
  width="1200"
  height="600"
  frameborder="0"
  allowfullscreen>
</iframe>

Alerting from Dashboards

Visual Alerts

Add threshold indicators:

type: single_stat
title: Error Rate
data:
  type: prometheus
  query: |
    sum(rate(http_requests_total{status=~"5.."}[5m]))
    / sum(rate(http_requests_total[5m]))

options:
  thresholds:
    - value: 0
      color: green
    - value: 0.01    # 1% error rate
      color: yellow
      alert: warning
    - value: 0.05    # 5% error rate
      color: red
      alert: critical
  alerts:
    - type: slack
      channel: '#alerts'
      condition: value > 0.05

Link to Alert Rules

Reference alert configuration:

type: line_chart
title: Response Time
data:
  type: prometheus
  query: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

options:
  alerts:
    - name: HighLatency
      threshold: 1.0
      severity: warning
      runbook: https://gitlab.com/runbooks/high-latency

Mobile Dashboards

Responsive Design

Dashboards automatically adapt to mobile screens:

• Stacked panels on small screens
• Touch-friendly controls
• Simplified visualizations

Mobile App Integration

Access dashboards in GitLab mobile app:

1. Open GitLab mobile app
2. Navigate to project
3. Analytics Dashboards

Troubleshooting

Dashboard Not Loading

Check YAML syntax:

# Validate YAML locally
yamllint .gitlab/analytics/dashboards/overview.yaml

Check data source connectivity:

# Test Prometheus query
curl -G https://prometheus:9090/api/v1/query \
  --data-urlencode 'query=up' | jq

Slow Dashboard Performance

Optimize queries:

• Use shorter time ranges
• Reduce label cardinality
• Use recording rules

Enable caching:

options:
  cache:
    enabled: true
    ttl: 60  # Cache for 60 seconds

Missing Metrics

Verify metric collection:

# Check if metric exists
curl -G https://prometheus:9090/api/v1/label/__name__/values | grep my_metric

Check scrape configuration:

# View Prometheus targets
curl https://prometheus:9090/api/v1/targets | jq '.data.activeTargets'

References

• GitLab Analytics Dashboards Documentation
• Value Streams Dashboard Documentation
• Grafana Documentation
• Prometheus Best Practices

Related Documentation

• Metrics - Prometheus metrics collection
• CI/CD Analytics - Pipeline performance metrics
• DORA Metrics - DevOps performance indicators
• Alerting - Alert configuration and management