Diffdash

PR-scoped observability dashboard generator.

Diffdash analyzes Ruby code changed in a Pull Request and generates dashboards for Grafana, Datadog, or Kibana — showing only the logs and metrics relevant to your changes.

No more searching through dashboards with thousands of metrics. See exactly what matters to your code.

Quick Start

gem install diffdash

Create diffdash.yml:

outputs:
  - grafana

grafana:
  url: https://myorg.grafana.net
  folder_id: 42

Set your token and run:

export DIFFDASH_GRAFANA_TOKEN=glsa_xxxxxxxxxxxx
diffdash

Supported Backends

Backend	Output	API Upload
Grafana	Loki logs, PromQL metrics	✅
Datadog	Log streams, timeseries	✅
Kibana	Saved searches, metrics	✅
JSON	Raw signal data	—

CLI

diffdash grafana          # Generate Grafana dashboard
diffdash kibana           # Generate Kibana dashboard  
diffdash datadog          # Generate Datadog dashboard
diffdash json             # Output raw signal JSON

diffdash grafana --dry-run    # Generate without uploading
diffdash grafana folders      # List Grafana folders
diffdash kibana folders       # List Kibana spaces
diffdash lint                 # Check for observability best practices
diffdash lint --verbose       # Show details for each issue
diffdash --list-signals       # Show detected signals

What It Detects

Logs:

logger.info("user_created")
Rails.logger.error("payment_failed")

Metrics:

StatsD.increment("orders.processed")
Prometheus.counter(:requests_total).increment
Hesiod.emit("cache.hit")

# Also resolves centralized metric constants:
Metrics::RequestTotal.increment  # → "request_total"

GitHub Actions

name: Diffdash Dashboard

on:
  pull_request:
    paths: ["**/*.rb", "!spec/**"]

jobs:
  dashboard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: ruby/setup-ruby@v1

      - run: gem install diffdash

      - run: diffdash --verbose
        env:
          DIFFDASH_GRAFANA_URL: ${{ secrets.DIFFDASH_GRAFANA_URL }}
          DIFFDASH_GRAFANA_TOKEN: ${{ secrets.DIFFDASH_GRAFANA_TOKEN }}

Configuration

Environment variables always override config file values.

Variable	Description
DIFFDASH_GRAFANA_URL	Grafana URL
DIFFDASH_GRAFANA_TOKEN	Grafana Service Account token
DIFFDASH_DATADOG_API_KEY	Datadog API key
DIFFDASH_DATADOG_APP_KEY	Datadog Application key
DIFFDASH_KIBANA_URL	Kibana URL
DIFFDASH_KIBANA_API_KEY	Kibana API key
DIFFDASH_OUTPUTS	Comma-separated outputs
DIFFDASH_INTERPOLATED_LOGS	How to handle interpolated logs (include, warn, exclude)

Signal Filtering

Control how interpolated logs are handled:

# diffdash.yml
signals:
  interpolated_logs: exclude  # exclude noisy dynamic logs

Value	Behavior
include	Include all logs (default)
warn	Include all, show CLI warning
exclude	Exclude interpolated logs from dashboard

See DOCS.md for full configuration reference.

Example

For a complete working example with CI integration, see: diffdash-test-app

Documentation

📖 Full Documentation — Configuration, signal detection, GitHub Actions, troubleshooting.

License

MIT