文档 插件 用于 Grafana 的 Snowflake 数据源

用于 Grafana 的 Snowflake 数据源

Snowflake 数据源插件允许您在 Grafana 中查询和可视化 Snowflake 数据指标。

要求

此插件有以下要求

• 已授予适当角色的Snowflake 用户。
  • 此数据源不需要特定的角色。
  • Snowflake 用户的角色决定了该用户可以访问哪些表。为了查询您的数据，请确保您的用户拥有适当的角色。
• 以下账户类型之一
• 任何免费或付费的Grafana Cloud 计划或激活的本地部署 Grafana Enterprise 许可证。签约的 Cloud 客户应参考其协议。

安装 Snowflake 数据源插件

要安装数据源，请参阅安装

配置 Snowflake

配置 Snowflake 数据源需要一个具有用户名和密码的 Snowflake 用户。

Grafana 建议为该数据源创建一个具有有限权限的新用户。

创建用户

为了连接到 Snowflake，您必须创建一个用户或使用现有用户进行身份验证。该用户将运行从 Grafana 发送的所有查询。

如果您希望不同的用户运行不同的查询/工作负载，则应创建多个具有不同设置的 Snowflake 数据源。

要在 Snowflake 中创建用户，您必须登录到您的 Snowflake 实例并运行CREATE USER 命令。

授予角色

创建 Snowflake 用户后，必须使用GRANT ROLE 命令授予用户一个角色。向用户授予角色允许该用户执行该角色允许的操作。

此角色定义了用户可以访问哪些仓库和表。

从 Snowflake 获取账户详细信息

如果您已有可用的 Snowflake 账户，您可以通过访问您的仪表盘左下角，在您的账户名称下点击“View account details”（查看账户详细信息），获取连接 Snowflake 所需的信息。您可以从那里获取要在数据源配置中使用的账户名称、区域和用户名。

在 Grafana 中配置数据源

这些连接设置与通过 SnowSQL 连接中使用的设置相同

添加数据源，填写以下字段：

密钥对身份验证

为了增强安全性，密钥对身份验证可作为基本身份验证的替代方案。您可以按照参考的Snowflake 文档生成公钥和私钥。使用密钥对身份验证时，务必更新 Snowflake 中的 rsa_public_key 并在数据源配置中提供用户名和未加密私钥。

OAuth 身份验证

您可以使用 OAuth 身份验证代表登录到 Grafana 的用户将令牌传递给 Snowflake。下面提供了一些关于使用 Azure AD 作为 OAuth 提供程序的说明。

1. 使用 Azure AD设置 OAuth

2. 按照此处的说明更新您在步骤 1 中创建的应用，并为 Snowflake 添加客户端应用。

3. 更新您在 grafana.ini 文件中步骤 1 中创建的 scopes。添加您在步骤 2 中创建的 api。scopes 看起来应该像这样

复制

scopes = api://8c1a0b1c-6bb0-4190-a730-8a1c34237619/session:role-any openid email profile offline_access

4. 重启 Grafana 并使用 Azure AD 登录。创建一个 Snowflake 数据源，身份验证类型选择 OAuth，并切换 Forward OAuth Identity。点击保存并测试以确认令牌正在传递且有效。

如果我收到无效令牌错误怎么办？步骤 2 中的说明提供了验证令牌的方法，这将提供更多关于令牌无效原因的信息。

复制

select system$verify_external_oauth_token('<ACCESS_TOKEN>');

附加链接

Azure OAuth。按照“代表用户”流程操作：https://docs.snowflake.com/en/user-guide/oauth-azure 使用 Postman 测试：https://community.snowflake.com/s/article/How-To-Configure-Postman-for-testing-SQL-API-with-OAuth 设置 Snowflake 安全集成：https://community.snowflake.com/s/article/Create-Security-Integration-User-To-Use-With-OAuth-Client-Token-With-Azure-AD

使用 Provisioning 配置数据源

