TGCode

关注互联网技术

Observability：使用 ecs@mappings 模板保证你的日志面向未来

2024年11月6日   |   by mebius

作者：来自 ElasticMaurizio Branca

%title插图%num

探索 Elasticsearch 中的 ecs@mappings 组件模板如何通过提供 Elastic Common Schema (ECS) 映射的集中式官方定义来简化数据管理。了解其优势，包括减少配置麻烦、提高数据完整性以及为集成开发人员和社区用户增强性能。了解此功能如何简化跨 Elastic Agent 集成的 ECS 现场支持并为你的数据流提供面向未来的保障。

随着 Elasticsearch 生态系统的发展，旨在简化数据管理的工具和方法也在不断发展。ecs@mappings 组件模板是一项将极大地造福我们社区的进步。

ECS（Elastic Common Schema）是用于日志和指标的标准化数据模型。它定义了一组通用字段名称和数据类型，有助于确保一致性和兼容性。

ecs@mappings 是一个组件模板，它提供了 Elastic 维护的 ECS 映射定义。每个 Elasticsearch 版本都包含所有 ECS 字段的始终最新的定义。

Elastic Common Schema 和 Open Telemetry

Elastic 将通过将 ECS 捐赠给 Open Telemetry 来保护我们用户对 Elastic Common Schema 的投资。Elastic 参与并与 OTel 社区合作，随着时间的推移合并 ECS 和 Open Telemetry 的语义约定。

ECS 映射的演变

从历史上看，用户和集成开发人员在各个索引模板和包中手动定义 ECS（Elastic Common Schema）映射，每个映射都一丝不苟地列出其字段。虽然这种方法很简单，但事实证明它很耗时，而且难以维护。

为了应对这一挑战，集成开发人员转向了两种主要方法：

  1. 引用 ECS 映射
  2. 直接导入 ECS 映射

这些方法是朝着正确方向迈出的一步，但也带来了挑战，例如保持 ECS 映射与 Elasticsearch 更改保持同步的维护成本。

输入 ecs@mappings

ecs@mappings 组件模板支持 ECS 中的所有字段定义，利用命名约定和一组动态模板。

Elastic 开始随 Elasticsearch v8.9.0 一起提供 ecs@mappings 组件模板，并将其包含在 logs–index template。

借助 Elasticsearch v8.13.0，Elastictgcode 现在在所有 Elastic Agent 集成的索引模板中包含 ecs@mappings。

这一举措是一个突破，因为：

  • 集中化和官方化：借助 ecs@mappings，我们现在有了 ECS 映射的官方定义。
  • 开箱即用的功能：ECS 映射随时可用，减少了对额外导入或引用的需求。
  • 简化维护：由于 Elasticsearch 本身的模板保持最新，因此手动跟进 ECS 变化的需求已经减少。

增强一致性和可靠性

借助 ecs@mappings，ECS 映射成为唯一真实来源。这种统一方法意味着集成过程中数据流的差异更少，一致性更高。

社区用户如何受益

社区用户将从采用 ecs@mappings 中获益良多。以下是主要优势：

  1. 减少配置麻烦：无论你是高级用户还是刚刚入门，简化的设置意味着更少的配置步骤和更少的错误机会。
  2. 提高数据完整性：由于 ecs@mappings 确保字段定义准确且最新，因此可以轻松维护数据完整性。
  3. 更好的性能：维护和引用 ECS 字段的开销更少，你的 Elasticsearch 操作运行得更顺畅。
  4. 增强的文档和可发现性：随着我们标准化 ECS 映射，文档可以集中化，使用户更容易发现和理解 ECS 字段。

让我们探索 ecs@mappings 组件模板如何帮助用户实现这些好处。

减少配置麻烦

现代 Elasticsearch 版本附带开箱即用的完整 ECS 字段支持（有关具体版本，请参阅后面的“要求”部分）。

例如，安装在受支持的 Elasticsearch 集群上的自定义 AWS 日志集成已在其索引模板中包含 ecs@mappings 组件模板：

