正在加载

TSDS 指南

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

在本文档中，您可以找到

时间序列是特定实体的观测序列。 TSDS 通过共置数据并优化存储和聚合，从而利用这种共置，从而在 Elasticsearch 中启用面向列的功能。

集成是 Elasticsearch 最大的输入数据源之一。 通过对包的 fields.yml 和 manifest.yml 文件进行最小的更改，可以集成包上启用 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
    1. 默认为 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，并与当前时间进行比较，以识别写入索引。

如果您发现此错误（有关参考，请参阅integrations issue #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. 找到一个修复程序以接收没有延迟的文档。

© . All rights reserved.