Use the aliyun-timestream plug-in - Elasticsearch - Centre de documentation Alibaba Cloud

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un cluster Alibaba Cloud Elasticsearch répondant à l'une des exigences de version suivantes :
- Version du cluster V7.10, version du noyau V1.8.0 ou ultérieure
- Version du cluster V7.16 ou ultérieure, version du noyau V1.7.0 ou ultérieure

Pour savoir comment créer un cluster, consultez la rubrique Créer un cluster Alibaba Cloud Elasticsearch.

Créer un index de séries temporelles

Syntaxe de la requête

PUT _time_stream/{name}

Pour appliquer un modèle d'index personnalisé, incluez-le dans le corps de la requête :

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

Notes d'utilisation

Aucune configuration de modèle d'index n'est nécessaire. Spécifiez un nom exact pour l'index. Les caractères génériques ne sont pas pris en charge dans le nom.
Laissez le corps de la requête vide pour utiliser le modèle par défaut, ou incluez un modèle d'index personnalisé. Pour connaître le format du corps de la requête, consultez la documentation Elasticsearch relative aux Modèles d'index.

Exemple

Requête :

PUT _time_stream/test_stream
{
  "template": {
    "settings": {
      "index.number_of_shards": "10"   // Override index settings (optional)
    }
  }
}

Réponse :

{
  "acknowledged" : true
}

Pour vérifier que l'index a bien été créé, interrogez-le :

GET _time_stream/test_stream

Mettre à jour les configurations d'un index de séries temporelles

Syntaxe de la requête

POST _time_stream/{name}/_update

Pour appliquer un modèle d'index personnalisé, incluez-le dans le corps de la requête :

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

Notes d'utilisation

Le format du corps de la requête est identique à celui de la section Créer un index de séries temporelles.
Les configurations mises à jour ne prennent pas effet immédiatement. Effectuez un roulement (rollover) de l'index de séries temporelles pour que les modifications soient appliquées.

Exemple

Requête :

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

Réponse :

{
  "acknowledged" : true
}

Supprimer un index de séries temporelles

Avertissement

La suppression d'un index de séries temporelles entraîne la suppression définitive de toutes les données qui y sont stockées. Confirmez que cette suppression n'affectera pas votre activité avant de poursuivre.

Syntaxe de la requête

DELETE _time_stream/{name}

Notes d'utilisation

Utilisez un caractère générique pour faire correspondre et supprimer plusieurs index simultanément.
Spécifiez plusieurs noms d'index séparés par des virgules (,) pour les supprimer en une seule requête.

Exemple

Requête :

DELETE _time_stream/test_stream

Réponse :

{
  "acknowledged" : true
}

Interroger les index de séries temporelles

Syntaxe de la requête

Interroger tous les index de séries temporelles :

GET _time_stream

Interroger des index de séries temporelles spécifiques :

GET _time_stream/{name}

Notes d'utilisation

Utilisez un caractère générique pour faire correspondre plusieurs index selon un modèle de nom.
Spécifiez plusieurs noms d'index séparés par des virgules (,) pour les interroger en une seule requête.

Exemple

Requête :

GET _time_stream

Réponse :

{
  "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
        }
      }
    }
  }
}

Interroger les métriques des index de séries temporelles

Syntaxe de la requête

Interroger les métriques de tous les index de séries temporelles :

GET _time_stream/_stats

Interroger les métriques d'un index de séries temporelles spécifique :

GET _time_stream/{name}/_stats

Notes d'utilisation

Le point de terminaison _stats renvoie des métriques, notamment time_stream_count, qui indique le nombre total de séries temporelles dans l'index.

Mode de calcul de time_stream_count :

La métrique compte le nombre de séries temporelles sur chaque shard primaire. Chaque shard primaire possède son propre ensemble distinct de séries temporelles ; le total pour un index correspond donc à la somme sur tous les shards primaires.
La réponse identifie l'index contenant le plus grand nombre de séries temporelles.

Performances et mise en cache : Le comptage des séries temporelles lit les valeurs de document du champ _tsid, ce qui génère des coûts de requête élevés. Pour réduire la surcharge :

Pour les index en lecture seule, le compte est mis en cache après la première requête.
Pour les autres index, le cache s'actualise toutes les 5 minutes par défaut. Modifiez cet intervalle avec le paramètre index.time_series.stats.refresh_interval . La valeur minimale est de 1 minute.

Exemple

Requête :

GET _time_stream/_stats

Réponse :

{
  "_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
    }
  ]
}

Écrire des données de séries temporelles dans un index de séries temporelles

aliyun-timestream utilise les API standard d'Elasticsearch, à savoir l'API bulk et l'API index , pour écrire des données dans un index de séries temporelles.

Important

Les écritures de données sont append-only (ajout seul). Le plug-in ne peut pas indexer, mettre à jour ni supprimer les données existantes.

