Skip to content

Query Types

The LogZilla Query API provides multiple query types for data analysis and retrieval, including TopN, Search, EventRate, and system queries. Each query type offers specific functionality with customizable parameters and response formats for different analytical needs.

Prerequisites

  • Valid LogZilla API authentication token (see Getting Started)
  • Understanding of query creation workflow (see Making Queries)
  • JSON data format familiarity
  • Time range and filtering concepts

TopN

Get top N values for requested field and time period, possibly with filtering. Detailed counts for subperiods of the given period can additionally be requested.

Configurable parameter description
time_range data is taken for this time range
field which field to aggregate by (defaults to "host")
with_subperiods boolean. if set then results for the whole time range and all subperiods are returned
top_periods boolean. if set then the top N subperiods are returned
filter extra filters. see Query API Parameters for details
limit number of values to show
show_other boolean. enables one extra value called "other", with the sum of all remaining values from N+1 to the end of the list
ignore_empty boolean. enables ignoring empty event field/tag values (defaults to True)
subfields extra subfields to get detailed results
subfields_limit the number of subfield values to show

TopN Data Format

"totals" with values for the whole time period are provided first:

{
  "totals": {
      "ts_from": 123450000,
      "ts_to": 123453600,
      "values": [
          {"name": "host32", "count": 3245},
          {"name": "host15", "count": 2311},
          {"name": "localhost", "count": 1255}
      ]
  }
}

Elements are sorted from highest to lowest count, but if "show_other" is requested then the last value is always "other" regardless of the count (which can be larger than any previous count). Number of elements in "values" can be less than "limit" parameter if not enough different values for the given field were found for the given time period.

LastN

Get last N values for the given field and given time period, with number of occurrences per given time range.

Configurable parameter description
time_range data is taken for this time range
field which field to aggregate by (defaults to "host")
filter extra filters. see Query API Parameters for details
limit number of values to show
ignore_empty boolean. enables ignoring empty event field/tag values (defaults to True)

LastN Data Format

Similar to "TopN" but there is also a "last_seen" field, with possibly fractional part of the second. Also, elements are sorted by "last_seen" instead of "count". Both elements shown and counts are for the given time_range and filters.

EventRate

Get number of events per given time periods - i.e. per second for last minute, or events per day for last month, and so on. Filters can be used to retrieve the rate for a particular host, program, severity or any combination. It is also used on the search results page to show a histogram for the search results.

Configurable parameter description
time_range data is taken for this time range
filter extra filters. see Query API Parameters for details

EventRate Data Format

{
  "totals": {
    "ts_from": 1416231300,
    "ts_to": 1416234900,
    "count": 123456
  },
  "details": [
    {
      "ts_from": 1416231300,
      "ts_to": 1416231360,
      "count": 1234
    },
    {
      "ts_from": 1416231360,
      "ts_to": 1416231420,
      "count": 2345
    }
  ]
}

The only query type that includes not only counts but also the list of events with details.

Configurable parameter description
time_range data is taken for this time range
filter extra filters. see Query API Parameters for details
sort array of field names to sort by. prefix with "-" for descending order
page page number for pagination (starts from 1)
page_size number of events per page
offset alternative to page - direct offset into results

Search Data Format

{
  "totals": {
    "ts_from": 1416231300,
    "ts_to": 1416234900,
    "count": 123456
  },
  "events": {
    "objects": [
      {
        "id": "event-id-123",
        "first_occurrence": 1416231350.123456,
        "last_occurrence": 1416231355.789012,
        "counter": 5,
        "message": "Sample log message",
        "host": "server01",
        "program": "apache",
        "severity": 6,
        "facility": 16
      }
    ],
    "page_number": 1,
    "page_size": 100,
    "item_count": 123456,
    "page_count": 1235
  }
}

System_CPU

System CPU usage query for monitoring system performance.

Configurable parameter description
time_range data is taken for this time range; only ts_from and ts_to are considered, step is always provided by the back-end depending on data available for the given period
cpu number of CPU (from 0 to n-1, with n being the actual number of CPU cores in the system), or 'totals' to get the sum for all CPUs

System_CPU Data Format

Returns CPU usage statistics including user, system, idle, wait, etc.

{
  "totals": {
    "user": {
      "count": 236,
      "sum": 1681.6008720000007,
      "min": 5.2671220000000005,
      "max": 9.599976,
      "avg": 7.125427423728817,
      "last": 6.400112999999999,
      "last_ts": 1416234840
    },
    "system": {
      "count": 236,
      "sum": 841.6008720000007,
      "avg": 3.565427423728817
    }
  },
  "details": [
    {
      "ts_from": 1416231300,
      "ts_to": 1416231315,
      "softirq": 0,
      "system": 8.400342,
      "idle": 374.946619,
      "user": 16.067144,
      "interrupt": 0.20001199999999997,
      "nice": 0,
      "steal": 0,
      "wait": 0.20001199999999997
    }
  ]
}

Note: The CPU plugin does not collect percentages. It collects jiffies, the units of scheduling. On many Linux systems, there are circa 100 jiffies in one second, but this does not mean a percentage will be returned. The number of jiffies per second will vary depending on system load, hardware, whether or not the system is virtualized, and possibly half a dozen other factors.

System_Memory

System memory usage query for monitoring memory consumption.

Configurable parameter description
time_range data are taken for this time range; only ts_from and ts_to are considered, step is always provided by the back-end, depending on data available for the given period

Available Memory Fields

  • available - available memory
  • buffered - buffered memory
  • cached - cached memory
  • free - free memory
  • total - total memory
  • used - used memory

System_DF

Disk usage query for monitoring filesystem space.

