« 使用新的索引功能 如何测试新的索引功能 »
Elastic 文档 ›集成开发指南 ›使用新的索引功能

TSDS 指南

编辑

TSDS 指南

编辑

本页面介绍如何在您的集成包中启用 TSDS 功能。有关 TSDS 的完整详细信息，请参阅 Elasticsearch 文档中的时间序列数据流。

在本文档中，您可以找到

背景

编辑

时间序列是特定实体的一系列观测值。TSDS 通过将数据共同定位并优化存储和聚合以利用这种共同定位，从而在 Elasticsearch 中启用列式功能。

集成是 Elasticsearch 输入数据的主要来源之一。通过对包的fields.yml 和manifest.yml 文件进行最小的更改，可以对集成包启用 TSDS。

为指标数据集启用 TSDS 的步骤

编辑

类型为logs 的数据流不包含在 TSDS 迁移中。

步骤 1：设置维度字段

编辑

属于唯一标识文档的字段集的每个字段都是一个维度。有关更多详细信息，请参阅维度。

要将字段设置为维度，只需将其映射中添加dimension: true

- name: ApiId
  type: keyword
  dimension: true

类型为flattened 的字段不能选择为维度字段。如果您选择的维度字段过长或类型为 flattened，请考虑对该字段的值进行哈希处理，并使用结果作为维度。指纹处理器 可用于此目的。

您可以在Oracle 集成 TSDS 启用示例 中找到一个示例

重要注意事项

  • 数据流可以具有的维度字段数量有限制。默认情况下，此值为21。您可以通过更改index.mapping.dimension_fields.limit 来调整此限制。

    elasticsearch:
  index_template:
    settings:
      index.mapping.dimension_fields.limit: 32 # Defaults to 21
  • 维度键的硬性限制为 512b。如果达到此限制，则会拒绝文档。
  • 维度值的硬性限制为 1024b。如果达到此限制，则会拒绝文档。
ECS 字段
编辑

有一些字段是每个包的一部分，它们是成为维度字段的潜在候选者

  • host.name
  • service.address
  • agent.id
  • container.id

对于能够在本地和公共云环境中运行（通过部署在公共云虚拟机上）的产品，建议将下面列出的 ECS 字段注释为维度字段

  • host.name
  • service.address
  • container.id
  • cloud.account.id
  • cloud.provider
  • cloud.region
  • cloud.availability_zone
  • agent.id
  • cloud.instance.id

对于在 AWS、Azure 和 GCP 等云提供商中作为托管服务运行的产品，建议将下面列出的字段标记为维度字段

  • cloud.account.id
  • cloud.region
  • cloud.availability_zone
  • cloud.provider
  • agent.id

请注意，对于某些包，其中一些字段没有任何值，因此请确保仅使用所需的字段。

集成特定字段
编辑

files.yml 文件包含特定于集成数据流的字段映射。如果 ECS 中的维度字段集不足以创建唯一的_tsid，则可能需要将其中一些字段设置为维度。

建议在维度注释之前添加内联注释，详细说明将特定字段选择为维度字段的原因

```
- name: wait_class
  type: keyword
  # Multiple events are generated based on the values of wait_class. Hence, it is a dimension
  dimension: true
  description: Every wait event belongs to a class of wait events.
```

步骤 2：为指标字段设置类型

编辑

指标是包含数值度量、以及基于这些度量的聚合和/或下采样值的字段。使用正确的指标类型对每个指标进行注释。当前支持的值 为gauge、counter 和null。

向字段添加指标类型的示例

- name: compactions_failed
  type: double
  metric_type: counter
  description: |
    Counter of TSM compactions by level that have failed due to error.

某些聚合函数不支持某些metric_type 值。在这种情况下，请重新检查您为该字段选择的metric_type 是否确实正确。如果有效，请在elastic/elasticsearch 中创建一个问题，说明用例。

步骤 3：更新 Kibana 版本

编辑

将包的manifest.yml 文件中的kibana.version 修改为至少8.8.0

conditions:
 kibana.version: "^8.8.0"

步骤 4：启用time_series 索引模式

编辑

如所示，将更改添加到数据流的manifest.yml 文件中以启用时间序列索引模式

elasticsearch:
  index_mode: "time_series"

测试

编辑
  • 如果维度的数量不足，我们将丢失数据。请考虑使用TSDS 迁移测试套件 测试这一点。
  • 验证仪表板是否正确呈现数据。如果某些可视化效果不起作用，请考虑迁移到Lens。请记住，当字段具有指标类型counter 时，某些聚合函数不受支持，例如avg()。将此类聚合函数替换为受支持的聚合类型，例如max() 或min()。

最佳实践

编辑
  • 使用Lens 作为首选的可视化类型。
  • 始终评估选择作为维度的字段将保存的唯一值的数目，尤其是在它是数字字段的情况下。保存数百万个唯一值的字段可能不是成为维度字段的理想候选者。
  • 如果维度字段值长度很长（最大限制为 1024B），请考虑将值转换为哈希值表示形式。指纹处理器 可用于此目的。
  • 在上述字段映射文件中，在每个维度字段之前添加内联注释，说明选择该字段作为维度字段的原因。
  • 作为 TSDS 迁移测试的一部分，您可能会发现其他与 TSDS 迁移无关的错误。请保持 TSDS 迁移的拉取请求不包含此类更改。这有助于快速获得 PR 批准。

故障排除

编辑
已丢弃的文档
编辑

如果在启用 TSDS 后您发现指标数据已从索引中删除，则可以使用TSDS 测试迁移套件 作为有用的调试工具。

冲突的字段类型
编辑

具有冲突字段类型的字段将不被视为维度。在将字段定义为维度字段之前，请解决字段类型歧义。

写入索引的识别
编辑

当数据流的映射被修改时，会发生索引滚动，并在数据流下创建一个新索引。即使存在新索引，数据也会继续进入旧索引，直到时间戳与新创建索引的index.time_series.start_time 匹配。

已为 Kibana 创建了一个增强请求 来指示写入索引。在此之前，请参考索引的 index.time_series.start_time 并与当前时间进行比较以识别写入索引。

如果您发现此错误（作为参考，请参阅集成问题 #7345 和elasticsearch PR #98518）

... (status=400): {"type":"illegal_argument_exception","reason":"the document timestamp [2023-08-07T00:00:00.000Z] is outside of ranges of currently writable indices [[2023-08-07T08:55:38.000Z,2023-08-07T12:55:38.000Z]]"}, dropping event!

请考虑

  1. 为每个数据流定义look_ahead 或look_back_time。例如

    elasticsearch:
  index_mode: "time_series"
  index_template:
    settings:
      index.look_ahead_time: "10h"

    使用此更新包不会导致数据流自动滚动。您必须手动执行此操作。

  2. 更新被拒绝的文档的timestamp。
  3. 找到一个修复程序以无延迟地接收文档。
« 使用新的索引功能 如何测试新的索引功能 »