Modèle de données

Chaque document écrit dans un index de séries temporelles doit respecter le modèle de données des séries temporelles :

Champ	Description
`labels`	Champs de dimension qui identifient de manière unique une série temporelle. Elasticsearch génère un ID de série temporelle (`_tsid`) à partir de ces champs.
`metrics`	Valeurs des métriques. Doivent être de type `LONG` ou `DOUBLE` .
`@timestamp`	Heure à laquelle les données de métrique ont été collectées. Par défaut, il s'agit d'un horodatage Unix avec une précision en millisecondes.

Exemple de document :

{
  "labels": {
    "namespce": "cn-hanzhou",      // Dimension fields — uniquely identify the time series and generate _tsid
    "clusterId": "cn-xxx-xxxxxx",
    "nodeId": "node-xxx",
    "label": "test-cluster",
    "disk_type": "cloud_ssd",
    "cluster_type": "normal"
  },
  "metrics": {
    "cpu.idle": 10.0,              // Metric values — must be LONG or DOUBLE
    "mem.free": 100.1,
    "disk_ioutil": 5.2
  },
  "@timestamp": 1624873606000      // Millisecond-precision Unix timestamp
}

Configurer les champs de dimension et de métrique

Lors de la création d'un index de séries temporelles, vous pouvez définir des champs de dimension personnalisés (labels_fields) et des champs de métrique (metrics_fields). Le plug-in crée automatiquement des mappages dynamiques et définit time_series_dimension: true sur les champs de dimension. Par défaut, les champs de métrique stockent uniquement les valeurs de document.

Les caractères génériques (*) sont pris en charge dans les modèles de noms de champ.

Télécharger un seul modèle de champ personnalisé :

PUT _time_stream/{name}
{
  --- index template ---
  "time_stream": {
    "labels_fields": "@label.*",    // Dimension field pattern — sets time_series_dimension: true
    "metrics_fields": "@metrics.*"  // Metric field pattern — stores doc values only
  }
}

Télécharger plusieurs modèles de champ :

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

Paramètre	Obligatoire	Par défaut	Description
`labels_fields`	Non	`label.*`	Modèles de noms de champ pour les champs de dimension
`metrics_fields`	Non	`metrics.*`	Modèles de noms de champ pour les champs de métrique

Exemple

Requête :

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
}

Réponse :

{
  "_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
}

Interroger les données d'un index de séries temporelles

aliyun-timestream utilise les API standard d'Elasticsearch, à savoir l'API search et l'API get , pour interroger les données. Le plug-in utilise des instructions Prometheus Querying Language (PromQL) au lieu d'instructions DSL (Domain Specific Language) pour interroger les données de métriques stockées, ce qui simplifie les opérations de requête et améliore leur efficacité.

Exemple

Requête :

GET test_stream/_search

Réponse :

{
  "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
      }
    ]
  }
}

Configurer le sous-échantillonnage (downsampling)

Le sous-échantillonnage réduit les coûts de stockage des données de séries temporelles en les agrégeant à une résolution inférieure.

Configurez une règle de sous-échantillonnage lors de la création d'un index de séries temporelles. Après la configuration, les lectures et les écritures dans l'index fonctionnent normalement ; le sous-échantillonnage s'exécute automatiquement en arrière-plan au moment du roulement (rollover), agissant sur les index qui ne reçoivent plus d'écritures.

Après le sous-échantillonnage, les valeurs des champs de métrique sont converties au type aggregate_metric_double et divisées en quatre sous-champs : max , min , sum et count . Lors de l'interrogation de l'index, le système sélectionne automatiquement les données sous-échantillonnées appropriées en fonction du paramètre interval de l'agrégation.

Chaque index sous-échantillonné hérite par défaut des paramètres de son index source. Remplacez les paramètres (tels que le nombre de shards primaires ou une politique ILM – Index Lifecycle Management) directement dans la règle de sous-échantillonnage.

Exemple de configuration

PUT _time_stream/{name}
{
  "time_stream": {
    "downsample": [
      {
        "interval": "1m",           // Required — data is rolled up at this granularity
        "settings": {               // Optional — override settings for the downsampling index
          "index.lifecycle.name": "my-rollup-ilm-policy_60m",
          "index.number_of_shards": "1"
        }
      },
      {
        "interval": "10m"           // A second downsampling tier at 10-minute granularity
      }
    ]
  }
}

Paramètres de sous-échantillonnage

Paramètre	Obligatoire	Description
`interval`	Oui	Granularité à laquelle les données sont agrégées. Spécifiez jusqu'à cinq intervalles. Si vous en spécifiez plusieurs, assurez-vous qu'ils sont multiples les uns des autres, par exemple `1m` , `10m` et `60m` .
`settings`	Non	Paramètres de l'index de sous-échantillonnage, tels que la politique ILM et le nombre de shards primaires.