通用指南

虽然指南侧重于指标，但它们同样适用于日志。

鉴于所有软件包都是基本的，开发人员应在适用时使用基本类型（例如 histogram、wildcard 等）。 当然，对于 ECS（见下文），我们应该使用 ECS 指定的类型。

集成软件包应符合 ECS 的最新版本。 这意味着集成填充了更多相关的 ECS 字段。

从 ECS 1.6 开始，ECS 将开始对某些字段使用基本类型。 作为此过程的一部分，集成字段应升级到新类型。

集成生成的所有字段都必须通过 fields.yml 进行映射。 这保证了它们的索引映射是正确的，并且 Kibana 有足够的信息来处理所有字段。

默认情况下，数据流的 total_fields.limit 设置为 1000。 除了定义的自定义字段外，这还包括动态生成的 ECS 字段。 如果您的数据流预计最终将包含超过 1000 个字段，请在数据流的 manifest.yml 中设置显式限制

elasticsearch:
  index_template:
    settings:
      index:
        mapping:
          total_fields:
            limit: 5000

作为字段定义的一部分，有两个设置可以添加元数据，这将有助于 Kibana 绘制图表

• unit 适用于所有数据类型，定义字段的单位。 单位的示例包括 byte 和 ms。 当使用 percent 表示百分比时，约定是使用 1 表示 100%。 您可以在软件包规范中找到支持的单位的完整列表。
• metric_type 仅适用于指标事件，要添加到指标字段。 它定义了它们的指标类型。 它可以是 gauge 或 counter 类型。 计数器用于随时间始终增加的指标，例如页面访问次数。 仪表用于随时间可以增加或减少的量，例如正在使用的内存量。

Elasticsearch 文档详细说明了这两个字段的预期值。

包括 Kibana 在内的其他应用程序可以在访问这些字段时使用此元数据提供的信息。 格式化字段的值时使用 unit，在查询数据时可以使用 metric_type 提供更好的默认值。

数据流的一组字段可以定义为维度。 具有相同值的一组维度标识单个时间序列。

仔细选择字段集非常重要。 它们应该是正确识别数据流中包含的任何时间序列所需的最小维度集。 维度太少可能会将多个时间序列的数据混合到一个时间序列中，而维度太多可能会影响性能。

可以通过在其定义中设置 dimension: true 将字段配置为维度。

只有某些数据类型的字段可以定义为维度。 这些数据类型包括关键字、IP 和数字类型。

选择维度时要考虑的一些指南

• 它们会影响提取性能，建议尽可能少的维度。 选择维度时，尽量避免冗余维度，例如引用同一对象的唯一标识符和名称。
• 还要注意维度是否太少。 对于给定的维度集，只能有一个具有相同时间戳的文档。 如果不同的对象产生相同的维度，这可能会导致数据丢失。
• 更改维度可能会产生重大更改。 即使它们选择相同的数据，不同的维度集也会产生不同的时间序列。

声明维度是使用 TSDB 索引的先决条件。 这些索引针对时间序列用例进行了优化，从而节省了磁盘存储空间并提供了额外的查询和聚合。

可以通过在其清单中设置 elasticsearch.index_mode: time_series 在数据流中启用 TSDB 索引。

如果适用，集成软件包应为日志和指标应用程序提供相关字段。 这对于专注于计算资源（VM、容器等）的集成尤其重要。

• 保持日志应用程序字段参考是最新的。
• 保持基础设施应用程序字段参考是最新的。

集成软件包应为任何目标系统收集合理数量的指标。 在某些情况下，这可能意味着删除 Filebeat 和 Metricbeat 今天正在收集的某些指标。 收集过多的指标会对指标存储以及提供给用户的数据的相关性产生影响。

要删除的潜在候选对象

• 低级别垃圾回收器指标
• 显示代码流的内部指标（例如，Got100Continue、Wait100Continue）
• 冗余指标（例如，MQ 主题的指标收集不需要收集摘要指标）