GET _index_template/logs-aws_logs.generic
{
  "index_templates": [
    {
      "name": "logs-aws_logs.generic",
      ...,
        "composed_of": [
          "logs@settings",
          "logs-aws_logs.generic@package",
          "logs-aws_logs.generic@custom",
          "ecs@mappings",
          ".fleet_globals-1",
          ".fleet_agent_id_verification-1"
        ],
    ...

无需导入或定义任何 ECS 字段。

改进数据完整性

ecs@mappings 组件模板支持所有现有的 ECS 字段。如果你在文档中使用任何 ECS 字段，它将准确具有预期的类型。

为了确保 ecs@mappings 始终与 ECS 存储库保持同步，我们设置了每日自动测试，以确保组件模板支持所有字段。

性能更佳

紧凑定义

ECS 字段定义非常紧凑；在撰写本文时，它只有 228 行，并且支持所有 ECS 字段。要了解更多信息，请参阅 ecs@mappings 组件模板源代码。

它依赖于命名约定并使用动态模板来实现这种紧凑性。

惰性映射 – lazy mapping

得益于动态模板，Elasticsearch 仅将现有文档字段添加到映射中。惰性映射将内存开销保持在最低水平，从而提高集群性能并使字段建议更具相关性。

增强的文档和可发现性
所有 Elastic Agent 集成都将迁移到 ecs@mappings 组件模板。这些集成不再需要添加和维护 ECS 字段映射，并且可以引用官方 ECS 字段参考或 Git 存储库中的 ECS 源代码：https://github.com/elastic/ecs/。

增强的文档和可发现性

所有 Elastic Agent 集成都迁移到 ecs@mappings 组件模板。这些集成不再需要添加和维护 ECS 字段映射，并且可以引用官方 ECS 字段参考或 Git 存储库中的 ECS 源代码：https://github.com/elastic/ecs/。

入门

要求

要利用 ecs@mappings 组件模板，请确保以下堆栈版本：

  • 8.9.0：如果你的数据流使用日志索引模板或你定义索引模板。
  • 8.13.0：如果你的数据流使用 Elastic Agent 集成的索引模板。

示例

我们将使用自定义 AWS 日志集成向你展示 ecs@mapping 如何处理任何开箱即用的 ECS 字段的映射。

假设你想使用自定义 AWS 日志集成提取以下日志事件：

{
  "@timestamp": "2024-06-11T13:16:00+02:00", 
  "command_line": "ls -ltr",
  "custom_score": 42
}

Dev Tools

Kibana 提供了一个出色的工具来试验 Elasticseatch API，即Dev Tools console.。使用开发工具，用户可以快速、无阻碍地运行所有 API 请求。

要打开 Dev Tools：

  • 打开 Kibana
  • 选择Management > Dev Tools > Console

Elasticsearch 版本

在 8.13 之前的 Elasticsearch 版本中，自定义 AWS 日志集成具有以下索引模板：

GET _index_template/logs-aws_logs.generic
{
  "index_templates": [
    {
      "name": "logs-aws_logs.generic",
      "index_template": {
        "index_patterns": [
          "logs-aws_logs.generic-*"
        ],
        "template": {
          "settings": {},
          "mappings": {
            "_meta": {
              "package": {
                "name": "aws_logs"
              },
              "managed_by": "fleet",
              "managed": true
            }
          }
        },
        "composed_of": [
          "logs-aws_logs.generic@package",
          "logs-aws_logs.generic@custom",
          ".fleet_globals-1",
          ".fleet_agent_id_verification-1"
        ],
        "priority": 200,
        "_meta": {
          "package": {
            "name": "aws_logs"
          },
          "managed_by": "fleet",
          "managed": true
        },
        "data_stream": {
          "hidden": false,
          "allow_custom_routing": false
        }
      }
    }
  ]
}

如你所见，它不包含 ecs@mappings 组件模板。

如果我们尝试索引测试文档：

POST logs-aws_logs.generic-default/_doc
{
  "@timestamp": "2024-06-11T13:16:00+02:00", 
  "command_line": "ls -ltr",
  "custom_score": 42
}

数据流将具有以下映射：

GET logs-aws_logs.generic-default/_mapping/field/command_line
{
  ".ds-logs-aws_logs.generic-default-2024.06.11-000001": {
    "mappings": {
      "command_line": {
        "full_name": "command_line",
        "mapping": {
          "command_line": {
            "type": "keyword",
            "ignore_above": 1024
          }
        }
      }
    }
  }
}

GET logs-aws_logs.generic-default/_mapping/field/custom_score
{
  ".ds-logs-aws_logs.generic-default-2024.06.11-000001": {
    "mappings": {
      "custom_score": {
        "full_name": "custom_score",
        "mapping": {
          "custom_score": {
            "type": "long"
          }
        }
      }
    }
  }
}

这些映射与 ECS 不一致，因此用户和开发人员必须维护它们。

Elasticsearch 版本 >= 8.13

在 Elasticsearch 版本等于或更新至 8.13 上，自定义 AWS 日志集成具有以下索引模板：

GET _index_template/logs-aws_logs.generic
{
  "index_templates": [
    {
      "name": "logs-aws_logs.generic",
      "index_template": {
        "index_patterns": [
          "logs-aws_logs.generic-*"
        ],
        "templatgcodete": {
          "settings": {},
          "mappings": {
            "_meta": {
              "package": {
                "name": "aws_logs"
              },
              "managed_by": "fleet",
              "managed": true
            }
          }
        },
        "composed_of": [
          "logs@settings",
          "logs-aws_logs.generic@package",
          "logs-aws_logs.generic@custom",
          "ecs@mappings",
          ".fleet_globals-1",
          ".fleet_agent_id_verification-1"
        ],
        "priority": 200,
        "_meta": {
          "package": {
            "name": "aws_logs"
          },
          "managed_by": "fleet",
          "managed": true
        },
        "data_stream": {
          "hidden": false,
          "allow_custom_routing": false
        },
        "ignore_missing_component_templates": [
          "logs-aws_logs.generic@custom"
        ]
      }
    }
  ]
}

logs-aws_logs.generic 的索引模板现在包含 ecs@mappings 组件模板。

如果我们尝试索引测试文档：

POST logs-aws_logs.generic-default/_doc
{
  "@timestamp": "2024-06-11T13:16:00+02:00", 
  "command_line": "ls -ltr",
  "custom_score": 42
}

数据流将具有以下映射：

GET logs-aws_logs.generic-default/_mapping/field/command_line
{
  ".ds-logs-aws_logs.generic-default-2024.06.11-000001": {
    "mappings": {
      "command_line": {
        "full_name": "command_line",
        "mapping": {
          "command_line": {
            "type": "wildcard",
            "fields": {
              "text": {
                "type": "match_only_text"
              }
            }
          }
        }
      }
    }
  }
}

GET logs-aws_logs.generic-default/_mapping/field/custom_score
{
  ".ds-logs-aws_logs.generic-default-2024.06.11-000001": {
    "mappings": {
      "custom_score": {
        "full_name": "custom_score",
        "mapping": {
          "custom_score": {
            "type": "float"
          }
        }
      }
    }
  }
}

在 Elasticsearch 8.13 中，command_line 和 custom_score 等字段从 ECS 中开箱即用地获取其定义。

这些映射与 ECS 保持一致，因此用户和开发人员无需维护它们。这同样适用于 Elastic Common Schema 中的所有数百个字段定义。你可以通过在数据流中包含一个 200 行的组件模板来实现这一点。

注意事项

ecs@mappings 组件模板处理数据类型的某些方面值得一提。

ECS 类型不强制执行

ecs@mappings 组件模板不包含那些动态映射已使用正确字段类型的 ECS 字段映射。因此，如果发送了类型兼容但不正确的字段值，Elasticsearch 不会对该值进行类型转换。

例如，如果你发送带有 faas.coldstart 字段（在 ECS 中定义为布尔值）的以下文档：

{
  "faas.coldstart": "true"
}

Elasticsearch 会将 faas.coldstart 映射为 keyword，而不是布尔值。因此，你需要确保输入到 Elasticsearch 的值使用正确的 JSON 字段类型，具体取决于它们在 ECS 中的定义方式。

这是tgcode拥有紧凑高效的 ecs@mappings 组件模板的权衡。它还允许在处理 ECS 和自定义字段的混合时实现更好的兼容性，因为如果类型与 ECS 中定义的类型不一致，文档不会被拒绝。

结论

ecs@mappings 的引入标志着 Elasticsearch 中 ECS 映射管理的重大改进。通过集中和简化这些定义，我们可以确保更高的一致性、减少维护并提高整体性能。

无论你是集成开发人员还是社区用户，迁移到 ecs@mappings 都代表着朝着更高效、更可靠的 Elasticsearch 操作迈出了一步。随着我们继续吸收反馈并改进我们的工具，你使用 Elasticsearch 的旅程只会变得更加顺利和更有回报。

加入对话

你对 ecs@mappings 有疑问或反馈吗？在我们的社区讨论论坛和 Slack 实例上向我们乐于助人的用户社区发帖并分享你的经验。你的意见对于帮助我们为整个社区微调这些进步非常宝贵。

祝你映射愉快！

原文：Future-proof your logs with ecs@mappings template — Elastic Observability Labs

文章来源于互联网:Observability：使用 ecs@mappings 模板保证你的日志面向未来

相关推荐: Observability：OpenTelemetry Elastic 分发简介

作者：来自 ElasticAlexander Wert•Miguel Luna•Bahubali Shetti Elastic 自豪地推出了 Elastic Distributions of OpenTelemetry (EDOT)，其中包含 Elastic …

Tags: ,