跳转到主要内容

插件开发最佳实践

我们整理了一份关于构建和发布高质量 Grafana 插件的最佳实践列表，这些实践我们发现非常有用。在构建您自己的插件时参考它们以获得最佳结果。

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

一般​

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

面板插件​

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

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

  • 记录dataframe模式 - 考虑在README中记录插件的模式（预期字段、字段类型、字段名称的命名约定等）。

数据源插件​

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

前端（仅）插件​

  • 仅在前端运行的数据源通常使用Grafana代理来访问外部服务 - 这是添加查询支持的一种简单方法，而且不需要Go语言知识。然而，对于一些用例，编写后端插件是必要的。有关这些用例的更多信息，请参阅后端插件。

后端插件​

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

应用插件​

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

发布插件​

  • 添加 GitHub 徽章 - 按照以下步骤操作以帮助用户通过 GitHub 徽章找到您的插件：这些步骤。
  • 添加工作流程自动化 - 如果您的插件可在 GitHub 上使用，请考虑将用于插件开发的 GitHub 工作流程 添加到您的仓库中。