这可能是最重要也是最难满足的指南之一，因为它需要了解每个目标系统。 识别相关指标应根据具体情况进行考虑。

此练习没有明确定义的指南。 它可以简单到在一个地方找到所有内容（例如RabbitMQ 文档），或者困难到审查多个来源，包括文档、博客文章和其他集成，并将发现的信息整合到一个地方进行修订。 建议仅收集仪表板和可视化通常需要的指标。

日志集成应保留原始消息字段（建议名称：event.original），以便它显示在日志 UI 中。 当用户想要在更改管道后重新索引数据时，它也会很有用。 此外，消息字段可用作某些未来运行时字段的来源。

原始字段应该是用户可配置的，具有 Kibana UI，以实现更好的成本和存储管理，并且与其他集成保持一致。

每个集成都应努力尽可能高效地存储收集的数据，这意味着优化每个集成生成文档的方式。

如果适用，集成软件包应提供一个默认数据集，该数据集聚合了其他数据流中最相关的指标的子集。 将这些指标视为在概览仪表板上可视化或用于警报的指标。 当软件包中的数据集数量超过三个时，可以创建一个单独的默认数据集。

集成软件包应支持目标系统的最相关版本。 我们的一些集成支持较旧的目标服务/系统版本，这些版本在实施时是相关的。 随着时间的推移，它们可能会过时并需要进行修订，这可能就像针对最新版本测试集成并更新文档中的兼容性部分一样简单，或者可能意味着重构代码以使其与最新版本一起使用。 例如，Ceph 模块最近已更新以支持最新版本，该版本具有完全不同的指标收集方式。 为了适应模块中的旧版本和新版本，专门为新版本在模块中创建了指标集，并在文档中注明了要使用的指标集。

集成软件包应提供有意义的默认值，例如收集间隔（周期）、启用的指标集以及任何其他集成特定的配置参数。 在大多数情况下，用户选择使用默认值。 因此，提供相关的默认值对于集成的有用性至关重要。 此外，集成应努力通过提供可以覆盖 80% 用例的默认值来提供一键式体验。

集成包应提供一致且全面的文档。更多详情，请参阅文档指南。

集成包应提供开箱即用的仪表板。更多详情，请参阅仪表板指南。

每个集成都将在公共网站 elastic.co/integrations 上列出，且软件包注册表将作为事实来源。因此，文档和屏幕截图应具有高质量，以展示集成。请确保 logo 使用 svg 格式，所有其他图像使用 png 格式。任何其他品牌宣传材料都应仔细审查，例如

• logo 格式和质量
• 使用 logo 和商标的许可

建议在 Fleet 中设置集成策略。每个集成和代理都应在 Fleet 中可见，并且用户应该能够直接从集成列表中添加集成。这可以带来更好的凝聚力，因为它可以在各个集成之间提供一致的体验，允许用户一次添加多个集成，并避免在多个应用程序之间来回切换。它还允许用户在列表中发现新的集成。

Elastic 产品还将可以选择为难以放入 Fleet 中的设置提供精心设计的 UI。产品可以自行决定希望在直接从 Fleet 更改配置方面提供多少灵活性。这将取决于用例以及这样做是否有意义。但建议提供一定程度的配置。

当通过 Fleet 安装资产时，默认情况下会添加一些元数据。

对于 Elasticsearch 资产，例如索引模板和 ingest 管道，将以下列方式将 _meta 属性添加到资产

{
  "managed_by": "fleet",
  "managed": true,
  "package": {
    "name": "<package name>"
  }
}

对于 Kibana 资产，除了 _meta 属性外，还会生成标签

• 一个 name 与软件包的 title 属性匹配的标签
• managed 标签，Kibana 使用该标签来识别“系统”资产，或那些由 Kibana 本身安装而不是由最终用户生成的资产