TimeStream API功能介绍

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

阿里云Elasticsearch提供Aliyun-TimeStream时序增强插件,支持通过API接口完成TimeStream索引的增删改查,以及数据写入和查询。本文介绍如何使用TimeStream API。

背景信息

TimeStream是阿里云Elasticsearch团队自研,并结合Elastic社区时序类产品特性共建的时序引擎。阿里云Elasticsearch提供的TimeStream时序增强功能插件,优化了Elasticsearch在存储指标数据方面的DSL(Domain-Specific Language)查询复杂且慢以及存储成本过高等问题。详细信息请参见TimeStream时序增强引擎介绍

前提条件

已创建阿里云Elasticsearch实例,且实例版本为7.10(内核版本为1.8.0及以上)或7.16及以上(内核版本为1.7.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原生写入接口写入数据,包括bulkindex

重要

写入只支持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原生查询接口查询数据,包括searchget

示例

  • 请求示例

    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配置等。