Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-05-24 09:28:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 30
fleet/articles/queries.md
Steven Palmesano 2f95183c08
Update server_settings documentation (#43839) 
We
[updated](02af994bb2)
some references when we renamed queries to reports, but didn't update
them all.
2026-04-22 17:53:34 -05:00

6.9 KiB
Raw Blame History

Reports

Reports in Fleet allow you to ask questions to help you manage, monitor, and identify threats on your devices. This guide will walk you through how to create, schedule, and run a report.

Unless a log destination is configured, osquery logs will be stored locally on each device.

New users may find it helpful to start with Fleet's policies. You can find policies and queries from the community in Fleet's library. To learn more about policies, see What are Fleet policies? and Understanding the intricacies of Fleet policies.

In this guide:

Create a report

How to create a report:

  1. In the top navigation, select Reports and Add report.

  2. In the Query field, enter your query. Remember, you can find common reports in Fleet's library.

Avoid using dot notation (".") for column names in your queries as it can cause results to render incorrectly in Fleet UI. Please see issue #15446 for more details.

  1. Select Save, enter a name and description for your report, select the interval that the report should run at, and select Save.

Targeting hosts using labels

Available in Fleet Premium.

When creating or editing a report, you can restrict the set of hosts that it will run on by using labels. By default, a new report will target all hosts, indicated by the All Hosts option being selected beneath the Targets setting. If you select Custom instead, you will be able to select one or more labels for the report to target. Note that the report will run on any host that matches any of the selected labels. To learn more about labels, see Managing labels in Fleet.

View a report

How to view a report:

  1. In the top navigation, select Reports.

  2. In the Reports table, find the report you'd like to run and select the reports's name.

  3. If you want to download the report, select Export results to save it as a CSV.

Fleet stores up to 1,000 results per report. If the count stays below this limit, Fleet updates the report each time hosts send new data.

If the results exceed 1,000, Fleet stops updating the report. To start collecting data again, clear the stored results from the report's page. Go to Advanced options, check Discard data, and select Save. Then uncheck Discard data and select Save again.

You can change the 1,000-result limit by setting server_settings.report_cap.

Persisting results within Fleet creates load on the database, so you'll want to monitor database load as you add queries. If needed, you can disable stored results either globally or per-report.

  • Globally via the UI: Settings > Advanced options > Disable stored results
  • Globally via the API: set server_settings.discard_reports_data
  • Per-report via the UI: Edit report > Show advanced options > Discard data
  • Per-report via the API: Set the discard_data field when creating or modifying the report

Run a report

Run a live report to get answers for all of your online hosts.

Offline hosts won’t respond to a live report because they may be shut down, asleep, or not connected to the internet.

How to run a report:

  1. In the top navigation, select Reports.

  2. In the Reports table, find the report you'd like to run and select the reports's name.

  3. Select Live report to navigate to the target picker. Select All hosts and select Run. This will run the report against all your hosts.

  4. If you want to download the results, select Export results to save it as a CSV.

The report may take several seconds to complete because Fleet has to wait for the hosts to respond with results.

Response time is inherently variable because of osquery's heartbeat response time. This helps prevent performance issues on hosts.

Schedule a report

Fleet allows you to schedule queries to run at a set interval. By default, queries that run on a schedule will only target platforms compatible with that report. This behavior can be overridden by setting the platforms in Advanced options when saving a report.

To create a scheduled report, set the interval to a value other than "Never" when creating a report. If the report has already been created, select the report and then select Edit report to set the interval.

Scheduled reports will send data to Fleet and/or your log destination automatically. Automations can be turned off in Advanced options or using the bulk Manage automations UI.

How to configure automations in bulk:

Only users with the admin role can manage report automations.

  1. In the top navigation, select Reports.

  2. Select Manage automations.

  3. Check the box next to the queries you want to send data to your log destination, and select Save. (The interval that queries run at is set when a report is created.)

Note: When viewing a specific fleet in Fleet Premium, only queries that belong to the selected fleet will be listed. When configuring automations for all hosts, only global reports will be listed.

Further reading