Reports

Unentropy generates interactive HTML reports showing how your metrics evolve over time. Reports include charts, statistics, and tools for exploring your data.

Generating Reports

Reports are automatically generated after metric collection in your CI workflow.

In GitHub Actions

The track-metrics action generates a report and uploads it as a workflow artifact:

- name: Track metrics
  uses: unentropy/track-metrics-action@v1

After the workflow completes:

1. Go to the Actions tab in your repository
2. Click on the latest workflow run
3. Download unentropy-report.html from artifacts
4. Open the HTML file in your browser

Local Preview

Preview your report structure locally without collecting real data:

bunx unentropy preview

This generates an empty report showing all configured metrics with placeholder data, then opens it in your browser.

Report Structure

Each report contains:

Header Section

• Repository name
• Generation timestamp
• Data range (first to last build)
• Total build count

Metric Cards

By default, each metric gets its own card with:

• Chart: Interactive visualization of trends
• Statistics: Latest, Min, Max, and Trend
• Description: Metric purpose (if configured)

You can optionally organize cards into named sections and combine related metrics on a single chart. See Customizing Report Layout below.

Controls

• Date range filters: View last 7, 30, 90 days, or all data
• Zoom/pan: Examine specific time periods in detail
• Export: Download charts as PNG images

Chart Types

Numeric Metrics

Displayed as line charts with:

• Smooth curves showing trends over time
• Filled area under the line
• Interactive tooltips with exact values
• X-axis: Build dates
• Y-axis: Metric values (auto-scaled)

Example metrics: Coverage, LOC, bundle size

Label Metrics

Displayed as bar charts with:

• Bars showing occurrence counts per label
• X-axis: Label values
• Y-axis: Count of occurrences

Example metrics: Build status (success/failure), environment

Interactive Features

Synchronized Tooltips

Hover over any chart to see tooltips on all charts for the same build:

Coverage: 87.5% → 88.2% (+0.7%)
Bundle Size: 240 KB → 238 KB (-2 KB)
LOC: 4,521 → 4,580 (+59)

This helps you correlate changes across metrics (e.g., “when coverage dropped, did bundle size increase?”).

Zoom and Pan

Examine specific time periods in detail:

1. Zoom: Scroll mouse wheel over a chart
2. Pan: Click and drag horizontally when zoomed
3. Reset: Click “Reset zoom” to restore original view

Zoom synchronizes across all charts automatically.

Date Range Filters

Quickly focus on recent data:

• 7 days: Last week
• 30 days: Last month
• 90 days: Last quarter
• All: Complete history

The active filter is highlighted. Charts update immediately when you select a new range.

Export Charts

Download individual charts as PNG images:

1. Click Download PNG on any metric card
2. Image downloads with chart title
3. Use in presentations, docs, or reports

Exported images reflect current zoom level and date range filter.

Preview Mode

When you have less than 10 builds, the report includes a preview toggle to show what charts will look like with more data.

Toggle Preview Data

The toggle appears below the report header:

📊 Preview Mode
Show how charts will look with more data
[Toggle Switch: Show preview]

• ON: Shows 20 synthetic data points demonstrating realistic trends
• OFF: Shows your actual collected data

This helps you:

• Validate report setup before collecting real data
• Understand chart appearance with sufficient history
• Test visualization features

Note: The toggle disappears once you have 10+ builds.

Preview Data Watermark

Charts exported while preview mode is active include a “(Preview Data)” watermark to indicate synthetic data.

Sparse Data Handling

Reports handle incomplete data gracefully:

Missing Data Points

If a metric has no value for a specific build:

• Chart shows a gap (no line/point)
• Synchronized tooltip shows “No data for this build”
• X-axis maintains consistent timeline across all charts

Few Data Points

Metrics with fewer than 5 data points show a “sparse data” warning indicator. Collect more data to see meaningful trends.

Empty Charts

When no data exists in the selected date range:

No data in selected range
Try selecting a different time period

Report Theming

Control the visual appearance of your reports with built-in color palettes and light/dark mode settings.

Built-in Themes

Unentropy ships with four built-in themes, each with dark and light variants:

lattice (default)

flux

halftone

specimen

Set a theme in your configuration:

{
  "report": {
    "theme": "flux"
  }
}

Custom Palettes

Override individual colors to match your brand:

{
  "report": {
    "theme": {
      "dark": { "--accent": "#ff00ff" },
      "light": { "--accent": "#aa00aa" }
    }
  }
}

Each palette defines 12 CSS variables (backgrounds, surfaces, borders, text, accent, trend colors). You can override any subset; omitted variables fall back to Lattice defaults. Values must be 7-character hex colors.

Light and Dark Mode

Control how the report selects between palette variants:

{
  "report": {
    "mode": "auto"
  }
}

Mode	Behavior
auto	Respects system prefers-color-scheme (default)
dark	Always uses the dark variant
light	Always uses the light variant

