TSDS 指南

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

本文档包含

背景
为指标数据集启用 TSDS 的步骤
测试
最佳实践
故障排除

背景

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

集成是 Elasticsearch 输入数据的最大来源之一。通过对包中的 fields.yml 和 manifest.yml 文件进行最少的更改，即可在集成包上启用 TSDS。

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

重要提示

类型为 logs 的数据流已从 TSDS 迁移中排除。

步骤 1：设置维度字段

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

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

		- name: ApiId
  type: keyword
  dimension: true

	

注意

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

您可以在 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 文件中，以启用 timeseries 索引模式。

		elasticsearch:
  index_mode: "time_series"

测试

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

最佳实践

使用 Lens 作为首选可视化类型。
始终评估选为维度的字段的唯一值数量，尤其是当它是数值字段时。包含数百万个唯一值的字段可能不是成为维度字段的理想选择。
如果维度字段值的长度非常长（最大限制为 1024B），请考虑将值转换为哈希值表示。 Fingerprint 处理器可用于此目的。
在上面每个维度字段的字段映射文件中，添加行内注释，说明选择该字段作为维度字段的原因。
作为 TSDS 迁移测试的一部分，您可能会发现其他与 TSDS 迁移无关的错误。请保持 TSDS 迁移的 pull request 清除这些更改。这有助于快速获得 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! 
	

考虑

为每个数据流定义 look_ahead 或 look_back_time。例如。
```
elasticsearch:
  index_mode: "time_series"
  index_template:
    settings:
      index.look_ahead_time: "10h"
```
注意

使用此更新包不会导致数据流自动滚动。您必须手动进行。
更新被拒绝文档的 timestamp。
找到一种接收文档而不延迟的解决方案。