› ›

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!

考虑

为每个数据流定义 look_ahead 或 look_back_time。例如
```
elasticsearch:
  index_mode: "time_series"
  index_template:
    settings:
      index.look_ahead_time: "10h"
```
使用此更新包不会导致数据流自动滚动。您必须手动执行此操作。
更新被拒绝的文档的 timestamp。
找到无需延迟即可接收文档的修复方法。

« 使用新索引功能如何测试新的索引功能 »