Locking to a specific mode is useful when sharing screenshots or hosting reports where you want a consistent appearance regardless of the viewer’s system settings.

Responsive Design

Reports adapt to different screen sizes:

• Mobile (320px+): Single column, stacked cards
• Tablet (640px+): Two columns
• Desktop (1024px+): Three columns

Print Support

Reports are print-friendly:

1. Open report in browser
2. Print or save as PDF
3. Charts and statistics render correctly

Customizing Report Layout

As your project grows, a flat grid of all metrics can become hard to navigate. You can organize reports into named sections and plot related metrics together on a single chart.

Sections

Group related metrics under section headers:

{
  "report": {
    "sections": [
      {
        "name": "Code Size",
        "description": "Source code and build artifact metrics",
        "charts": [
          { "metrics": "typescript-loc" },
          { "metrics": "javascript-loc" },
          { "metrics": "bundle" }
        ]
      },
      {
        "name": "Quality",
        "charts": [
          { "metrics": "coverage" },
          { "metrics": "test-count" }
        ]
      }
    ]
  }
}

Each section displays its name as a header with an optional description. Charts appear in the order defined. Metrics not referenced in any section are omitted from the report (they may still be used for quality gates).

Multi-Metric Charts

Plot multiple related metrics on a single chart to compare them directly:

{
  "report": {
    "sections": [
      {
        "name": "Refactoring Progress",
        "charts": [
          {
            "metrics": ["modern-classes", "legacy-classes"],
            "title": "Modern vs Legacy Class Count"
          }
        ]
      }
    ]
  }
}

This renders one chart card containing both metrics as separate lines with distinct colors and a legend. Metrics with incompatible units or vastly different scales automatically receive dual Y-axes so both series remain clearly visible.

Custom Chart Titles

Override the default title derived from metric names:

{
  "metrics": "bundle-size",
  "title": "Production Bundle Size"
}

Backward Compatibility

Omitting the report block entirely preserves the original flat layout: every metric gets its own single-metric chart displayed in definition order.

Publishing to GitHub Pages

Host your reports on GitHub Pages for easy team access.

Add Deployment Job

Update .github/workflows/metrics.yml:

jobs:
  track-metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with coverage
        run: bun test --coverage
      - name: Track metrics
        uses: unentropy/track-metrics-action@v1

  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    needs: track-metrics
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Enable GitHub Pages

1. Go to repository Settings → Pages
2. Source: GitHub Actions
3. Save

After the next workflow run, your report will be available at:

https://<username>.github.io/<repo>/

Example Reports

Minimal Data

Report with 3 builds showing early trends:

• Preview toggle available
• All charts display sparse data warning
• Metrics show “N/A” for trend (insufficient data)

Full History

Report with 100+ builds showing rich trends:

• No preview toggle (enough data)
• Clear trends visible (↑ increasing, ↓ decreasing, → stable)
• Zoom/pan useful for examining specific periods

Multiple Metrics

Report tracking 5+ metrics:

• Grid layout shows all metrics at once
• Synchronized tooltips help correlate changes
• Date filters let you focus on recent activity

Accessibility

Reports meet WCAG 2.1 AA standards:

• Color contrast for readability
• Keyboard navigation support
• Screen reader labels for charts
• Focus indicators on interactive elements

Troubleshooting

Report Shows No Data

Problem: Empty charts despite successful metric collection

Solutions:

• Verify metrics were collected successfully in workflow logs
• Check storage backend is working (database accessible)
• Ensure track-metrics action completed without errors
• Download database artifact and verify it contains data

Charts Not Interactive

Problem: Tooltips, zoom, or filters don’t work

Solutions:

• Ensure JavaScript is enabled in browser
• Check browser console for errors
• Verify CDN resources loaded (Chart.js, chartjs-plugin-zoom)
• Try a different browser (Chrome, Firefox, Safari, Edge)

Preview Toggle Doesn’t Appear

Problem: Expected preview toggle but not visible

Possible reasons:

• You have 10+ builds (toggle only shows for <10 builds)
• Report was generated with older version
• JavaScript error prevented toggle from rendering

Solution: Check build count in report header. If <10, check browser console for errors.

Exported Charts Are Blank

Problem: Downloaded PNG files are empty or corrupted

Solutions:

• Wait for chart to fully render before exporting
• Disable browser extensions that might interfere
• Try exporting from a different chart
• Check browser console for export errors

Dark Mode Not Working

Problem: Report doesn’t use dark mode

Solutions:

• Check report.mode in your configuration. If set to "light", the report will always use the light palette regardless of system settings. Change to "auto" or "dark" to enable dark mode.
• If report.mode is "auto" or not set, dark mode follows your OS preference. Check your system dark mode setting.
• Some browsers need to be restarted after changing system preferences.

Related Resources

• Metrics Guide - Configure metrics to track
• Getting Started - Initial setup
• Storage Guide - Where reports are stored