跳转到主内容

插件开发最佳实践

我们已经汇总了我们发现对构建和发布高质量的 Grafana 插件有益的实践经验列表。在构建您自己的插件时，请参考它们以获得最佳结果。

列表中缺少什么？ 告诉我们。

通用​

  • 验证您的数据源或应用插件是否可以配置 - 更多信息请参阅 配置。
  • 在您的数据源或应用插件中包含默认仪表板 - 更多信息请参阅 仪表板绑定。
  • 确保 Grafana 的最低版本正确 - 确保 plugin.json 中的 grafanaDependency 指向插件完全支持的 Grafana 的最早版本。
  • 不要暴露敏感信息 - 由于安全原因，避免暴露敏感信息，例如机密信息。确保正确使用日志级别，避免过多的记录，并永远不要记录凭据或其他敏感信息。
  • 避免在插件中使用 console.log - 控制台消息通常是用于调试目的的，因此不适用于发送给客户端。
  • 添加 linting 和自动完成 - 通过添加类似于 这个片段 的代码到 VS Code 中来为您的插件添加代码质量分析和自动补全功能。
  • 包含一个高质量的 README - 帮助用户深入了解如何配置和使用您的插件，但不要让它成为必读内容。您希望用户在没有查阅文档的情况下，可以通过直觉理解您的插件。
  • 允许渐进式学习 - 使用开关或分类隐藏高级选项，并让用户在准备好的时候了解高级功能。
  • 获取测试用户 - 让目标受众的用户在您提交插件之前试用您的插件。在发布之前，获取反馈以帮助改进您的插件。

面板插件​

  • 不要存储或使用凭证 - 面板插件没有一种安全存储凭证的方法。如果您的插件需要使用凭证，请考虑使用数据源或应用插件代替，并使用面板插件来显示数据源返回的信息。

  • 考虑创建自定义选项 - 如果默认面板选项不适合您想要提供给用户的内容，请使用 自定义选项。

  • 记录dataframe架构 - 请考虑在README中记录插件架构（预期字段、字段类型、字段名称命名约定等）（文档插件架构）。

数据源插件​

  • 如果您的插件需要存储凭证，请使用secureJsonData代替jsonData - 前者是在停机时加密的，而后者没有。有关更多信息，请参阅安全JSON数据。
  • 实现查询构建器 - 这对不熟悉数据源查询语言的用户非常有用。例如，请参阅微软SQL服务器查询构建器，它有助于编写该服务所需的SQL查询。
  • 为您的插件添加健康检查 - 健康检查 用于验证数据源是否正常运行。实现方式取决于插件是否有后端。请参阅前端和后端的健康检查示例（健康检查）。对于 backend 的情况，只要它从 @grafana/runtime 扩展了 DataSourceWithBackend 类，则不需要修改其前端代码。
  • 添加仪表板变量支持 - 仪表板（或模板）变量允许用户创建动态仪表板。在您的插件中添加对变量的支持有两个方面。第一个是允许查询您的数据源并将返回值用作变量。第二个是替换其他查询中现有的变量。有关更多信息，请参阅我们的文档。在选择 "所有值" 时请注意，可能需要特定的逻辑来连接变量值。
  • 添加注释支持 - 注释允许用户将其仪表板中添加上下文信息，并且可以使用查询来定义它。有关更多信息，请参阅启用注释。
  • 练习良好的前端设计 - 在构建前端组件时，请确保使用Grafana组件作为基础，并遵循 Saga设计系统。
  • 添加查询编辑器帮助 - 查询编辑器可能很复杂，为用户提供帮助很有用。有关更多信息，请参阅添加查询编辑器帮助。
  • 跳过隐藏或空查询 - 这可以避免执行不必要的或错误的查询。仅实现DataSourceWithBackend的数据源只需要实现filterQuery方法。请参考这个示例。
  • 指定默认查询 - 默认查询可以帮助用户了解如何编写插件查询。请参考这个示例。

前端（仅）插件​

  • 仅在前端运行的数据源通常使用Grafana 代理来访问外部服务 - 这是一种简单的方式来支持插件中的查询，而且不需要Golang知识。然而，有些情况下必须编写后端插件。有关详细信息，请参阅后端插件。

后端插件​

  • 添加对警报的支持 - 后端插件具有内置的Grafana 警报支持，但需要启用此支持。只需将 "alerting": true 添加到您的 plugin.json 文件。
  • 使用 CallResourceHandler 接口来处理自定义 HTTP 请求。更多信息请参阅 资源处理程序。例如，在提供查询构建器时很有用，如这个示例 所示。
  • 为您的数据源添加日志、指标和追踪。这将使插件开发人员和 Grafana 运维人员更容易诊断和解决问题。更多信息请参阅我们的 文档。
  • 保持已缓存的连接 - 这是一个重要的优化。更多信息请参阅我们的 文档 和一个 示例。
  • 添加宏支持 - 宏类似于变量，但它们通常在后端评估，可以根据环境数据（如当前时间选择）返回值。例如，在动态时间段内评估警报时非常有用。通常使用语法 $__macroName （例如，$__timeFilter）定义。有关如何实现支持的示例，请参阅这个示例。插件 SDK 中提供了一些预定义的宏，位于 宏 包中。
  • 对于 SQL 数据源，请参阅 SDK 中的sqlutil 包 - 它包括多个辅助程序，用于处理 SQL 数据源，例如数据帧转换、默认宏等。此外，请考虑使用 sqlds 包，该包大大简化了 SQL 数据源的实现。
  • 不要使用本地文件系统 - 不同的插件共享相同的环境。出于安全原因，插件不应依赖于本地文件。
  • 不要使用环境变量 - 环境变量也是一个安全风险，应予以避免。对于针对特定数据源的配置，请使用 plugin.json 文件中的 jsonData 或 secureJsonData 字段。如果需要对在数据源之间共享的插件进行配置，请使用 plugin 配置。
  • 插件不应在后台执行任意代码 - 这同样是一个安全风险，应予以避免。如果您的插件需要执行代码，请提供允许的命令列表，并在执行之前验证输入。
  • 通常，任何错误都应该用 error 级别记录。
  • 不要使用 info 级别：请使用 debug 级别。
  • 启用并发查询执行 - 这允许您并行运行多个查询。欲了解更多信息，请参阅我们的文档。

应用插件​

  • 指定应用的主页 - 如果您的应用定义了多个页面，请确保选择一个默认页面，该页面将用作插件的登录页面。
  • 对您的应用进行代码拆分 - 如果您的应用包含多个页面，请确保使用代码拆分技术来提高前端加载性能。默认情况下，Webpack 在构建期间如果任何前端资源大于 250kb，则会在终端显示警告。有关更多信息，请参阅以下链接
  • 要生成动态应用，请考虑使用 Grafana Scenes。
  • 考虑贡献一个 UI 扩展 - UI 扩展可以帮助用户在上下文中发现您的应用并继续给定的工作流程。此外，如果您的应用提供其他应用可以使用的上下文，则创建一个扩展点，允许这些应用这样操作，而无需在您的应用中进行任何进一步更改。

发布插件​