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)
end	Epoch timestamp marking the end of the query range (in milliseconds)
requestType	Type of response expected (e.g., time_series, scalar, raw)
compositeQuery	This contains the compositeQuery which is explained below
variables	Variables for templated queries (optional)

Composite Query

The compositeQuery field consists of:

NAME	DESCRIPTION
queries	Array of query envelopes

Query Envelope

Each query in the queries array consists of:

NAME	DESCRIPTION
type	Type of query (e.g., builder_query, builder_formula, clickhouse_sql, promql). Scope of this documentation is limited to builder_query type
spec	Query specification based on type - contains the builderQuery for builder_query type

Builder Query

A builderQuery spec consists of:

NAME	DESCRIPTION
name	Name of the query (e.g., A, B, C)
signal	Source of data (e.g., logs, traces, metrics)
stepInterval	Aggregation interval for query in seconds
aggregations	Array of aggregation expressions
filter	filter expression for filtering data
groupBy	Array of groupByKey used for groupBy
order	Array of orderBy for sorting
limit	Maximum number of results to return
offset	Offset used in pagination
disabled	Specifies if the query is disabled

Aggregation

An aggregation consists of:

NAME	DESCRIPTION
expression	Aggregation expression - count(), count_distinct(field), sum(field), avg(field), min(field), max(field), p50(field), p75(field), p90(field), p95(field), p99(field)
alias	Optional alias for the aggregation result

Filter

A filter consists of:

NAME	DESCRIPTION
expression	Filter expression string using operators like `=, !=, >, >=, <, <=, IN, NOT IN, CONTAINS, NOT CONTAINS, REGEXP, NOT REGEXP, EXISTS, NOT EXISTS`

GroupBy Key

The groupByKey includes:

NAME	DESCRIPTION
name	Name of the field
fieldDataType	Data type of the field (e.g., string, int64, float64, bool)
fieldContext	Type of the field, i.e., attribute/resource

OrderBy

The orderBy includes:

NAME	DESCRIPTION
key	Object containing the field name to order by
direction	Sort direction (asc, desc)

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,
    "requestType": "scalar",
    "variables": {},
    "compositeQuery": {
        "queries": [
            {
                "type": "builder_query",
                "spec": {
                    "name": "A",
                    "signal": "logs",
                    "stepInterval": 60,
                    "aggregations": [
                        {
                            "expression": "count_distinct(component)",
                            "alias": "distinct_components"
                        }
                    ],
                    "groupBy": [
                        {
                            "name": "container_id",
                        }
                    ],
                    "order": [
                        {
                            "key": {
                                "name": "distinct_components"
                            },
                            "direction": "desc"
                        }
                    ],
                    "disabled": false
                }
            }
        ]
    }
}