kibana_aggregate_logs
Group logs by field (e.g., level, service) and compute counts or metrics like avg, sum. Efficient aggregation without returning raw logs.
Instructions
Aggregate logs using a terms grouping and optional metric.
Wraps POST {ES_URL}/{index}/_search with size:0 (no hits returned)
and a terms aggregation on group_by. This is the efficient way to
get counts, averages, or sums grouped by a field value.
When more than 20 buckets are rendered in the text output, a truncation
hint is appended — use the structured buckets field for the full list.
Examples:
- Use when: "How many logs per log level in the last hour?"
→ index='logs-*', group_by='level',
time_from='2026-04-18T09:00:00Z'.
- Use when: "What is the average response time per service?"
→ group_by='service.keyword', metric='avg',
metric_field='response_time_ms'.
- Use when: "Top 10 HTTP status codes today."
→ group_by='http.response.status_code', size=10.
- Don't use when: You need raw log content/messages — use
kibana_search_logs which returns full _source objects.
- Don't use when: You need time-series (histogram per interval) —
that requires a date_histogram aggregation not supported here.
Returns:
dict with total_documents / took_ms / buckets (list).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Elasticsearch index name or pattern (e.g. 'logs-*'). | |
| group_by | Yes | Field name for terms aggregation (e.g. 'level', 'service.keyword', 'http.response.status_code'). For text fields use the '.keyword' sub-field. | |
| query | No | Elasticsearch Query String Syntax filter applied before aggregation. Use '*' (default) to aggregate all documents, or narrow with e.g. 'service:api'. | * |
| metric | No | Aggregation metric: 'count' (default, doc_count per bucket), 'avg', 'sum', 'min', 'max' (require metric_field). | count |
| metric_field | No | Field to apply the metric on. Required when metric is 'avg', 'sum', 'min', or 'max'. Example: 'response_time_ms' for avg latency per service. | |
| time_field | No | Name of the timestamp field. | @timestamp |
| time_from | No | Start of time range. ISO-8601 or epoch-ms. | |
| time_to | No | End of time range. ISO-8601 or epoch-ms. | |
| size | No | Number of terms buckets to return (1-100, default 10). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| total_documents | Yes | ||
| took_ms | Yes | ||
| index | Yes | ||
| group_by | Yes | ||
| metric | Yes | ||
| metric_field | Yes | ||
| buckets_count | Yes | ||
| buckets | Yes |