文档指南

每个集成文档的目标是：

• 描述该集成提供的优势，以及 Elastic 如何帮助解决不同的用例。

• 指定要求，包括系统兼容性、第三方产品支持的版本、所需权限等。

• 提供所收集字段的列表，包括每个字段的数据和指标类型。这些信息在评估集成、解读所收集的数据或排查问题时非常有用。

• 每个集成文档应包含以下部分：

  • 概述
  • 此集成收集哪些数据？
  • 使用此集成需要满足哪些条件？
  • 如何部署此集成？
  • 故障排除
  • 性能与扩展
  • 参考

文档文件编写为 _dev/build/docs/*.md 下的模板，并在 elastic-package build 期间进行处理，以在 docs/ 中生成最终文档。

关键注意事项

• Markdown 语法： 文档文件使用标准 Markdown 语法。
• 模板函数： 使用 {{ fields "data_stream" }} 和 {{ event "data_stream" }} 等模板函数自动生成字段表和示例事件。请参阅 模板函数 获取完整列表。
• 链接到 开源搜索教程： 使用 {{ url "link-id" "Caption" }} 函数创建指向 开源搜索教程的链接。这确保了在文档 URL 发生变更时链接依然有效。可用的链接 ID 定义在 links_table.yml 中。

概述 (Overview) 部分解释了该集成的功能、主要用例，并包含以下小节：

• 兼容性

  指出该集成与哪些版本的第三方软件、部署方法或架构兼容。

• 工作原理

  提供有关集成如何收集数据的概览。

此部分应包括：

• 该集成所收集的数据类型
• 支持的使用场景

此部分说明使用此集成所需的内容

• Elastic 先决条件（例如，自托管或 Cloud 部署）
• 第三方软件的凭据或管理员帐户

此部分参考可观测性 (Observability) 入门指南 以获取通用的分步说明，还应包含以下额外的设置说明：

上线与配置

• 如何安装 Agent 并部署此集成？
• 哪些 Agent 部署方法是可接受的？Fleet？还是独立式 (Standalone)？
• 此集成是否支持无 Agent 部署？
• 在集成部署期间必须配置哪些数据、输入、字段或身份验证令牌？它们应该具有什么值？

验证

• 如何测试集成是否正常工作？如果适用，请包括示例命令或测试文件。

故障排除部分应包括针对每种输入类型的详细信息，以及解决部署此集成时遇到的常见问题的一般指导。如果可能，请链接到第三方软件提供的故障排除文档。

根据输入，此部分应解释如何扩展该集成以及应使用哪种最佳扩展架构，包括基准测试建议。

可以有任意数量的参考部分，例如：

• ECS 字段参考
• 指标参考
• 日志参考
• 此集成中使用的输入
• 用于收集数据的 API
• 更新日志

每个参考部分应包含有关以下内容的详细信息：

• 集成内支持的日志或指标类型列表，以及指向相关第三方文档的链接。
• （可选）JSON 格式的示例事件。
• 用于日志、指标和事件的导出字段及其真实类型（例如 counters、gauges、histograms 与 longs 和 doubles）。字段应使用 Fine-tune the integration 中的说明生成。
• 机器学习 (ML) 模块作业。