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)
requestType	Type of response expected (e.g., time_series, scalar, raw, trace)
compositeQuery	This contains the compositeQuery which is explained below
variables	Map of variables used in the query (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, clickhouse_sql, promql). Scope of this documentation is limited to builder_query and clickhouse_sql types
spec	Query specification based on type - contains the builderQuery for builder_query type or chQuery for clickhouse_sql 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., traces)
stepInterval	Aggregation interval for query in seconds
aggregations	Array of aggregation expressions
filter	filter expression for filtering data
selectFields	Array of selectField which is used in raw/trace requestType to fetch columns/attributes
groupBy	Array of groupByKey used for groupBy
order	Array of orderBy used for ordering data
having	having expression used for filtering data after aggregation
disabled	Specifies if the query is disabled
limit	Limit number of results
offset	Offset used in pagination

Ch Query

A chQuery spec consists of:

NAME	DESCRIPTION
name	Name of the query (e.g., A, B, C)
query	Clickhouse query
disabled	Whether 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), rate(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`

Select Field

A selectField consists of:

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.

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

Order By

An orderBy consists of:

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

Having

A having consists of:

NAME	DESCRIPTION
expression	Having expression (e.g., "count() > 100", "avg_duration > 1000")

Sample Payload

For builderQuery with table requestType

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

{
    "start": 1702007766000,
    "end": 1702009566000,
    "requestType": "time_series",
    "variables": {},
    "compositeQuery": {
        "queries": [
            {
                "type": "builder_query",
                "spec": {
                    "name": "A",
                    "signal": "traces",
                    "stepInterval": 60,
                    "aggregations": [
                        {
                            "expression": "count()",
                            "alias": "error_count"
                        }
                    ],
                    "filter": {
                        "expression": "hasError = true"
                    },
                    "groupBy": [
                        {
                            "name": "serviceName",
                        }
                    ],
                    "order": [
                        {
                            "key": {
                                "name": "error_count"
                            },
                            "direction": "desc"
                        }
                    ],
                    "disabled": false
                }
            }
        ]
    }
}

For chQuery

{
    "start": 1723644761000,
    "end": 1723646561000,
    "requestType": "scalar",
    "compositeQuery": {
        "queries": [
            {
                "type": "clickhouse_sql",
                "spec": {
                    "name": "A",
                    "query": "SELECT resource_string_service$$name AS `service.name`, toFloat64(avg(durationNano)) AS value FROM signoz_traces.distributed_signoz_index_v3 WHERE timestamp BETWEEN $start_datetime AND $end_datetime AND ts_bucket_start BETWEEN $start_timestamp - 1800 AND $end_timestamp GROUP BY (`service.name`) order by (`service.name`) ASC;",
                    "disabled": false
                }
            }
        ]
    }
}