可以使用 Grafana 的 Provisioning 系统通过配置文件配置数据源。您可以在Provisioning 文档页面上了解有关其工作原理以及可以为数据源设置的所有设置的更多信息

示例

yaml 复制

datasources:
  - name: Snowflake
    type: grafana-snowflake-datasource
    access: proxy
    basicAuth: false
    editable: true
    enabled: true
    jsonData:
      account: xyz123.east-us-2.azure
      username: grafana-user
      authType: password
      timeInterval: 10s
      defaultQuery: SELECT \n\t $__timeGroup(<time_column>, $__interval) as time,\n\t <value_column>\n FROM <metric_table>\n WHERE $__timeFilter(time)
      defaultVariableQuery: SELECT DISTINCT <column_name> FROM <metric_table> LIMIT 1000
      defaultInterpolation: '' # Refer: https://grafana.org.cn/docs/grafana/latest/variables/advanced-variable-format-options/
    secureJsonData:
      password: grafana-password
  - name: Snowflake Billing Data
    type: grafana-snowflake-datasource
    access: proxy
    basicAuth: false
    editable: true
    enabled: true
    jsonData:
      account: xyz123.us-east1.gcp
      username: grafana-admin-user
      database: snowflake
      role: ACCOUNTADMIN
      timeInterval: 10s
      defaultQuery: SELECT \n\t $__timeGroup(<time_column>, $__interval) as time,\n\t <value_column>\n FROM <metric_table>\n WHERE $__timeFilter(time)
      defaultVariableQuery: SELECT DISTINCT <column_name> FROM <metric_table> LIMIT 1000
      defaultInterpolation: sqlstring # Refer: https://grafana.org.cn/docs/grafana/latest/variables/advanced-variable-format-options/
    secureJsonData:
      password: grafana-admin-password

查询数据源

提供的查询编辑器是标准的 SQL 查询编辑器。Grafana 包含一些宏，有助于编写更复杂的时间序列查询。

宏

示例

表格可视化

Snowflake 中的大多数查询最适合用表格可视化表示。任何查询都将在表格中显示数据。如果可以查询，就可以放入表格中。

此示例返回用于表格可视化的结果

sql 复制

SELECT {column_1}, {column_2} FROM {table};

时间序列 / 图形可视化

对于时间序列 / 图形可视化，有一些要求

• 必须选择一个 date 或 datetime 类型的列
• date 列必须按升序排列（使用 ORDER BY column ASC）
• 还必须选择一个数值列

为了生成更合理的图形，请务必使用 $__timeFilter 和 $__timeGroup 宏。

时间序列查询示例

sql 复制

SELECT
  avg(execution_time) AS average_execution_time,
  $__timeGroup(start_time, $__interval),
  query_type
FROM
  account_usage.query_history
WHERE
  $__timeFilter(start_time)
group by
  query_type,start_time
order by
  start_time,query_type ASC;

检查查询

由于 Grafana 支持 Snowflake 不支持的宏，您可以在查询检查器中看到完全渲染的查询，可以直接复制/粘贴到 Snowflake 中。要查看完整的插值查询，请点击查询检查器按钮，完整查询将显示在“查询”选项卡下。如果需要进一步调试，请查看 Snowsight 中的“查询历史记录”页面。在此处了解更多信息：https://docs.snowflake.com/en/user-guide/ui-snowsight-activity

模板和变量

要添加新的 Snowflake 查询变量，请参阅添加查询变量。使用您的 Snowflake 数据源作为以下可用查询的数据源

从 Snowflake 表中查询的任何值都可以用作变量。请务必避免选择过多的值，因为这可能会导致性能问题。

如果变量查询返回两列，第二列的值将用作显示值

使用变量

创建变量后，您可以通过使用变量语法在 Snowflake 查询中使用它。有关变量的更多信息，请参阅模板和变量。

在使用查询中的变量时，您可以选择设置插值格式。您还可以在数据源配置中配置默认的插值格式。

单值变量

