aggregate_logs
Aggregate matching log events into a time series and detect volume spikes. Find when log volume bursts without pulling raw events, then search the spike window.
Instructions
[READ] Aggregate matching events into a time series and detect spikes.
WHEN: to find when/whether log volume burst without pulling raw events. Follow up with search_logs on the spike window.
RETURNS: {aggregation, field, bin_width_ms, constraints, bins:[{timestamp_ms, end_ms, value}] oldest first, spikes:[{timestamp_ms, end_ms, value, zscore}]}, plus 'note' when an empty series has a likely cause. For SAMPLE each bin's value is one example event {timestamp_ms, text, fields}, and no spikes are computed. The appliance omits bins with no events; for COUNT and UCOUNT those are added back as 0 (filled_empty_bins: true) so a burst after a quiet stretch still stands out. On a sparse series (a few events in an hour) that makes most non-empty bins spikes — read them as "events happened here", not as bursts. A bin is flagged as a spike when it sits at least 2 standard deviations above the mean; a series of fewer than 3 bins, or a flat one, reports no spikes rather than calling everything a spike — so an empty 'spikes' list is not evidence of calm when the window is short. Read-only.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| last | No | Relative window ending now — "30m", "2h", "7d" (units s/m/h/d) or a bare number of seconds. Cannot be combined with begin_ms/end_ms. Omit all three and the window defaults to the last hour. | |
| text | No | Word(s) matched with CONTAINS (whole words, not substrings; `*` is a wildcard), exactly as in search_logs. Omit to aggregate every event in the window. | |
| field | No | The field the function applies to, as listed by list_log_fields ('name') — e.g. aggregation="UCOUNT", field="hostname" counts distinct hosts per bin. Required for UCOUNT/AVG/MIN/MAX/SUM/STDDEV/VARIANCE, refused for COUNT/SAMPLE. AVG/MIN/MAX/SUM/STDDEV/VARIANCE need a NUMBER field (list_log_fields 'type'). An unknown name returns an empty series with a 'note', not an error. Pass 'name' exactly as list_log_fields gives it: for a content-pack field that is the qualified "com.vmware.vsphere:vmw_esxi_auth_failed_user" — the bare display name and 'internal_name' match nothing. | |
| end_ms | No | Absolute window end as epoch milliseconds. Usable on its own; cannot be combined with last. | |
| target | No | Log Insight target name as spelled in ~/.vmware-log-insight/config.yaml. Omit to use that file's default_target — with no default configured, omitting it is an error that lists the configured names. | |
| begin_ms | No | Absolute window start as epoch milliseconds (seconds are refused). Usable on its own; must be before end_ms; cannot be combined with last. | |
| aggregation | No | The function applied within each bin — exactly one of COUNT, UCOUNT, AVG, MIN, MAX, SUM, STDDEV, VARIANCE, SAMPLE (lower case is accepted and upper-cased). Anything else raises a ValueError listing the nine. Default COUNT, which answers "how many events per bin" and is what spike detection is normally run on. COUNT and SAMPLE take no field; the other seven require one. | COUNT |
| bin_width_ms | No | Width of each time bin in milliseconds, must be positive (default 60000 = one minute). It sets the resolution of both the series and the spike test: bins much wider than the burst average it away, bins much narrower make every quiet minute look like noise. |