aliyun-timestream プラグインの使用 - Elasticsearch - Alibaba Cloud ドキュメントセンター

Alibaba Cloud Elasticsearch は、時系列データの保存と使用を強化するための aliyun-timestream という名前のプラグインを提供しています。このプラグインを使用すると、API を使用して時系列インデックスの作成、削除、変更、クエリを実行したり、時系列インデックスへのデータの書き込みとデータのクエリを実行したりできます。このトピックでは、aliyun-timestream でサポートされている API を使用して上記の操作を実行する方法について説明します。

背景情報

aliyun-timestream は、Elastic コミュニティが提供する時系列製品の機能に基づいて、Alibaba Cloud Elasticsearch チームが開発したプラグインです。このプラグインは、時系列データの保存と使用のパフォーマンスを向上させるために使用されます。 aliyun-timestream は、ドメイン固有言語 ( DSL ) ステートメントではなく、Prometheus Querying Language ( PromQL ) ステートメントを使用して、保存されているメトリックデータをクエリします。これにより、クエリ操作が簡素化され、クエリ効率が向上します。 aliyun-timestream はストレージコストも削減します。詳細については、「aliyun-timestream の概要」をご参照ください。

前提条件

次のバージョン要件を満たす Elasticsearch クラスターが作成されていること。クラスターのバージョンが V7.10 で、クラスターのカーネルバージョンが V1.8.0 以降であること、またはクラスターのバージョンが V7.16 以降で、クラスターのカーネルバージョンが V1.7.0 以降であること。Elasticsearch クラスターの作成方法については、「Alibaba Cloud Elasticsearch クラスターの作成」をご参照ください。

時系列インデックスの作成

リクエスト構文

リクエスト本文にコンテンツが指定されていません
```
PUT _time_stream/{name}
```
カスタムテンプレートがリクエスト本文にアップロードされています
```
PUT _time_stream/{name}
{
  --- index template --- // インデックステンプレート
}
```

使用上の注意

時系列インデックスを作成する場合、インデックスパターンを設定する必要はありません。ただし、インデックスに特定の名前を指定する必要があります。名前にワイルドカードはサポートされていません。

リクエスト本文を空のままにするか、カスタムテンプレートをリクエスト本文にアップロードできます。リクエスト本文の形式については、オープンソース Elasticsearch のドキュメントの「インデックステンプレート」をご参照ください。

例

リクエスト例

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

レスポンス例
```
{
  "acknowledged" : true
}
```

時系列インデックスの構成の更新

リクエスト構文

リクエスト本文にコンテンツが指定されていません
```
POST _time_stream/{name}/_update
```

カスタムテンプレートがリクエスト本文にアップロードされています

POST _time_stream/{name}/_update
{
  --- index template --- // インデックステンプレート
}

使用上の注意

時系列インデックスの構成を更新するために使用される API に渡されるリクエスト本文は、時系列インデックスを作成するために使用される API に渡されるリクエスト本文と同じです。詳細については、このトピックの「時系列インデックスの作成」セクションをご参照ください。

時系列インデックスの構成を更新した後、新しい構成はインデックスにすぐには反映されません。新しい構成を有効にするには、時系列インデックスをロールオーバーする必要があります。

例

リクエスト例

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

レスポンス例
```
{
  "acknowledged" : true
}
```

時系列インデックスの削除

リクエスト構文

Delete _time_stream/{name}

使用上の注意

あいまい一致を実行して複数の時系列インデックスを検索し、一度に削除できます。削除する時系列インデックスの名前を指定し、名前をカンマ ( , ) で区切って一度に削除することもできます。

警告

時系列インデックスを削除すると、インデックスに保存されているデータも削除されます。削除操作を実行する前に、操作がビジネスに影響を与えないことを確認してください。

例

リクエスト例
```
DELETE _time_stream/test_stream
```
レスポンス例
```
{
  "acknowledged" : true
}
```

時系列インデックスのクエリ

リクエスト構文

すべての時系列インデックスをクエリする
```
GET _time_stream
```
特定の時系列インデックスをクエリする
```
GET _time_stream/{name}
```

使用上の注意

あいまい一致を実行して、クエリする時系列インデックスを検索できます。クエリする時系列インデックスの名前を指定し、名前をカンマ ( , ) で区切ってインデックスを検索することもできます。

例