如果变量返回单个值，您可以使用以下格式之一。以下示例假设您已将 sqlstring 设置为默认插值，并且您有两个名为 queryTypeSingle 和 limit 的变量。它们的值分别为 SELECT 和 2。

sql 复制

SELECT query_type FROM account_usage.query_history WHERE query_type = ${queryTypeSingle} Limit ${limit:raw}

将转换为

sql 复制

SELECT query_type FROM account_usage.query_history WHERE query_type = 'SELECT' Limit 10

默认变量插值类型的设置是在 1.2 版本中引入的。从该版本开始，您可以将默认插值类型设置为 sqlstring

在此插件的 1.2 版本之前，或者如果您使用 none 作为默认插值类型，相同的查询必须按以下方式编写

sql 复制

SELECT query_type FROM account_usage.query_history WHERE query_type = '${queryTypeSingle}' Limit ${limit:raw}

使用 sqlstring 插值的多值变量

当使用返回多个选项的变量时，您可以使用以下方法使用它。以下示例假设您已将 sqlstring 设置为默认插值，并且您有两个名为 queryTypeMulti 和 limit 的变量。它们的值分别为 CREATE,SELECT 和 2。

sql 复制

SELECT query_type FROM account_usage.query_history WHERE query_type in (${queryTypeMulti}) Limit ${limit:raw}

将转换为

sql 复制

SELECT query_type FROM account_usage.query_history WHERE query_type in ('CREATE','SELECT') Limit 10

使用 regex 的多值变量

要使用具有多个值的变量，您可以使用regex 修改选项以及regexp Snowflake 函数。例如：${variable:regex}

例如，此查询将仅使用在 queryType 变量中选择的 Query Types 进行过滤

sql 复制

...
  AND query_type regexp '${queryType:regex}'
...

此查询转换为

sql 复制

...
  AND query_type regexp '(DESCRIBE|CREATE_USER|DROP|TRUNCATE_TABLE|ALTER)'
...

将数据可视化为日志

在查询中选择日志格式后，您可以在 Explorer 中的日志查看器中可视化数据。使用日志格式查询时，您的查询应至少包含一个时间列和一个字符串/内容列。您还可以选择查询中包含第三列，名为 level，用于设置特定行的日志级别。支持的日志级别及其关键字可在Grafana 日志集成文档网站中找到。如果查询返回任何额外的列，它们将被视为日志中的额外字段/检测到的字段。

例如，以下是有效的日志查询。

sql 复制

SELECT 'hello foo'  as "content", (timestamp '2021-12-31') as "start_time", 'warn'  as "level" UNION
SELECT 'hello bar'  as "content", (timestamp '2021-12-30 14:12:59') as "start_time", 'error' as "level" UNION
SELECT 'hello baz'  as "content", (timestamp '2021-12-30') as "start_time", 'warn'  as "level" UNION
SELECT 'hello qux'  as "content", (timestamp '2021-12-29') as "start_time", 'info'  as "level" UNION
SELECT 'hello world' as "content", (timestamp '2021-12-28') as "start_time", 'unknown'  as "level" UNION
SELECT 'hello user' as "content", (timestamp '2021-12-27') as "start_time", 'info'  as "level"

为 Snowflake 导入仪表盘

捆绑的 Snowflake 仪表盘需要一个具有 ACCOUNTADMIN 角色的数据源来查看账单数据。在 Provisioning 部分有一个示例。

按照这些说明导入仪表盘。

导入的仪表盘可在 Configuration（配置）> Data Sources（数据源）> 选择您的 Snowflake 数据源 > 选择 Dashboards（仪表盘）选项卡中找到，以查看可用的预制仪表盘。

充分利用此插件

• 添加注释。
• 配置和使用模板和变量。
• 添加转换。
• 使用Explorer 中的日志。
• Trace Frame 数据结构.
• 设置告警；请参阅告警概述。

了解更多

• 密钥对身份验证
• 在 Snowflake 中使用查询历史记录监控查询活动