TimeStream API功能介紹 - Elasticsearch

Elasticsearch提供Aliyun-TimeStream時序增強外掛程式，支援通過API介面完成TimeStream索引的增刪改查，以及資料寫入和查詢。本文介紹如何使用TimeStream API。

背景資訊

TimeStream是Elasticsearch團隊自研，並結合Elastic社區時序類產品特性共建的時序引擎。Elasticsearch提供的TimeStream時序增強功能外掛程式，最佳化了Elasticsearch在儲存指標資料方面的DSL（Domain-Specific Language）查詢複雜且慢以及儲存成本過高等問題。詳細資料請參見TimeStream時序增強引擎介紹。

前提條件

已建立Elasticsearch執行個體，且執行個體版本為通用商業版7.16及以上、核心版本為1.7.0及以上，或者執行個體版本為通用商業版7.10、核心版本為1.8.0及以上。具體操作請參見建立Elasticsearch執行個體。

建立TimeStream索引

請求文法

Body為空白
```
PUT _time_stream/{name}
```

Body中傳入自訂模板內容

PUT _time_stream/{name}
{
  --- index template ---
}

使用說明

建立TimeStream索引無需傳入index_patterns，TimeStream使用{name}作為index名稱，不支援模糊比對。

請求中的Body可為空白，也可傳入自訂模板內容，Body格式請參見Elasticsearch的Index templates介面。

樣本

請求樣本

PUT _time_stream/test_stream
{
  "template": {
    "settings": {
      "index.number_of_shards": "10"
    }
  }
}

返回樣本
```
{
  "acknowledged" : true
}
```

更新TimeStream索引配置

請求文法

Body為空白
```
POST _time_stream/{name}/_update
```

Body中傳入自訂模板內容

POST _time_stream/{name}/_update
{
  --- index template ---
}

使用說明

更新介面傳遞的Body內容跟建立介面一致，具體可見建立TimeStream索引的使用說明。

更新TimeStream索引配置後，該配置不會立即應用到索引上，需要進行一次rollover後，配置才生效。

樣本

請求樣本

POST _time_stream/test_stream/_update
{
  "template": {
    "settings": {
      "index.number_of_shards": "10"
    }
  }
}

返回樣本
```
{
  "acknowledged" : true
}
```

刪除TimeStream索引

請求文法

Delete _time_stream/{name}

使用說明

支援模糊比對或按逗號分隔索引實現大量刪除。

警告刪除TimeStream索引後，對應的索引資料會直接清除，請謹慎操作。

樣本

請求樣本
```
DELETE _time_stream/test_stream
```
返回樣本
```
{
  "acknowledged" : true
}
```

查看TimeStream索引列表

請求文法

查看全部索引列表
```
GET _time_stream
```
查看指定的索引列表
```
GET _time_stream/{name}
```

使用說明

查看TimeStream索引列表，支援模糊查詢，以及按逗號分隔索引。

樣本

請求樣本
```
GET _time_stream
```

返回樣本

{
  "time_streams" : {
    "test_stream" : {
      "name" : "test_stream",
      "datastream_name" : "test_stream",
      "template_name" : ".timestream_test_stream",
      "template" : {
        "index_patterns" : [
          "test_stream"
        ],
        "template" : {
          "settings" : {
            "index" : {
              "number_of_shards" : "10"
            }
          }
        },
        "composed_of" : [
          ".system.timestream.template"
        ],
        "data_stream" : {
          "hidden" : true
        }
      }
    }
  }
}

查看TimeStream指標資訊

請求文法

查看全部索引的指標資訊
```
GET _time_stream/_stats
```
查看指定索引的指標資訊
```
GET _time_stream/{name}/_stats
```

使用說明

查看TimeStream指標介面，可以擷取索引的time_stream_count（時間軸數量）等指標。

關於time_stream_count（時間軸數量）的說明如下：

計算方式
1. 擷取索引中每個主shard的時間軸數量。由於每個shard的時間軸不重複，所以一個索引的時間軸數量就是全部主shard時間軸數量的總和。
2. 返回TimeStream索引列表中時間軸數量最大的索引。
注意事項
由於shard上擷取時間軸數量是從內部的時間軸ID（_tsid）欄位的docvalue資料直接擷取，查詢代價過高，所以增加了緩衝策略。唯讀索引擷取一次後就不再擷取，正常索引緩衝預設失效時間是5分鐘，通過設定索引配置index.time_series.stats.refresh_interval可修改緩衝更新時間，最小為1分鐘。

樣本

請求樣本
```
GET _time_stream/_stats
```

返回樣本

{
  "_shards" : {
    "total" : 4,
    "successful" : 4,
    "failed" : 0
  },
  "time_stream_count" : 2,
  "indices_count" : 2,
  "total_store_size_bytes" : 1278822,
  "time_streams" : [
    {
      "time_stream" : "test_stream",
      "indices_count" : 1,
      "store_size_bytes" : 31235,
      "tsidCount" : 1
    },
    {
      "time_stream" : "prom_index",
      "indices_count" : 1,
      "store_size_bytes" : 1247587,
      "tsidCount" : 317
    }
  ]
}

