> For the complete documentation index, see [llms.txt](https://docs.datasentinel.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasentinel.io/manual/features/key-features/reporting.md).

# Reporting

Turn any time window of your PostgreSQL activity into a PDF report: download it, email it once, or schedule it, from the web interface, the API, or an AI assistant.

A report is a self-contained PDF snapshot of your PostgreSQL activity over a time window. It mirrors the dashboards of the web interface, with the same charts and tables, and it travels where a dashboard cannot: a ticket, an email, a post-mortem, a weekly review.

<figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2Fgit-blob-91b95eafe3ec00ea491ed9e7bd3be38ba5d1c950%2Freporting.svg?alt=media" alt="Animated illustration of the Reporting feature. On the left, the Create Report form: the report type is chosen from a list (Instance, Workload, Top queries, Session history, Data size), then the database and the time window, then the action (Download report, One time email, Scheduled email), and the Save button. On the right, the generated Workload report PDF appears page by page: time window, PostgreSQL instance, active sessions chart, top queries bars, cluster and system metrics. Four green confirmations list the delivery modes: downloaded or sent by email, scheduled daily or weekly, generated automatically through the API, and fed to the AI Assistant."><figcaption><p>Choose a report type, a database and a time window, then download, email, or schedule the PDF.</p></figcaption></figure>

Reports are generated from the web interface, from the [Reporting API](/manual/implementation/platform-usage/api-reference/reporting.md), or on request from an AI assistant through [AI Connector](https://docs.datasentinel.io/ai-connector/generate-reports). Whatever the entry point, the PDF is built server-side by the platform, with the rights of the user who asks for it.

{% hint style="info" %}
Tag filters apply to reports as they do to dashboards: a single report can cover several instances, an application, or a whole environment. See [Tags](/manual/features/tips-and-hints/tags.md).
{% endhint %}

## Report types

| Report              | What it contains                                                                                                                                                                                                                                                                                                                               |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Full report**     | The complete picture in one document, titled **Workload report** in the PDF. It chains the sections below: workload sessions, top queries, tables and indexes, instance activity, blocking scenarios, server activity, and data size. A **Developer** profile gets the same report without the instance activity and server activity sections. |
| **Session history** | The [Session History](/manual/features/key-features/session-history.md) dashboard on paper: average active sessions over time by wait event type and wait event, by an optional dimension of your choice (application, user, database, or any tag), then the top sampled queries and the top sampled users and databases.                      |
| **Top queries**     | The [Top Queries](/manual/features/key-features/top-queries.md) ranked by the metric of your choice (total time by default): a summary of the whole query workload per instance, then one entry per query with its statistics and its proportional bar chart.                                                                                  |
| **Query**           | A deep dive on a single query: its full text, its statistics by cluster, database and user, its session history, its global, cache, I/O, temporary I/O and WAL activity over time, and its captured [execution plans](/manual/features/other-features/execution-plans.md).                                                                     |
| **Top tables**      | The [Top Tables](/manual/features/key-features/top-tables.md) and top indexes ranked by the criterion of your choice (block reads or hits, DML operations, scans, size), with the per-table characteristics described below.                                                                                                                   |
| **Instance**        | The [cluster metrics](/manual/features/key-features/cluster-and-system-metrics.md): per-database I/O, tuples and transactions, background writer and checkpoint activity, the [changed parameters](/manual/features/other-features/changed-parameters.md) over the time window, and the full list of collected parameter values.               |
| **Server**          | The [system metrics](/manual/features/key-features/cluster-and-system-metrics.md) of the monitored hosts: CPU, memory, swap, disk and network activity over time, with a summary per server and its file systems.                                                                                                                              |
| **Data size**       | The size of each database over the time window, then the fifty largest tables and the fifty largest indexes.                                                                                                                                                                                                                                   |

### What every report starts with

The first pages are the same for all report types: the time window and its duration, the filters in effect, the list of PostgreSQL instances covered, the selected database when one was chosen, and a table of contents. Every section is numbered, so a finding is easy to cite.

### Inside the Full report

The Full report brings together the detail that used to be spread across several report types.

* **Workload sessions**: average active sessions over time by wait event type and by wait event, then the top sampled queries. Each query comes with its **load profile** (average, minimum, maximum and the 75th, 90th, 95th and 99th percentiles of active sessions executing it) and the distribution of its **top wait events**, so you see at a glance whether a query waits on CPU, I/O or locks.
* **Top queries**: a summary of the query workload per instance, then the top queries by total time with their statistics and charts.
* **Tables and indexes**: the top tables by block hits and by block reads, the top indexes by the same criteria, and a **table characteristics** page per table: column count, tuple size, extra size, **bloat size**, **XID age** and frozen XID, fill factor, table options, **column statistics** and **extended statistics**.
* **Instance activity**: per-database I/O and transactions over time, background writer and checkpoint activity, the changed parameters and the collected parameters.
* **Blocking scenarios**: every [blocking scenario](/manual/features/key-features/lock-explorer.md) detected in the time window, with the blocker session, the locks it held, the blocked sessions and their pending locks. The first twenty scenarios are detailed.
* **Server activity**: CPU, memory, swap, disk and network over time, with a summary per server and its file systems.
* **Data size**: database sizes, then the largest tables and indexes.

{% hint style="info" %}
The bloat size, the XID age and the column and extended statistics come from the optional [internal function](/manual/getting-started/postgresql-clusters/internal-function.md). Without it, those cells show as not available and the rest of the report is unchanged.
{% endhint %}

## Create a report

Reports start from the dashboards, so the filters, the selected dimension and the time window you are looking at carry over into the report.

{% stepper %}
{% step %}

### Open the reporting dialog

Click the **Reporting** icon in the toolbar of most dashboards.

<div align="left"><figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2FvFfTtUx2BCCVSgarG6La%2Freporting_toolbar.png?alt=media&amp;token=2412af4d-8423-47a9-90b2-63050028828c" alt="The dashboard toolbar with the Reporting icon highlighted"><figcaption><p>The Reporting icon in the dashboard toolbar</p></figcaption></figure></div>
{% endstep %}

{% step %}

### Choose the report type and the scope

Pick the report type. Some dashboards pin it: from the Session History dashboard, only the Session history report is offered. Then restrict the report to one database, or keep the default, **All databases**.

<figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2Fh1iuezEgc9FAjq7F3a5Y%2Freporting-download.png?alt=media&amp;token=3339d801-b932-4b66-9b5d-281168674fce" alt="The Create Report form: report type, database, and the three actions Download report, One time email, and Scheduled email"><figcaption><p>Report creation</p></figcaption></figure>
{% endstep %}

{% step %}

### Choose the action and save

Select **Download report**, **One time email** or **Scheduled email**, described below, then click **Save**. The platform builds the PDF from the time window and filters in effect, and the report then follows the delivery mode you chose.
{% endstep %}
{% endstepper %}

## Delivery modes

{% tabs %}
{% tab title="Download report" %}
The report is generated right away and downloaded to your computer.
{% endtab %}

{% tab title="One time email" %}
The report is generated right away and sent to the recipients you list. You can edit the email subject and address several recipients.

<figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2FoHbV2eOJmtuSk2uIyvx3%2Freporting-email.png?alt=media&amp;token=bc59c457-97cd-4a7f-80bf-a9af3fb30abb" alt="The email options of a report: subject and recipients"><figcaption><p>Email options</p></figcaption></figure>

{% hint style="warning" %}
Email delivery requires an [SMTP server](/manual/implementation/platform-usage/configuration/smtp.md) configured on the platform.
{% endhint %}
{% endtab %}

{% tab title="Scheduled email" %}
The report is generated at regular intervals and sent by email each time.

* **Frequency**: daily or weekly.
* **Day and hour**: when the report runs. For a weekly report, the day you pick becomes the day of the week.
* **Range**: the activity window covered by each run, from the last hour to the last 7 days, ending at the execution time.

<figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2FHQPSb2thNXeOFsHbU1Vw%2Freporting-scheduled.png?alt=media&amp;token=1c21758b-d382-418a-bfb8-6d1c6c42fa97" alt="The scheduler options of a report: frequency, day, hour and time range"><figcaption><p>Scheduler options</p></figcaption></figure>

{% hint style="info" %}
A scheduled report always runs 3 minutes after the chosen time, so that the latest metrics are collected before the report is built.
{% endhint %}
{% endtab %}
{% endtabs %}

## Manage scheduled reports

The **Scheduled reports** tab of the reporting section lists the scheduled reports with their type, owner, frequency, next run, recipients, time range and filters. From there you can edit the properties of a report, delete it, or expand it to see its execution history.

<figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2Fcl0YM6LM5AJXDNzVDogv%2Fscheduled-reports.png?alt=media&amp;token=b3b9acd2-9d8d-4c45-9d09-f111268a663a" alt="The Scheduled reports tab listing four daily reports with their type, owner, frequency, next run, recipients, time range and filters"><figcaption><p>Scheduled reports</p></figcaption></figure>

{% hint style="info" %}
An administrator sees and manages every scheduled report. Any other [role](/manual/implementation/platform-usage/configuration/users-and-roles.md) manages only the reports it created.
{% endhint %}

## Execution history

The **Execution history** tab keeps a log of every scheduled run: the report, the day, the start and end times, the duration and the status. Filter it by name or by report type to find a failed run quickly.

<figure><img src="https://1072624949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlcWi6G1jtNuyGT9C0pkc%2Fuploads%2Fnc2RtbBvPCHDsDFxDmrM%2Fexecution-history.png?alt=media&amp;token=154b947e-39a5-4a8d-940f-0ba7325dd4fa" alt="The Execution history tab listing four report runs with their day, start, end, duration and status"><figcaption><p>Execution history</p></figcaption></figure>

## Generate reports without the web interface

{% content-ref url="/pages/Ax2GR2jf0dLwU2cYguRk" %}
[Reporting](/manual/implementation/platform-usage/api-reference/reporting.md)
{% endcontent-ref %}

Every report type has its own route in the Reporting API, with the same download, email and scheduled modes. A scheduled report created through the API shows up in the **Scheduled reports** tab like any other.

An AI assistant connected through [AI Connector](https://docs.datasentinel.io/ai-connector) can also ask the platform for the Full, Session history, Top queries and Query reports and hand you back a download link. See [Generate and share reports](https://docs.datasentinel.io/ai-connector/generate-reports).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.datasentinel.io/manual/features/key-features/reporting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
