Logs API Payload Model
The SigNoz Logs API uses a JSON payload for queries, which includes various fields and nested fields. This document provides a detailed explanation of each field to help users construct effective queries.
Top-level
The top-level of the payload model has the following fields:
| NAME | DESCRIPTION |
|---|---|
| start | Epoch timestamp marking the start of the query range (in milliseconds or nanoseconds) |
| end | Epoch timestamp marking the end of the query range (in milliseconds or nanoseconds) |
| step | Aggregation interval for the query, specified in seconds |
| compositeQuery | This contains the compositeQuery which is explained below |
Composite Query
The compositeQuery field consists of:
| NAME | DESCRIPTION |
|---|---|
| queryType | Type of query (e.g., builder, clickhouse, prometheus).Scope of this documentation is limited to builder type |
| panelType | Type of panel (e.g., list, graph, table) |
| offset | Offset used in pagination |
| pageSize | Number of items to fetch, used in list view |
| limit | For list view: - Maximum number of items to be paginate, i.e., offset + pageSize cannot exceed limit, For aggregation:- limit on the results |
| builderQueries | Map of builderQuery |
Builder Query
A builderQuery consists of:
| NAME | DESCRIPTION |
|---|---|
| stepInterval | Aggregation interval for query in seconds |
| queryName | Name of the query, should match the key to this map value |
| dataSource | Source of data, e.g., logs |
| aggregateOperator | Type of aggregation - noop, count, count_distinct, sum, avg, min, max, p05, p10, p20, p25, p50, p75, p90, p95, p99, rate, sum_rate, avg_rate, min_rate, max_rate, rate_sum, rate_avg, rate_min, rate_max |
| aggregateAttribute | The attribute against which the aggregateOperator is applied |
| filters | Array of filter used for filtering data |
| groupBy | Array of attribute used for groupBy |
| expression | Will be same as query name but different in case of formulas |
| disabled | Specifies if the query is disabled |
Filter
A filter consists of:
| NAME | DESCRIPTION |
|---|---|
| items | Array of filterItem |
| op | Operator defining how filter items are joined (e.g., AND). |
Filter Item
The filterItem includes:
| NAME | DESCRIPTION |
|---|---|
| key | Corresponding attribute |
| op | Operators - =, !=, >, >=, <, <=, in, nin, contains, ncontains, regex, nregex, like, nlike, exists, nexists, has, nhas |
| value | Value for the filter, can be empty for some op |
📝 Note
The value parameter will be empty for exists and nexists.
Attribute
An attribute consists of:
| NAME | DESCRIPTION |
|---|---|
| key | Name of the key |
| type | Type of the key, i.e., tag/resource. It is empty for top level fields. (e.g., tag = method, resource = k8s_deployment_name, (empty) = trace_id) |
| dataType | Data type of the key (e.g., string, int64, float64, bool) |
| isColumn | Indicates if it has a materialized column, i.e., selected field |
| isJson | Specifies if the key is a JSON key |
Sample Payload
This sample payload contains the different fields that we looked at above. It queries the SigNoz Logs API and illustrates how to count distinct component values and group them by container_id.
{
"start": 1700734490000,
"end": 1700738090000,
"step": 60,
"variables": {},
"compositeQuery": {
"queryType": "builder",
"panelType": "table",
"builderQueries": {
"A": {
"dataSource": "logs",
"queryName": "A",
"aggregateOperator": "count_distinct",
"aggregateAttribute": {
"key": "component",
"dataType": "string",
"type": "tag",
"isColumn": false
},
"filters": {
"items": [],
"op": "AND"
},
"expression": "A",
"disabled": false,
"stepInterval": 60,
"orderBy": [
{
"columnName": "timestamp",
"order": "desc"
}
],
"groupBy": [
{
"key": "container_id",
"dataType": "string",
"type": "tag",
"isColumn": true,
"isJSON": false
}
],
"offset": 0
}
}
}
}