寫入資料

請求文法

TimeStream使用Elasticsearch原生寫入介面寫入資料，包括bulk和index。

重要寫入只支援append資料，不支援index存在的資料，也不支援update和delete。

寫入模型

TimeStream寫入的資料要符合時序資料模型，預設模型如下。

欄位	描述
labels	指標相關的屬性，唯一標識個體的中繼資料，時間軸ID可由labels產生。
metrics	指標資料集合，指標只能為long或者double類型。
@timestamp	指標記錄對應的時間，預設是毫秒級的時間戳記。

資料樣本如下。

{
  "labels": {
    "namespce": "cn-hanzhou",
    "clusterId": "cn-xxx-xxxxxx",
    "nodeId": "node-xxx",
    "label": "test-cluster",
    "disk_type": "cloud_ssd",
    "cluster_type": "normal"
  },
  "metrics": {
    "cpu.idle": 10.0,
    "mem.free": 100.1,
    "disk_ioutil": 5.2
  },
  "@timestamp": 1624873606000
}

樣本

請求樣本

POST test_stream/_doc
{
  "labels": {
    "namespce": "cn-hanzhou",
    "clusterId": "cn-xxx-xxxxxx",
    "nodeId": "node-xxx",
    "label": "test-cluster",
    "disk_type": "cloud_ssd",
    "cluster_type": "normal"
  },
  "metrics": {
    "cpu.idle": 10,
    "mem.free": 100.1,
    "disk_ioutil": 5.2
  },
  "@timestamp": 1624873606000
}

返回樣本

{
  "_index" : ".ds-test_stream-2021.09.03-000001",
  "_id" : "suF_qnsBGKH6s8C_OuFS",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

修改模型欄位

在建立TimeStream索引時，支援傳入自訂的單個或多個維度和指標欄位。TimeStream內部會為維度和指標欄位配置dynaimc_mapping，維度欄位會設定time_series_dimension，Elasticsearch內部會用維度欄位產生時間軸ID；指標欄位預設只使用doc_value。同時，配置欄位時，TimeStream索引支援使用*進行模糊比對。修改預設維度和指標欄位的樣本如下：

傳入單個欄位

PUT _time_stream/{name}
{
  --- index template ---
  "time_stream": {
    "labels_fields": "@label.*",
    "metrics_fields": "@metrics.*"
  }
}

傳入多個欄位

PUT _time_stream/{name}
{
  --- index template ---
  "time_stream": {
    "labels_fields": ["label.*", "dim*"],
    "metrics_fields": ["@metrics.*", "metrics.*"]
  }
}

參數	說明
labels_fields	預設為label.*，可選。
metrics_fields	預設為metrics.*，可選。

查詢資料

請求文法

TimeStream使用Elasticsearch原生查詢介面查詢資料，包括search和get。

樣本

請求樣本
```
GET test_stream/_search
```

返回樣本

{
  "took" : 172,
  "timed_out" : false,
  "_shards" : {
    "total" : 10,
    "successful" : 10,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : ".ds-test_stream-2021.09.03-000001",
        "_id" : "suF_qnsBGKH6s8C_OuFS",
        "_score" : 1.0
      }
    ]
  }
}

DownSample使用說明

DownSample（降採樣）是時序情境的常用功能，在建立TimeStream索引時，支援配置DownSample規則。配置了DownSample規則後，您只需正常讀寫資料，TimeStream索引就能在內部完成對原始寫入資料的DownSample處理。同時，在查詢資料時，TimeStream索引會根據aggregation中的interval參數來選擇合適的DownSample資料進行查詢。

DownSample規則只需配置interval，TimeStream索引會結合labels和metrics配置進行DownSample處理。metrics欄位經過DownSample處理後變成aggregate_metric_double類型，並產生max、min、sum和count四種資料。

由於DownSample觸發時機是在Rollover階段，對歷史不再寫入的索引進行DownSample處理，因此每個原始索引都會根據DownSample規則產生DownSample索引。DownSample索引預設繼承全部原始索引的settings，如果需要單獨配置DownSample索引的settings，可以在DownSample規則中指定。例如，如果DownSample索引的容量更小，可減少shard數量；儲存時間更長，可單獨指定ILM policy。

DownSample規則的配置樣本如下。

PUT _time_stream/{name}
{
  "time_stream": {
    "downsample": [
      {
        "interval": "1m",
        "settings": {
           "index.lifecycle.name": "my-rollup-ilm-policy_60m",
           "index.number_of_shards": "1"
        }
      },
      {
        "interval": "10m"
      }
    ]
  }
}

time_stream參數增加downsample參數，用來配置downsample列表。downsample中的參數說明如下。

參數	可選性	說明
interval	必選	配置downsample的時間間隔，downsample將按照該時間間隔Rollup資料。最多支援配置5個interval規則，不同規則需要保持倍數關係，例如1m、10m、60m。
settings	可選	配置downsample索引的setting資訊，例如生命週期配置、shard配置等。