Snowflake 数据源用于 Grafana
Snowflake 数据源插件允许您在 Grafana 中查询和可视化 Snowflake 数据指标。
要求
此插件有以下要求
- 创建具有相应角色的Snowflake 用户。
- 此数据源不需要特定的角色。
- Snowflake 用户的角色是允许该用户访问表的原因。为了查询您的数据,请确保您的用户具有适当的角色。
- 以下账户类型之一
- 任何免费或付费的Grafana Cloud 计划或已激活的本地部署 Grafana 企业许可。合同云客户应参考其协议。
安装 Snowflake 数据源插件
要安装数据源,请参阅安装
配置 Snowflake
配置 Snowflake 数据源需要具有用户名和密码的 Snowflake 用户。
Grafana 建议为此数据源创建一个具有有限权限的新用户。
创建用户
为了连接到 Snowflake,您必须创建用户或使用现有用户进行身份验证。此用户将运行从 Grafana 发出的所有查询。
如果您希望不同用户运行不同的查询/工作负载,那么您应该创建多个具有不同设置的 Snowflake 数据源。
要在 Snowflake 中创建用户,您必须登录到您的 Snowflake 实例并运行CREATE USER 命令。
授予角色
现在 Snowflake 用户已创建,必须使用 GRANT ROLE 命令授予用户角色。向用户授予角色允许用户执行该角色允许的操作。
此角色定义了用户可以访问哪些仓库和表。
在 Grafana 中配置数据源
这些连接设置与通过 SnowSQL 连接时使用的设置相同
通过填写以下字段添加数据源
字段 | 描述 |
---|---|
名称 | 为此特定的 Snowflake 数据源指定一个名称 |
账户 | 账户是 Snowflake 分配的 Snowflake 账户的名称。在分配账户后从 Snowflake 收到的 URL 中,账户名称是位于 snowflakecomputing.com 左侧的 整个 字符串。如果 Snowflake 实例不在 us-west-2 上,则必须在账户名称中包含区域。例如:xyz123.us-east-1 如果 Snowflake 实例不在 Amazon Web Services 上,则必须在账户名称中也包含平台。例如:xyz123.us-east-1.gcp |
区域 | 已弃用,由账户取代。区域指定 Snowflake 实例所在区域 |
用户名 | 将查询 Snowflake 的账户的用户名 |
身份验证类型 | 身份验证类型。您可以使用密码身份验证或密钥对身份验证 |
密码 | 将查询 Snowflake 的账户的密码 |
私钥 | 如果您喜欢使用基于密钥对的身份验证,请在字段中输入您的 未加密 私钥。 |
角色 | 此选项允许用户使用非用户默认角色的角色连接到 Snowflake 实例。必须使用 GRANT ROLE 命令授予用户角色,以便可以假定该角色。 |
仓库 | 默认用于查询的仓库 |
数据库 | 默认用于查询的数据库 |
模式 | 默认用于查询的模式 |
时间间隔 | 可选。用于 $__interval 和 $__interval_ms 宏的下限。如果留空,默认将使用 10s |
默认查询 | 可选。向面板添加新的雪花查询时使用的默认查询 |
默认变量查询 | 可选。向仪表板变量添加新的雪花查询时使用的默认查询 |
密钥对认证
为了增强安全性,可以使用密钥对认证作为基本认证的替代方案。您可以通过参考Snowflake 文档生成公钥和私钥。在密钥对认证时,重要的是更新 Snowflake 中的 rsa_public_key
,并在数据源配置中提供用户名和未加密的私钥。
OAuth 认证
您可以使用 OAuth 认证代表已登录 Grafana 的用户将令牌传递到 Snowflake。以下提供了一些使用 Azure AD 作为 OAuth 提供者的说明。
使用 Azure AD 设置 OAuth
按照这里的说明更新步骤 1 中创建的应用程序,并添加 Snowflake 的客户端应用程序。
更新步骤 1 中在您的 grafana.ini 文件中创建的 scopes。添加步骤 2 中创建的 api。 scopes 应看起来像以下内容:
scopes = api://8c1a0b1c-6bb0-4190-a730-8a1c34237619/session:role-any openid email profile offline_access
- 重启 Grafana 并使用 Azure AD 登录。创建一个使用认证类型:OAuth 的 Snowflake 数据源,并切换 转发 OAuth 身份。 保存并测试 以确认令牌正在传递且有效。
如果收到无效令牌错误怎么办?步骤 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
使用配置文件配置数据源
您可以使用 Grafana 的配置系统使用配置文件来配置数据源。您可以在配置文件配置数据源页面上阅读有关其工作原理以及您可以设置的所有数据源设置的更多信息。
示例
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 包含一些宏,可以帮助编写更复杂的时序查询。
宏
宏 | 描述 | 输出示例 |
---|---|---|
$__timeFilter(column) | $__timeFilter 通过面板时间范围过滤 column 。 column 必须有非时区的字段。 | CONVERT_TIMEZONE('UTC', 'UTC', time) < '2017-07-18T11:15:52Z' AND CONVERT_TIMEZONE('UTC', 'UTC', time) > '2017-07-18T11:15:52Z |
$__timeFilter(column, timezone) | $__timeFilter 通过面板时间范围过滤 column ,并将 UTC 转换为 timezone 。 column 必须包含无时区的字段。 | CONVERT_TIMEZONE('UTC', 'America/New_York', time) < '2017-07-18T11:15:52Z' AND CONVERT_TIMEZONE('UTC', 'America/New_York', time) > '2017-07-18T11:15:52Z |
$__timeTzFilter(column) | $__timeTzFilter 通过面板时间范围过滤 column 。 column 应包含包含时区的字段。 | CONVERT_TIMEZONE('UTC', time) < '2017-07-18T11:15:52Z' AND CONVERT_TIMEZONE('UTC', time) > '2017-07-18T11:15:52Z |
$__timeTzFilter(column, timezone) | $__timeTzFilter 通过面板时间范围过滤 column 并将当前时区转换为 timezone 。 column 应包含包含时区的字段。 | CONVERT_TIMEZONE('America/New_York', time) < '2017-07-18T11:15:52Z' AND CONVERT_TIMEZONE('America/New_York', time) > '2017-07-18T11:15:52Z |
$__timeGroup(column, $__interval) | $__timeGroup 按间隔分组时间戳,使图表上每 $__interval 只有一个点 | TIME_SLICE(TO_TIMESTAMP(created_ts), 1, 'HOUR', 'START') |
$__timeGroup(column, $__interval, timezone) | $__timeGroup 按间隔分组时间戳,使图表上每 $__interval 只有一个点,并将其转换为给定时区 | TIME_SLICE(TO_TIMESTAMP(CONVERT_TIMEZONE('UTC', 'America/Los_Angeles', created_ts)), 1, 'HOUR', 'START') |
示例
表格可视化
在 Snowflake 中,大多数查询最适合以表格可视化表示。任何查询都会以表格形式显示数据。如果可以查询,则可以将其放入表格中。
此示例返回表格可视化的结果
SELECT {column_1}, {column_2} FROM {table};
时间序列/图表可视化
对于时间序列/图表可视化,有一些要求
- 必须选择具有
date
或datetime
类型的列 date
列必须按升序排列(使用ORDER BY column ASC
)- 还必须选择一个数值列
为了创建更合理的图表,请务必使用 $__timeFilter
和 $__timeGroup
宏。
示例时间序列查询
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 查询变量,请参阅[添加查询变量](/docs/grafana/latest/variables/variable-types/add-query-variable/)。使用您的 Snowflake 数据源作为以下可用查询的数据源
可以从 Snowflake 表中查询到的任何值都可以用作变量。请确保不要选择过多的值,因为这可能会导致性能问题。
如果变量查询返回两列,则将从第二列的值用作显示值
使用变量
创建变量后,您可以通过使用变量语法在Snowflake查询中使用它。有关变量的更多信息,请参阅模板和变量。
在查询中使用变量时,您可以可选地设置插值格式。您还可以在数据源配置中配置默认插值格式。
单值变量
如果变量返回单个值,您可以使用以下格式之一。以下示例假设您已将sqlstring
设置为默认插值,并且您有两个名为queryTypeSingle
和limit
的变量。它们的值分别为SELECT
和2
。
SELECT query_type FROM account_usage.query_history WHERE query_type = ${queryTypeSingle} Limit ${limit:raw}
将被翻译为
SELECT query_type FROM account_usage.query_history WHERE query_type = 'SELECT' Limit 10
默认变量插值类型设置是在版本1.2中引入的。从该版本开始,您可以将默认插值类型设置为
sqlstring
在插件版本1.2之前或如果您使用none
作为默认插值类型时,相同的查询必须写成以下形式
SELECT query_type FROM account_usage.query_history WHERE query_type = '${queryTypeSingle}' Limit ${limit:raw}
使用sqlstring插值的多值变量
当消费返回多个选项的变量时,您可以按以下方法消费它。以下示例假设您已将sqlstring
设置为默认插值,并且您有两个名为queryTypeMulti
和limit
的变量。它们的值分别为CREATE,SELECT
和2
。
SELECT query_type FROM account_usage.query_history WHERE query_type in (${queryTypeMulti}) Limit ${limit:raw}
将被翻译为
SELECT query_type FROM account_usage.query_history WHERE query_type in ('CREATE','SELECT') Limit 10
使用正则表达式插值的多值变量
要使用具有多个值的变量,您可以使用正则表达式修饰符选项和regexp
Snowflake函数。例如:${variable:regex}
例如,此查询将仅使用在queryType
变量中选择的查询类型
进行过滤
...
AND query_type regexp '${queryType:regex}'
...
此查询翻译为
...
AND query_type regexp '(DESCRIBE|CREATE_USER|DROP|TRUNCATE_TABLE|ALTER)'
...
将数据可视化为日志
在查询中选择日志格式时,您可以在探索器的日志查看器中可视化数据。使用日志格式查询时,您的查询至少应有一个时间列和一个字符串/内容列。可选地,查询可以有一个名为级别的第三列,以设置特定行的日志级别。支持的日志级别及其关键字可以在Grafana日志集成文档站点中找到。如果查询返回任何附加列,它们将被视为日志中的附加字段/检测到的字段。
例如,以下是一个有效的日志查询。
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
角色的数据源来查看计费数据。在配置部分有一个示例。
按照这些说明导入仪表板。
导入的仪表板可以在配置 > 数据源 > 选择您的Snowflake数据源 > 选择仪表板选项卡中找到,以查看可用的预制作仪表板。