Consulta pontos de dados de uma ou mais séries temporais em um intervalo de tempo especificado. Envie uma requisição POST para /api/query com um corpo JSON que defina o intervalo de tempo e uma ou mais subconsultas.
Sintaxe da requisição
POST /api/query
Parâmetros da requisição
|
Parâmetro |
Tipo |
Obrigatório |
Padrão |
Descrição |
|
|
Long |
Sim |
— |
Início do intervalo de tempo. Unidade: segundos ou milissegundos. O TSDB determina a unidade com base no valor numérico. Consulte Unidades de timestamp. |
|
|
Long |
Não |
Hora atual do servidor |
Fim do intervalo de tempo. Unidade: segundos ou milissegundos. O padrão é a hora atual no servidor TSDB. Consulte Unidades de timestamp. |
|
|
Array |
Sim |
— |
Array de subconsultas. Consulte Parâmetros de subconsulta. |
|
|
Boolean |
Não |
|
Define se os timestamps devem ser retornados em milissegundos. Aplica-se apenas quando os pontos de dados consultados usam timestamps com precisão de segundos. Se |
|
|
Map |
Não |
— |
Dica de consulta para reduzir o tempo de resposta. Consulte Parâmetro: hint. |
Unidades de timestamp
O TSDB determina a unidade do timestamp a partir do valor numérico:
|
Intervalo |
Unidade |
Período de datas |
|
|
Segundos |
1970-02-20 01:02:48 – 2106-02-07 14:28:15 |
|
|
Milissegundos |
1970-02-20 01:02:47.296 – 2286-11-21 01:46:39.999 |
|
|
Inválido |
— |
Estas regras aplicam-se tanto a/api/put(escrita) quanto a/api/query(consulta).
Para consultar pontos de dados em um único momento, defina start e end com o mesmo valor — por exemplo, 1356998400.
Parâmetros de subconsulta
Cada objeto no array queries aceita os seguintes parâmetros:
|
Parâmetro |
Tipo |
Obrigatório |
Padrão |
Descrição |
|
|
String |
Sim |
— |
Função de agregação. Consulte Parâmetro: aggregator. Exemplo: |
|
|
String |
Sim |
— |
Nome da métrica. Exemplo: |
|
|
Boolean |
Não |
|
Define se deve calcular a taxa de variação entre valores consecutivos. Fórmula: |
|
|
Boolean |
Não |
|
Define se deve calcular o delta entre valores consecutivos. Fórmula: |
|
|
Integer |
Não |
|
Número máximo de pontos de dados a retornar por série temporal por página. |
|
|
Integer |
Não |
|
Quantidade de pontos de dados a pular por série temporal por página. |
|
|
String |
Não |
— |
Filtra os pontos de dados retornados por valor. Operadores suportados: |
|
|
String |
Não |
— |
Filtra pontos de dados brutos durante a varredura, antes da agregação. Usa os mesmos operadores de |
|
|
String |
Não |
— |
Configuração de downsample. Consulte Parâmetro: downsample. Exemplo: |
|
|
Map |
Não |
— |
Condições de filtro baseadas em tags. Mutuamente exclusivo com |
|
|
List |
Não |
— |
Condições de filtro no formato JSON. Mutuamente exclusivo com |
|
|
Map |
Não |
— |
Dica de consulta no nível da subconsulta. Consulte Parâmetro: hint. |
|
|
String |
Não |
— |
Previsão de pontos de dados futuros usando treinamento de IA. Consulte Parâmetro: forecasting. |
|
|
String |
Não |
— |
Detecção de anomalias em uma série temporal usando treinamento de IA. Consulte Parâmetro: abnormaldetect. |
Uma única requisição suporta no máximo 200 subconsultas.
Casotagsefilterssejam especificados simultaneamente, o parâmetro que aparecer posteriormente no JSON prevalecerá.
Exemplo de requisição
POST /api/query
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0"
},
{
"aggregator": "sum",
"metric": "sys.cpu.1"
}
]
}
Elementos da resposta
Uma requisição bem-sucedida retorna HTTP 200 com um array JSON. Cada elemento corresponde ao resultado de uma subconsulta.
|
Parâmetro |
Descrição |
|
|
Nome da métrica. |
|
|
Tags cujos valores não foram agregados. |
|
|
Tags cujos valores foram agregados. |
|
|
Pontos de dados como pares timestamp-valor. |
Exemplo de resposta
[
{
"metric": "tsd.hbase.puts",
"tags": {"appName": "hitsdb"},
"aggregateTags": ["host"],
"dps": {
"1365966001": 25595461080,
"1365966061": 25595542522,
"1365966062": 25595543979,
"1365973801": 25717417859
}
}
]
Parâmetro: limit e offset
Use limit e offset em conjunto para paginar resultados dentro de uma subconsulta.
limit: número máximo de pontos de dados a retornar por série temporal. O padrão0significa sem limite.offset: quantidade de pontos de dados a pular por série temporal. O padrão0indica que nenhum ponto de dado será ignorado.
Nem limit nem offset podem ser definidos com um número negativo.
Para recuperar pontos de dados classificados de 1001 a 1500, defina limit como 500 e offset como 1000:
{
"start": 1346046400,
"end": 1347056500,
"queries": [
{
"aggregator": "avg",
"downsample": "2s-sum",
"metric": "sys.cpu.0",
"limit": "500",
"offset": "1000",
"tags": {
"host": "localhost",
"appName": "hitsdb"
}
}
]
}
Parâmetro: dpValue
Filtra pontos de dados por valor após a agregação. Operadores suportados: >, <, =, <=, >=, !=.
Quando o valor do filtro for uma string, apenas = e != são suportados.
Exemplo
{
"start": 1346046400,
"end": 1347056500,
"queries": [
{
"aggregator": "avg",
"downsample": "2s-sum",
"metric": "sys.cpu.0",
"dpValue": ">=500",
"tags": {
"host": "localhost",
"appName": "hitsdb"
}
}
]
}
Parâmetro: delta
Quando delta é definido como true, cada valor na resposta dps representa o delta calculado entre pontos de dados consecutivos. Se o resultado original contiver n pares chave-valor, o resultado delta conterá n−1 pares — o primeiro par é descartado porque não existe valor anterior para cálculo. O operador delta também se aplica aos valores após o downsample.
deltaOptions
Configure deltaOptions na subconsulta para controlar como os deltas são calculados.
|
Parâmetro |
Tipo |
Obrigatório |
Padrão |
Descrição |
|
|
Boolean |
Não |
|
Trata os valores da métrica como contagens cumulativas monotonicamente crescentes ou decrescentes (semelhante a um contador). O servidor não valida os valores da métrica. |
|
|
Integer |
Não |
— |
Limiar para valores delta quando |
|
|
Boolean |
Não |
|
Controla o comportamento para deltas anormais quando |
Exemplo
{
"start": 1346046400,
"end": 1347056500,
"queries": [
{
"aggregator": "none",
"downsample": "5s-avg",
"delta": true,
"deltaOptions": {
"counter": true,
"counterMax": 100
},
"metric": "sys.cpu.0",
"dpValue": ">=50",
"tags": {
"host": "localhost",
"appName": "hitsdb"
}
}
]
}
Parâmetro: downsample
O downsample agrega dados em um intervalo de tempo especificado, sendo útil ao consultar dados em longos períodos. O intervalo de tempo é dividido em janelas do tamanho especificado, e cada timestamp retornado marca o início de uma janela.
Formato
<interval><units>-<aggregator>[-<fill policy>]
Quando downsample é especificado, o TSDB estende automaticamente o intervalo de consulta em um intervalo para ambos os lados. Por exemplo, um intervalo de [1346846401, 1346846499] com um intervalo de 5 minutos torna-se [1346846101, 1346846799].
Campos
interval
Valor numérico como 5 ou 60. Use 0all para agregar todos os pontos de dados do intervalo em um único valor.
units
|
Valor |
Unidade |
|
|
Segundos |
|
|
Minutos |
|
|
Horas |
|
|
Dias |
|
|
Meses |
|
|
Anos |
Por padrão, os timestamps são alinhados usando truncamento modular: Timestamp alinhado = Timestamp dos dados − (Timestamp dos dados % Intervalo de tempo) .
Para alinhar por intervalo de calendário (por exemplo, das 00:00 às 00:00 do dia seguinte), adicionecà unidade:1dc.
aggregator
|
Operador |
Descrição |
|
|
Valor médio |
|
|
Número de pontos de dados |
|
|
Primeiro valor |
|
|
Último valor |
|
|
Valor mínimo |
|
|
Valor máximo |
|
|
Valor mediano |
|
|
Soma dos valores |
|
|
Soma dos valores (interpolação zero) |
|
|
Igual a |
|
|
Igual a |
|
|
Igual a |
|
|
Igual a |
Os operadoresrfirst,rlast,rminermaxnão podem ser usados com uma política de preenchimento na mesma expressão de downsample.
Políticas de preenchimento
As políticas de preenchimento definem como o TSDB preenche valores ausentes nos resultados do downsample. Quando não há dados em uma janela de tempo, o TSDB aplica a política de preenchimento para gerar um valor.
|
Política de preenchimento |
Preenche valores ausentes com |
|
|
Sem preenchimento (padrão) |
|
|
|
|
|
|
|
|
|
|
|
Valor calculado por interpolação linear |
|
|
Valor anterior |
|
|
Valor adjacente mais próximo |
|
|
Próximo valor |
|
|
Valor fixo especificado pelo usuário |
Política de preenchimento fixo
Para preencher valores ausentes com um número fixo, use o formato:
<interval><units>-<aggregator>-fixed#<number>
O valor fixo pode ser positivo ou negativo. Exemplos: 1h-sum-fixed#6, 1h-avg-fixed#-8.
Exemplos de downsample
1m-avg, 1h-sum-zero, 1h-sum-near
downsample é opcional. Para desativar explicitamente o downsample, defina-o como null ou uma string vazia: {"downsample": null} ou {"downsample": ""}.
Parâmetro: aggregator
Após o downsample, o TSDB mescla várias linhas do tempo em uma só, agregando valores em cada timestamp alinhado. A agregação é ignorada quando apenas uma linha do tempo corresponde à consulta.
Interpolação
Ao agregar múltiplas linhas do tempo, uma linha sem valor em um determinado timestamp recebe um valor interpolado — desde que nenhuma política de preenchimento seja especificada e pelo menos outra linha tenha um valor nesse timestamp.
Por exemplo, ao mesclar duas linhas do tempo com {"downsample": "10s-avg", "aggregator": "sum"}:
A Linha do tempo 1 tem valores em
t+0,t+10,t+20,t+30.A Linha do tempo 2 tem valores em
t+0,t+20,t+30.
Antes da agregação, o TSDB interpola um valor para a Linha do tempo 2 em t+10. O método de interpolação depende do agregador:
|
Operador |
Descrição |
Método de interpolação |
|
|
Valor médio |
Interpolação linear |
|
|
Número de pontos de dados |
|
|
|
Valor mínimo |
Valor máximo interpolado |
|
|
Valor máximo |
Valor mínimo interpolado |
|
|
Valor mínimo |
Interpolação linear |
|
|
Valor máximo |
Interpolação linear |
|
|
Ignora agregação |
|
|
|
Soma dos valores |
Interpolação linear |
|
|
Soma dos valores |
|
Parâmetro: filters
O parâmetro filters aceita uma lista de objetos de filtro JSON para filtragem baseada em tags. É mutuamente exclusivo com o parâmetro tags.
Parâmetros do objeto de filtro
|
Parâmetro |
Tipo |
Obrigatório |
Padrão |
Descrição |
|
|
|
String |
Sim |
— |
Tipo de filtro. Consulte Tipos de filtro. Exemplo: |
|
|
|
String |
Sim |
— |
Chave da tag para filtrar. Exemplo: |
|
|
|
String |
Sim |
— |
Expressão de filtro. Exemplo: |
web02`. |
|
|
Boolean |
Não |
|
Define se deve executar uma operação GROUP BY nos valores de tag correspondentes. |
Também é possível usar expressões abreviadas de tags diretamente na subconsulta:
tagk = *: executa um GROUP BY em todos os valores da chave da tag.tagk = tagv1|tagv2: agrega valores detagv1e valores detagv2separadamente.
Tipos de filtro
|
Tipo de filtro |
Exemplo |
Descrição |
||
|
|
|
web02` |
Corresponde a valores exatos de tag separados por |
`. Sensível a maiúsculas e minúsculas. |
|
|
|
Corresponde a valores de tag usando um padrão curinga. Sensível a maiúsculas e minúsculas. |
Exemplo sem filtros
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0",
"rate": "true",
"tags": {
"host": "*",
"dc": "lga"
}
}
]
}
Exemplo com filtros
{
"start": 1356998400,
"end": 1356998460,
"queries": [
{
"aggregator": "sum",
"metric": "sys.cpu.0",
"rate": "true",
"filters": [
{
"type": "wildcard",
"tagk": "host",
"filter": "*",
"groupBy": true
},
{
"type": "literal_or",
"tagk": "dc",
"filter": "lga|lga1|lga2",
"groupBy": false
}
]
}
]
}
Parâmetro: hint
Uma dica de consulta reduz o tempo de resposta controlando quais índices de chave de tag o TSDB usa durante a execução da consulta. Por exemplo, se as séries temporais correspondentes ao conjunto de tags B forem um subconjunto daquelas correspondentes ao conjunto de tags A, você pode orientar o TSDB a usar apenas o índice de B — evitando a sobrecarga de leitura de A.
O parâmetro hint pode ser definido no nível superior (aplica-se a toda a consulta) ou dentro de uma subconsulta (aplica-se apenas a essa subconsulta).
A versão atual do TSDB suporta apenas o parâmetro tagk em uma dica.
Formato
No mapa tagk, defina cada chave de tag como 1 para usar seu índice, ou 0 para ignorá-lo. Todos os valores devem ser 0 ou 1 — misturar ambos na mesma dica causa um erro.
Requisito de versão: TSDB V2.6.1 e posterior.
Dica aplicada a uma subconsulta
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
},
"hint": {
"tagk": {
"dc": 1
}
}
}
]
}
Dica aplicada a toda a consulta
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 1
}
}
}
Casos de erro
Valores 0 e 1 misturados
A seguinte requisição causa um erro porque dc é 1 e host é 0:
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 1,
"host": 0
}
}
}
Resposta de erro:
{
"error": {
"code": 400,
"message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
}
Valor diferente de 0 ou 1
{
"start": 1346846400,
"end": 1346846400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"tags": {
"dc": "lga",
"host": "web01"
}
}
],
"hint": {
"tagk": {
"dc": 100
}
}
}
Resposta de erro:
{
"error": {
"code": 400,
"message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
"details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
}
}
Parâmetro: forecasting
Usa treinamento de IA em dados históricos de séries temporais para prever pontos de dados futuros. O TSDB treina com os dados existentes para identificar tendências e ciclos, projetando os valores adiante.
Formato
<AlgorithmName>-<ForecastPointCount>[-<ForecastPolicy>]
Algoritmos suportados
-
arima— AutoRegressive Integrated Moving Average (ARIMA). OForecastPolicypara ARIMA possui dois campos:delta: ordem de diferenciação. Padrão:1. Aumente para reduzir flutuações nos dados.seasonality: duração do ciclo em número de pontos de dados. Padrão:1. Defina para corresponder ao ciclo natural dos dados (por exemplo,10se os dados flutuarem a cada 10 pontos).
-
holtwinters— Suavização exponencial de Holt-Winters. OForecastPolicypara Holt-Winters possui um campo:seasonality: igual ao ARIMA. Padrão:1.
Exemplos: arima-1, arima-48-1-48, holtwinters-1-1
Exemplo
Dados existentes na série:
[
{
"metric": "sys.cpu.nice",
"tags": {"dc": "lga", "host": "web00"},
"aggregateTags": [],
"dps": {
"1346837400": 1,
"1346837401": 2,
"1346837402": 3,
"1346837403": 4,
"1346837404": 5,
"1346837405": 6,
"1346837406": 7,
"1346837407": 8,
"1346837408": 9,
"1346837409": 10,
"1346837410": 11,
"1346837411": 12
}
}
]
Consulta:
{
"start": 1346837400,
"end": 1346847400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"forecasting": "arima-1"
}
]
}
Resultado da previsão (um ponto de dado adicional é anexado):
[
{
"metric": "sys.cpu.nice",
"tags": {"dc": "lga", "host": "web00"},
"aggregateTags": [],
"dps": {
"1346837400": 1,
"1346837401": 2,
"1346837402": 3,
"1346837403": 4,
"1346837404": 5,
"1346837405": 6,
"1346837406": 7,
"1346837407": 8,
"1346837408": 9,
"1346837409": 10,
"1346837410": 11,
"1346837411": 12,
"1346837412": 13
}
}
]
Parâmetro: abnormaldetect
Utiliza o algoritmo STL (Decomposição Sazonal-Tendência usando Loess) para detectar anomalias em uma série temporal. O TSDB treina com os dados existentes para identificar padrões e sinaliza pontos de dados que se desviam significativamente do intervalo esperado.
Formato
<AlgorithmName>[-<Sigma>-<NP>-<NS>-<NT>-<NL>]
Apenas o algoritmo STL é suportado. Se você não estiver familiarizado com o ajuste de parâmetros STL, use os valores padrão omitindo os campos de parâmetros.
Parâmetros
|
Parâmetro |
Descrição |
|
|
Nome do algoritmo. Use |
|
|
Limiar de anomalia. Um ponto de dado é sinalizado como anormal se a diferença absoluta entre seu valor e a média da série exceder Sigma × desvio padrão. Valor típico: |
|
|
Número de pontos de dados por ciclo. |
|
|
Parâmetro de suavização sazonal. |
|
|
Parâmetro de suavização de tendência. |
|
|
Parâmetro de suavização do filtro passa-baixa. |
Exemplos
"abnormaldetect": "stl"
"abnormaldetect": "stl-5-5-7-0-0"
Exemplo de consulta
{
"start": 1346836400,
"end": 1346946400,
"queries": [
{
"aggregator": "none",
"metric": "sys.cpu.nice",
"abnormaldetect": "stl-5-5-7-0-0",
"filters": [
{
"type": "literal_or",
"tagk": "dc",
"filter": "lga",
"groupBy": false
},
{
"type": "literal_or",
"tagk": "host",
"filter": "web00",
"groupBy": false
}
]
}
]
}
Saída da detecção de anomalias
Cada valor em dps é um array no formato:
[srcValue, upperValue, lowerValue, predictValue, isAbnormal]
|
Campo |
Descrição |
|
|
Valor original do ponto de dado. |
|
|
Limite superior do intervalo esperado. |
|
|
Limite inferior do intervalo esperado. |
|
|
Valor previsto pelo algoritmo STL. |
|
|
|
Exemplo de saída
[
{
"metric": "sys.cpu.nice",
"tags": {"dc": "lga", "host": "web00"},
"aggregateTags": [],
"dps": {
"1346837400": [1, 1.0000000000000049, 0.9999999999999973, 1.0000000000000013, 0],
"1346837401": [2, 2.0000000000000036, 1.9999999999999958, 1.9999999999999998, 0],
"1346837402": [3, 3.0000000000000036, 2.9999999999999956, 3, 0],
"1346837403": [4, 4.0000000000000036, 3.9999999999999956, 4, 1],
"1346837404": [5, 5.0000000000000036, 4.9999999999999964, 5, 0],
"1346837405": [6, 6.000000000000002, 5.999999999999995, 5.999999999999998, 0],
"1346837406": [7, 7.0000000000000036, 6.9999999999999964, 7, 1],
"1346837407": [8, 8.000000000000004, 7.9999999999999964, 8, 0],
"1346837408": [9, 9.000000000000004, 8.999999999999996, 9, 0],
"1346837409": [10, 10.000000000000004, 9.999999999999996, 10, 0],
"1346837410": [11, 11.000000000000005, 10.999999999999998, 11.000000000000002, 0],
"1346837411": [12, 12.000000000000004, 11.999999999999996, 12, 0]
}
}
]