Using Grafana Reporting

1. Understanding Reporting

Example: Creating a report configuration

{
  "name": "Monthly Sales Report",
  "dashboard": {
    "uid": "monthly-sales-dashboard"
  },
  "recipients": [
    "team@example.com"
  ],
  "schedule": {
    "interval": "monthly",
    "day": 1
  },
  "format": "pdf"
}

Property	Description	Values
name	Name of the report	`string`
dashboard.uid	Unique identifier of the dashboard to report on	`string`
recipients	Email addresses to send the report to	`array<string>`
schedule.interval	How often to generate the report	`daily \| weekly \| monthly`
schedule.day	Day of the month or week to run the report	`number`
format	Output format of the report	`pdf \| png \| csv`

Note: Reports can be scheduled to run automatically or generated on-demand.

Warning: Ensure email permissions are configured correctly to send reports.

2. Creating Reports

Example: Create a report using Grafana UI

1. Navigate to the Grafana dashboard you want to report on.
2. Click the "Share" button in the top right corner.
3. Select "Report" from the dropdown menu.
4. Configure report settings:
   - Report title
   - Time range (e.g., last 24 hours)
   - Format (PDF, PNG, or CSV)
5. Schedule the report (optional).
6. Click "Generate Report".

Setting	Description	Values
report.title	Title of the report	`System Performance Report`
report.timeRange	Time range for data in the report	`last 24h, last 7d, custom`
report.format	Output format of the report	`PDF, PNG, CSV`
report.schedule	Frequency of report generation	`daily, weekly, monthly`

Note: Reports can be generated for dashboards with multiple panels, and each panel will appear as a separate page in the PDF report.

Warning: Large reports with many panels or long time ranges may take longer to generate and could exceed system limits.

3. Scheduling Reports

Field	Description	Values
name	Name of the report	`string`
schedule	CRON expression or preset	`"0 0 * * *"` or `"daily"`
recipients	Email addresses or channels to send report to	`["user@example.com"]`
format	Report format (PDF, PNG)	`"pdf"`, `"png"`
dashboardUid	Unique identifier of the dashboard	`"abc123"`
timeRange	Time range for report data	`"last_24h"`, `"last_7d"`

Example: Scheduling a Daily Report

{
  "name": "Daily Metrics Report",
  "schedule": "0 0 * * *",
  "recipients": ["admin@example.com"],
  "format": "pdf",
  "dashboardUid": "abc123",
  "timeRange": "last_24h"
}

Note: Reports are generated and sent based on the schedule. Ensure email settings are configured in Grafana for successful delivery.

4. Configuring Report Format

Property	Values	Description
format	`pdf`, `png`, `csv`	Specifies the output format of the report. Default is `pdf`.
orientation	`portrait`, `landscape`	Defines the page orientation for PDF reports. Default is `portrait`.
includeAnnotations	`true`, `false`	Controls whether annotations are included in the report. Default is `true`.
includeImage	`true`, `false`	Indicates whether to embed images in the report. Default is `true`.

Example: Setting Report Format to PNG

{
  "format": "png",
  "orientation": "landscape",
  "includeAnnotations": false
}

Note: PNG reports are best for visual dashboards with charts and graphs.

5. Setting Report Recipients

Recipient Type	Configuration	Notes
Email	`"to": "user@example.com"`	Single email or comma-separated list
Slack	`"slack": {"url": "https://hooks.slack.com/services/..."}`	Webhook URL for Slack channel
Microsoft Teams	`"teams": {"url": "https://outlook.office.com/webhook/..."}`	Webhook URL for Teams channel

Example: Email Report Recipients

{
  "to": "admin@example.com, team@example.com",
  "cc": "monitoring@example.com"
}

Example: Slack Report Recipients

{
  "slack": {
    "url": "https://hooks.slack.com/services/123456789/000000000/XXXXXXXXXX"
  }
}

6. Configuring Report Layout

Example: Basic Report Layout Configuration

{
  "name": "Monthly Report",
  "layout": {
    "header": {
      "title": "Monthly Report",
      "show": true
    },
    "footer": {
      "text": "Generated by Grafana",
      "show": true
    },
    "page": {
      "orientation": "portrait",
      "size": "A4"
    }
  }
}