Configurable parameter description
time_range data is taken for this time range; only ts_from and ts_to are considered, step is always provided by the back-end depending on data available for the given period
path filesystem path to monitor

Available Disk Fields

  • free - free disk space
  • total - total disk space
  • used - used disk space
  • used_percent - percentage of disk space used

System_Disk

Disk I/O statistics query for monitoring disk performance.

Configurable parameter description
time_range data is taken for this time range
device disk device name (e.g., "sda", "sdb")

Available Disk I/O Fields

  • reads - number of read operations
  • writes - number of write operations
  • read_bytes - bytes read
  • write_bytes - bytes written
  • read_time - time spent reading
  • write_time - time spent writing

System_Net

Network interface statistics query for monitoring network performance.

Configurable parameter description
time_range data is taken for this time range
interface network interface name (e.g., "eth0", "lo")

Available Network Fields

  • bytes_recv - bytes received
  • bytes_sent - bytes sent
  • packets_recv - packets received
  • packets_sent - packets sent
  • err_in - input errors
  • err_out - output errors
  • drop_in - input drops
  • drop_out - output drops

ProcessingStats

Indicates the number of events processed by the system in the given time period. Similar to EventRates but does not allow for any filtering, or timestamps of the events (only the moment it was actually processed by the system). To use this query internal counters verbosity must be set to DEBUG (run LogZilla config INTERNAL_COUNTERS_MAX_LEVEL DEBUG).

Configurable parameter description
time_range data is taken for this time range. Max time_range is last 24h

System_Memory Data Format

Includes "totals" and "details". With both there is an object with time range and three keys:

label description
new number of new items processed (not duplicates)
duplicates number of items that were found to be duplicates
oot item ignored, because their timestamp was outside the TIME_TOLERANCE compared to the current time (this should be zero at normal circumstances) 
{
  "totals": {
    "duplicates": 20,
    "oot": 5,
    "new": 75,
    "total": 100,
    "ts_to": 1441090061,
    "ts_from": 1441090001
  },
  "details": [
    {
      "duplicates": 10,
      "new": 5,
      "oot": 15,
      "ts_from": 1441090001,
      "ts_to": 1441090002
    }
  ]
}

StorageStats

Returns events counters stored by the system for the given time period. Similar to EventRates but this does not allow for any filtering and returns only total counters without subperiod details.

Time Range is rounded up to full hours -- if a 1-second time period is requested the response will be with hourly counters.

Configurable parameter description
time_range data is taken for this time range. Max time_range is last 24h

System_Disk Data Format

Includes "totals" and "all_time" counters stored in the system:

label description
totals counters from given period
all_time all time counters

For both there are three keys:

key description
new number of new items processed (not duplicates)
duplicates number of items that were found to be duplicates
total total sum 
{
  "totals": {
    "duplicates": 25,
    "new": 75,
    "total": 100,
    "ts_to": 1441090061,
    "ts_from": 1441090001
  },
  "all_time": {
    "duplicates": 20000,
    "new": 18000,
    "total": 20000
  }
}

Tasks

List of tasks.

Configurable parameter description
target filter list by "assigned to", which is either "assigned_to_me" and "all"
is_overdue filter list by is_overdue flag (boolean)
is_open filter list by is_open flag (boolean)
assigned_to filter list by assigned user id list. for the empty list, it will return only unassigned
sort list of fields to sort results by. available fields are created_at and updated_at. descending sort order can be specified by prefixing the field name with "-" (minus) sign

Tasks Data Format

[
  {
    "id": 1,
    "title": "Task name",
    "description": "Description",
    "due": 1446508799,
    "status": "new",
    "is_overdue": false,
    "is_closed": false,
    "is_open": true,
    "assigned_to": 1,
    "updated_at": 1446371434,
    "created_at": 1446371434,
    "owner": {
      "id": 1,
      "username": "admin",
      "fullname": "Admin User"
    }
  }
]

Notification

List of notifications groups, with associated events.

Configurable parameter description
sort order of notifications groups, which is "Oldest first", "Newest first", "Oldest unread first" or "Newest unread first"
time_range data is taken for this time range
time_range_field specify field for the time range processing, which is "updated_at", "created_at", "unread_since" or "read_at"
is_private filter list by is_private flag (boolean)
read filter list by read_flag flag (boolean)
with_events add to data events information (boolean)

Notifications Data Format

[
  {
    "id": 1,
    "name": "test",
    "trigger_id": 1,
    "is_private": false,
    "read_flag": false,
    "all_count": 765481,
    "unread_count": 765481,
    "hits_count": 911282,
    "read_at": null,
    "updated_at": 1446287520,
    "created_at": 1446287520,
    "owner": {
      "id": 1,
      "username": "admin",
      "fullname": "Admin User"
    },
    "trigger": {
      "id": 1,
      "snapshot_id": 1,
      "name": "test",
      "is_private": false,
      "send_email": false,
      "exec_script": false,
      "snmp_trap": false,
      "mark_known": false,
      "mark_actionable": false,
      "issue_notification": true,
      "add_note": false,
      "send_email_template": "",
      "script_path": "",
      "note_text": "",
      "filter": [
        {
          "field": "message",
          "value": "NetScreen"
        }
      ],
      "is_active": false,
      "active_since": 1446287518,
      "active_until": 1446317276,
      "updated_at": 1446317276,
      "created_at": 1446287518,
      "owner": {
        "id": 1,
        "username": "admin",
        "fullname": "Admin User"
      },
      "hits_count": 911282,
      "last_matched": 1446317275,
      "notifications_count": 911282,
      "unread_count": 911282,
      "last_issued": 1446317275,
      "order": null
    }
  }
]