Trace API Payload Model

The SigNoz Trace 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)
step	Aggregation interval for the query, specified in seconds
variables	Map of variables used in the query
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, trace, value)
builderQueries	Map of builderQuery
chQueries	Map of chQuery

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., traces
aggregateOperator	Type of aggregation - noop, count, count_distinct, sum, avg, min, max, p05, p10, p20, p25, p50, p75, p90, p95, p99, 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
selectColumns	Array of attribute which is used in list panelType to fetch columns/attributes of list
groupBy	Array of attribute used for groupBy
orderBy	Array of orderBy used for ordering data
having	Array of having used for filtering data after aggregation
expression	Will be same as query name but different in case of formulas
disabled	Specifies if the query is disabled
limit	Limit number of results
offset	Offset used in pagination
pageSize	Number of results per page

Ch Query

A chQuery consists of:

NAME	DESCRIPTION
query	Clickhouse query

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
value	Value for the filter, can be empty for some op like `exists` and `nexists`

📝 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's column, i.e., it would be faster to query using this attribute

Order By

An orderBy consists of:

NAME	DESCRIPTION
columnName	Name of the attribute/key
order	Order of the column (e.g., asc, desc)

Having

A having consists of:

NAME	DESCRIPTION
columnName	Name of the attribute/key along with aggregate operator (e.g., COUNT(httpMethod))
op	Operators - =, !=, >, >=, <, <=
value	Value for the filter

Sample Payload

For builderQuery with table panelType

This sample payload contains the different fields that we looked at above. It queries the SigNoz Trace API and illustrates how to count distinct hasError values and group them by serviceName where hasError is true.

{
    "start": 1702007766000,
    "end": 1702009566000,
    "step": 60,
    "variables": {},
    "compositeQuery": {
        "queryType": "builder",
        "panelType": "table",
        "builderQueries": {
            "A": {
                "dataSource": "traces",
                "queryName": "A",
                "aggregateOperator": "count",
                "aggregateAttribute": {
                    "key": "hasError",
                    "dataType": "bool",
                    "type": "tag",
                    "isColumn": true
                },
                "filters": {
                    "items": [
                        {
                            "key": {
                                "key": "hasError",
                                "dataType": "bool",
                                "type": "tag",
                                "isColumn": true
                            },
                            "op": "=",
                            "value": "true"
                        }
                    ],
                    "op": "AND"
                },
                "expression": "A",
                "disabled": false,
                "having": [],
                "stepInterval": 60,
                "limit": null,
                "orderBy": [
                    {
                        "columnName": "timestamp",
                        "order": "desc"
                    }
                ],
                "groupBy": [
                    {
                        "key": "serviceName",
                        "dataType": "string",
                        "type": "tag",
                        "isColumn": true
                    }
                ],
                "legend": "",
                "reduceTo": "sum"
            }
        }
    },
    "dataSource": "traces"
}

For chQuery

{
    "start": 1723644761000,
    "end": 1723646561000,
    "compositeQuery": {
        "queryType": "clickhouse_sql",
        "panelType": "table",
        "chQueries": {
            "A": {
                "query": "SELECT stringTagMap['service.name'] AS `service.name`, toFloat64(avg(durationNano)) AS value FROM signoz_traces.distributed_signoz_index_v2 WHERE timestamp BETWEEN {{.start_datetime}} AND {{.end_datetime}} GROUP BY (`service.name`) order by (`service.name`) ASC;"
            }
        }
    }
}