Property	Description	Values	Notes
layout.header.title	Title of the report header	`string`	Displayed at the top of each page
layout.header.show	Whether to show the header	`true` \| `false`	Default: `true`
layout.footer.text	Footer text to display	`string`	Can include date/time placeholders
layout.footer.show	Whether to show the footer	`true` \| `false`	Default: `true`
layout.page.orientation	Page orientation	`portrait` \| `landscape`	Default: `portrait`
layout.page.size	Page size for report	`A4`, `Letter`, `Legal`	Default: `A4`

Note: The report layout configuration is part of the Grafana reporting API and can be customized via JSON when creating or updating report definitions.

7. Setting Report Time Range

Property	Description	Values	Notes
timeRange.from	Start time for the report	`now-1h`, `now-6h`, `now-1d`, `2024-01-01T00:00:00Z`	Supports relative and absolute time formats
timeRange.to	End time for the report	`now`, `now-1h`, `2024-01-01T00:00:00Z`	Must be after `from` time

Example: Setting Time Range in Report

{
  "timeRange": {
    "from": "now-1d",
    "to": "now"
  }
}

8. Using Report Variables

Variable	Description	Usage	Notes
__dashboard.name__	Name of the dashboard	`{{__dashboard.name__}}`	Available in report templates
__dashboard.uid__	Unique identifier of the dashboard	`{{__dashboard.uid__}}`	Used for linking or tracking
__dashboard.url__	URL to the dashboard	`{{__dashboard.url__}}`	Includes full path to dashboard
__report.created__	Time when report was generated	`{{__report.created__}}`	Formatted as ISO string
__report.title__	Title of the report	`{{__report.title__}}`	Set in report settings
__report.time.from__	Start time of report period	`{{__report.time.from__}}`	Uses dashboard time range
__report.time.to__	End time of report period	`{{__report.time.to__}}`	Uses dashboard time range

Example: Using Dashboard Name in Report

Dashboard: {{__dashboard.name__}}
Generated at: {{__report.created__}}

Note: Report variables are only available in the context of Grafana reports and cannot be used in regular dashboard panels or queries.

9. Managing Report Templates

Property	Description	Default Value	Notes
name	Name of the report template	""	Required field
description	Optional description of the report template	""	Helps identify templates in UI
layout	Layout type for the report	"grid"	Options: "grid", "list"
timezone	Timezone used in report generation	"browser"	Can be "utc", "browser", or custom IANA timezone
timeRange	Time range for report data	"last 24 hours"	Can be a relative or absolute time range
dashboardUid	Unique identifier of the dashboard	null	Required for report generation

Example: Creating a Report Template

{
  "name": "Weekly Sales Report",
  "description": "Weekly sales dashboard report",
  "layout": "grid",
  "timezone": "utc",
  "timeRange": "last 7 days",
  "dashboardUid": "abc123"
}

Note: Report templates can be managed via the Grafana UI under Configuration > Reporting or through the API.

Warning: Templates with invalid dashboard UIDs will not generate reports and must be corrected.

10. Viewing Report History

Field	Description	Value
reportId	Unique identifier for the report	`string`
name	Name of the report	`string`
createdBy	User who created the report	`string`
createdAt	Timestamp when report was created	`datetime`
lastModified	Timestamp of last modification	`datetime`
status	Current status of the report (e.g., completed, failed)	`string`
format	Format of the report (PDF, PNG, etc.)	`string`
recipients	Email addresses of report recipients	`array`

Example: Fetching Report History

const reportHistory = [
  {
    reportId: "report-123",
    name: "Monthly Report",
    createdBy: "admin@example.com",
    createdAt: "2025-04-01T10:00:00Z",
    lastModified: "2025-04-01T10:05:00Z",
    status: "completed",
    format: "pdf",
    recipients: ["user1@example.com", "user2@example.com"]
  },
  {
    reportId: "report-456",
    name: "Weekly Summary",
    createdBy: "admin@example.com",
    createdAt: "2025-03-25T14:30:00Z",
    lastModified: "2025-03-25T14:35:00Z",
    status: "failed",
    format: "png",
    recipients: ["user3@example.com"]
  }
];

Note: The report history includes all reports generated in the last 30 days by default.