リクエスト例
```
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
        }
      }
    }
  }
}

時系列インデックスのメトリックのクエリ

リクエスト構文

すべての時系列インデックスのメトリックをクエリする
```
GET _time_stream/_stats
```
特定の時系列インデックスのメトリックをクエリする
```
GET _time_stream/{name}/_stats
```

使用上の注意

時系列インデックスのメトリックをクエリするために使用される API を呼び出して、time_stream_count などのメトリックに関する情報を取得できます。 time_stream_count メトリックの値は、時系列の数を示します。

time_stream_count メトリックの説明：

計算方法
1. time_stream_count メトリックは、インデックスのプライマリシャードごとに時系列の数を収集します。各プライマリシャードには異なる時系列があります。インデックスの全時系列の総数は、インデックスのすべてのプライマリシャードの時系列の数の合計です。
2. time_stream_count メトリックは、時系列の数が最も多いインデックスの名前を返します。
注意事項
time_stream_count メトリックは、時系列の ID を指定する _tsid フィールドの doc 値から、プライマリシャードごとに時系列の数を収集します。このプロセスは、非常に高いクエリコストを発生させます。コストを削減するために、Elasticsearch ではキャッシュポリシーを設定できます。読み取り専用インデックスにこのようなポリシーを設定すると、time_stream_count メトリックは、インデックスのプライマリシャードごとに時系列の数を 1 回だけ収集します。デフォルトでは、システムは他のタイプのインデックスのキャッシュを 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
    }
  ]
}

時系列インデックスへの時系列データの書き込み

リクエスト構文

aliyun-timestream プラグインは、bulk API や index API など、オープンソース Elasticsearch が提供する API を使用して、時系列インデックスにデータを書き込みます。

重要

aliyun-timestream プラグインが API を使用して時系列インデックスにデータを書き込む場合、プラグインはデータを追加することしかできません。プラグインは、既存のデータをインデックス化、更新、または削除することはできません。

データ書き込みモデル

aliyun-timestream プラグインを使用して時系列インデックスにデータを書き込む場合、データが時系列データモデルの要件を満たしていることを確認する必要があります。時系列データモデルには、次の表で説明するデフォルトフィールドが含まれています。

フィールド	説明
labels	メトリックに関連するプロパティ。このフィールドは、書き込まれるデータレコードのメタデータを一意にマークします。時系列の ID は、このフィールドの設定によって生成できます。
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
}

時系列データモデルのフィールドの設定

時系列インデックスを作成するときに、1 つ以上のカスタムディメンションフィールドとメトリックフィールドをアップロードできます。 aliyun-timestream プラグインは、ディメンションフィールドとメトリックフィールドの動的マッピングを自動的に作成し、ディメンションフィールドの time_series_dimension パラメーターを設定します。 Elasticsearch は、ディメンションフィールドに基づいて時系列 ID を自動的に生成します。デフォルトでは、メトリックフィールドには doc 値のみが保存されます。ディメンションフィールドとメトリックフィールドを設定する場合、ワイルドカード ( * ) を使用してあいまい一致を実行できます。次のコードは、ディメンションフィールドとメトリックフィールドを設定する方法の例を示しています。

単一のカスタムディメンションフィールドまたはメトリックフィールドをアップロードする

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.*。

時系列インデックスのデータのクエリ

リクエスト構文

aliyun-timestream プラグインは、search API や get API など、オープンソース Elasticsearch が提供する API を使用して、時系列インデックスのデータをクエリします。

例

リクエスト例
```
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
      }
    ]
  }
}

ダウンサンプリングの使用上の注意

ダウンサンプリングは、時系列シナリオで一般的に使用される機能です。時系列インデックスを作成するときに、インデックスのダウンサンプリングルールを構成できます。時系列インデックスのダウンサンプリングルールを構成した後、インデックスへのデータの読み取りまたは書き込みのみを行う必要があり、インデックスはインデックス内のデータに対して自動的にダウンサンプリングを実行します。時系列インデックスのデータをクエリすると、インデックスは、集計用に構成された interval パラメーターの値に基づいて、クエリする必要があるダウンサンプリングされたデータの範囲を自動的に決定します。

時系列インデックスのダウンサンプリングルールを構成する場合、構成する必要があるのは interval パラメーターのみです。時系列インデックスは、ラベルフィールドとメトリックフィールドの構成に基づいて、データのダウンサンプリングを自動的に実行します。ダウンサンプリング後、メトリックフィールドの値のデータ型は aggregate_metric_double に変更され、システムはメトリックフィールドに対して max、min、sum、および count のサブフィールドを生成します。

ダウンサンプリングルールは、ロールオーバー段階でトリガーされます。ダウンサンプリングルールがトリガーされると、データが書き込まれなくなったインデックスに対してダウンサンプリングが実行されます。システムは、ダウンサンプリングルールに基づいて、元のインデックスごとにダウンサンプリングインデックスを生成します。デフォルトでは、各ダウンサンプリングインデックスは、関連する元のインデックスの設定を継承します。ダウンサンプリングインデックスの設定をカスタマイズする場合は、関連するダウンサンプリングルールで設定を構成できます。たとえば、ダウンサンプリングインデックスの容量を削減する場合は、インデックスのプライマリシャードの数を減らすことができます。ダウンサンプリングインデックスをより長期間保存する場合は、インデックスのインデックスライフサイクル管理（ ILM ）ポリシーを構成できます。

次のコードは、ダウンサンプリングルールを構成する方法の例を示しています。

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	はい	ダウンサンプリングが実行される間隔です。ダウンサンプリング中、データはこのパラメーターで指定された間隔でロールアップされます。最大 5 つの間隔を指定できます。複数の間隔を指定する場合は、間隔が倍数であることを確認する必要があります。たとえば、1m、10m、60m を指定できます。
settings	いいえ	ダウンサンプリングインデックスの設定 (ライフサイクルやプライマリシャードの数に関連する設定など)。