简体中文 | English | 旧版README | Old Version README

1. 简介

日志服务 SLS 是云原生观测分析平台，为Log/Metric/Trace等数据提供大规模、低成本、实时平台化服务。一站式提供数据采集、加工、分析、告警可视化与投递功能，全面提升研发、运维、运营和安全等场景数字化能力。官方文档
本仓库为阿里云日志服务Grafana数据源插件。使用本插件的前提，需要您使用日志服务产品，并拥有至少1个已配置采集的LogStore。

2. 安装

依赖 Grafana 8.0 及以上版本 , Grafana 8.0 以下请使用1.0版本。
于Release处下载本插件到grafana插件目录下，修改配置文件，在配置文件的[plugins] 节点中，设置 allow_loading_unsigned_plugins = aliyun-log-service-datasource， 然后重启grafana。

• mac
  • 插件目录： /usr/local/var/lib/grafana/plugins
  • 配置文件位置：/usr/local/etc/grafana/grafana.ini
  • 重启命令：brew services restart grafana
• YUM/RPM
  • 插件目录：/var/lib/grafana/plugins
  • 配置文件位置：/etc/grafana/grafana.ini
  • 重启命令：systemctl restart grafana-server
• .tar.gz
  • 插件目录：{PATH_TO}/grafana-{x}.{x}.{x}/data/plugins
  • 配置文件位置：{PATH_TO}/grafana-{x}.{x}.{x}/conf/defaults.ini
  • 重启命令：./bin/grafana-server web

3. 添加数据源

3.1 日志库配置

在datasource界面添加一个SLS log-service-datasource数据源。在数据源管理面板, 添加 LogService 数据源，在 settings 面板, 设置 Endpoint 为您日志服务 project 的 endpoint ( endpoint 在 project 的概览页可以看到，详情请参见服务入口)。例如您的 project 在 qingdao region, Url 可以填 cn-qingdao.log.aliyuncs.com。根据需要设置 Project 和 logstore，设置 AccessId 和 AccessKeySecret , 最好配置为子账号的AK。为保证数据安全 , AK保存后清空 , 且不会回显。

3.2 时序库配置（使用SLS插件，支持SQL查询+组合算子查询）

时序库也可以配置为SLS插件的形式，使用这种接入方式，则支持SQL查询时序库，以及使用PromQL算子查询时序库（详情请查阅：时序查询语法简介）。配置方式与1.1节一致，在LogStore中填写metricStore名称即可。

3.3 时序库配置（原生方式，使用Prometheus插件）

SLS的时序库支持原生Prometheus查询，因此可以直接使用原生Prometheus插件进行数据源接入。请参考如下官方文档配置数据源。日志服务MetricStore的URL，格式为https://{project}.{sls-endpoint}/prometheus/{project}/{metricstore}。其中_{sls-endpoint}为Project所在地域的Endpoint，详情请参见服务入口，{project}和{metricstore}_为您已创建的日志服务的Project和Metricstore，请根据实际值替换。例如：https://sls-prometheus-test.cn-hangzhou.log.aliyuncs.com/prometheus/sls-prometheus-test/prometheus
从最佳实践角度：时序库可以同时添加Prometheus数据源与SLS数据源，查询时可根据个人习惯任意使用不同的语句查询方式，在Variable中推荐使用SLS数据源（支持与SLS仪表盘互相转化）

4. 使用

4.1 仪表盘变量

4.1.1 Grafana变量在query中的写法

从实践上，唯一推荐的写法是：${var_name}。
从理论上，Grafana支持3种写法，分别是$varname、${var_name}、[[varname]]。但是不加大括号的写法有可能会变量名范围识别错误、双中扩号的写法在未来将会逐步抛弃。参考来源。

4.1.2 一般用法与全选配置

对于大部分SLS DataSource，可以通过SQL语句查询值，将其作为变量。步骤：

• 进入Grafana仪表盘的设置 - Variables
• 类型选择Query、Datasource配置为对应LogStore、书写query
• 在Preview of values中查看结果

通常，如果作为日志库筛选用，实践中推荐打开All Option，并将Custom all value配置为*。

这样在Dashboard Query语句中，按照如下写法：* and request_method: ${var} | select * from log即可支持Variable选择与全选。

4.1.3 时序数据在SLS插件中的Variable配置

在配置SLS存储数据源中提到， SLS时序库支持Prometheus原生方式配置，也支持SLS插件方式配置。若使用SLS插件配置，则通常需要搭配promql算子，其使用方式与语法详见：时序数据查询和分析简介。
以下给出一个示例，该示例获取时序库中所有指标名。

4.1.4 使用Interval变量根据时间跨度控制打点

首先配置一个Grafana 时间变量

Name	变量名称，例如myinterval。该名称是您配置中使用的变量，此处为myinterval，则查询条件中需写成**$$myinterval**。
Type	选择Interval。
Label	配置为time interval。
Values	配置为1m,10m,30m,1h,6h,12h,1d,7d,14d,30d。
Auto Option	打开Auto Option开关，其他参数保持默认配置。

注意：该时间变量在SLS中不同于Grafana变量，需要在正常变量写法之前，再加上一个**$**符号，才能正确在SLS语句中转化Interval。

图表类型: TimeSeries
xcol: time
ycol: pv, uv
query: * | select __time__ - __time__ % $${myinterval} as time, COUNT(*)/ 100 as pv, approx_distinct(remote_addr)/ 60 as uv GROUP BY time order by time limit 2000

在配置为1m时显示为：

在配置为10m时显示为：

该功能在仪表盘时间范围选择非常长的时候，可以很方便地进行时间打点密度的控制。

4.2 图表标准写法概览

4.2.1 单值图（Stat / Gauge）

xcol写法：stat
ycol写法：<数值列>, <数值列>
注意：图中要求的数值列若提供的是非数值列，会直接置0。
示例1：

图表类型: Stat
xcol: stat
ycol: PV, deltaPercent
query: * | select diff[1] as "PV", round((diff[1] - diff[2])/diff[2] * 100, 2) as deltaPercent from (select compare("PV", 86400) as diff from (select count(*) as "PV" from log))

示例2：

图表类型: Gauge
xcol: stat
ycol: c
query: * | select count(distinct labels['hostname']) as c from (select promql_query('${metricName}{cluster =~ "${cluster}"}') from metrics ) limit 100000

其他场景：
在线图场景下也可以显示为单值图，但不推荐这种写法。

4.2.2 饼图（Pie）

xcol写法：pie
ycol写法：<聚合列>, <数值列>
示例1：

图表类型: Pie
xcol: pie
ycol: request_method, c
query: request_method: "$method" |  select count(*) as c, request_method group by request_method

示例2：

图表类型: Pie
xcol: pie
ycol: http_user_agent, pv
query: * | select count(1) as pv, case when http_user_agent like '%Chrome%' then 'Chrome' when http_user_agent like '%Firefox%' then 'Firefox' when http_user_agent like '%Safari%' then 'Safari' else 'unKnown' end as http_user_agent  group by case when http_user_agent like '%Chrome%' then 'Chrome' when http_user_agent like '%Firefox%' then 'Firefox' when http_user_agent like '%Safari%' then 'Safari' else 'unKnown' end  order by pv desc limit 10

其他场景：
Stat图的写法也适用于饼图，也可以展示出效果。

图表类型: Pie
xcol: stat
ycol: hostNameNum, ipNum
query: * | select count(distinct labels['hostname']) as hostNameNum, count(distinct labels['ip']) + 20 as ipNum from (select promql_query('${metricName}{cluster =~ ".*"}') from metrics ) limit 100000

4.2.3 线图（TimeSeries）

xcol写法：<时间列>
ycol写法：<数值列> [, <数值列>, ...]（日志写法）<labels / 聚合列>#:#<数值列>（时序库写法或日志聚合写法）
示例1：

图表类型: Time series
xcol: time
ycol: pv, uv
query: * | select __time__ - __time__ % $${myinterval} as time, COUNT(*)/ 100 as pv, approx_distinct(remote_addr)/ 60 as uv GROUP BY time order by time limit 2000

示例2：

图表类型: Time series
xcol: time
ycol: labels#:#value
query: * | select time, * from (select promql_query_range('${metricName}') from metrics) limit 1000

示例3：
也可以通过sql对时序labels进行自定义展示。

图表类型: Time series
xcol: time
ycol: customLabelsExtract#:#value
query: * | select concat(labels['ip'], ' -> ', labels['cluster']) as customLabelsExtract, value from (select promql_query_range('${metricName}') from metrics) limit 1000

4.2.4 柱状图（Bar）

xcol写法：bar
ycol写法：<聚合列>, <数值列> [, <数值列>, ...]
示例1：

图表类型: Bar
xcol: bar
ycol: host, pv, pv2, uv
query: * | select host, COUNT(*)+10 as pv, COUNT(*)+20 as pv2, approx_distinct(remote_addr) as uv GROUP BY host ORDER BY uv desc LIMIT 5

4.2.5 表格（Table）

xcol写法：<空>
ycol写法：<空> 或者 <展示列> [, <展示列>, ...]
示例1：

图表类型: Table
xcol: 
ycol: 
query: * | select __time__ - __time__ % 60 as time, COUNT(*)/ 100 as pv, approx_distinct(remote_addr)/ 60 as uv GROUP BY time order by time limit 2000

4.2.6 日志（Log）

xcol写法：<空>
ycol写法：<空>
示例1：

图表类型: Logs
xcol: 
ycol: 
query: host: www.vt.mock.com

4.2.7 Trace（Traces）

图表类型: Traces
xcol: trace
ycol: 
query: traceID: "f88271003ab7d29ffee1eb8b68c58237"

该示例中使用了Trace的日志库，需要您在SLS使用Trace服务，日志服务支持OpenTelemetry Trace数据的原生接入，还支持通过其他Trace系统接入Trace数据。更多细节请参见：https://help.aliyun.com/document_detail/208894.html
在 Grafana 10.0 以上版本，支持Trace数据的span筛选功能，如果您使用的是低版本Grafana，也可以在query筛选中自定义span的筛选。例如：

traceID: "f88271003ab7d29ffee1eb8b68c58237" and resource.deployment.environment : "dev" and service : "web_request" and duration > 10

4.2.8 地图（Map）

xcol写法：map
ycol写法：<国家列>, <地理位置列>, <数值列>
示例1：

图表类型: GeoMap
xcol: map
ycol: country, geo, pv
query: * | select count(1) as pv ,geohash(ip_to_geo(arbitrary(remote_addr))) as geo,ip_to_country(remote_addr) as country  from log group by country having geo <>'' limit 1000

5. 一键跳转SLS控制台

注意：此功能在 SLS Grafana Plugin 2.30 版本及以上才可使用。
您可以在Explore界面和仪表盘界面中，随时跳转到SLS控制台进行比对了，同时也可以使用SLS控制台更强大的功能和更灵活的日志检索。
跳转到SLS控制台，将附带query、时间信息，无需手动输入。

此种跳转方式是直接跳转到SLS控制台，不涉及任何配置，但需要您的浏览器登录了SLS控制台，否则会显示登录页面。

5.1 STS方式跳转（无需登录）

步骤：

1. 访问RAM控制台https://ram.console.aliyun.com/roles/，创建一个**有且只有AliyunLogReadOnlyAccess**权限策略的角色。建议最大会话时间为3600秒。在基本信息处可复制roleArn信息。
   
2. 访问RAM控制台授权界面https://ram.console.aliyun.com/permissions，给在Grafana DataSource配置的AccessKey对应的用户，赋予AliyunRAMReadOnlyAccess、AliyunSTSAssumeRoleAccess权限。（或更换Grafana DataSource配置的AccessKey、AccessSecret，必须保证用户有该权限）
   
3. 在DataSource界面配置roleArn。
   
4. 再次回到Explore界面，尝试gotoSLS按钮，即可免登STS跳转。

注意：如果配置的roleArn有误、权限范围有误，均会导致免登失效，将仍按照一般逻辑进行跳转。

5.2 注意事项和风险警告⚠️

若配置STS跳转，为权限安全考虑，需要满足以下两个条件：

• 配置DataSource的accessKey对应的用户，需要有AliyunRAMReadOnlyAccess权限、AliyunSTSAssumeRoleAccess权限
• 配置DataSource的roleArn，里面的权限策略，必须有且只有AliyunLogReadOnlyAccess

原理参考：控制台内嵌及分享
如果您配置了免登跳转，请一定要注意数据源是否涉及Grafana仪表盘公开访问的分享，如果涉及公开访问，可能会造成潜在的流量成本上升、潜在的日志内容公开暴露。

6. 持续更新的常见疑问

6.1 为什么在SLS上可以显示图表，在Grafana上显示不了

• 排查xcol、ycol是否配置规范，详情见本文第4章。
• 将xcol、ycol置空，已表格形式查看数据是否正确。
• 排查是否数值列中混有非数字字符或特殊字符。
• Query Inspector中查看是否有数据返回。
• 联系我们查看此问题。

6.2 为什么会产生时间漂移，时间显示不对？

请检查SQL语句中是否包含date_format函数，如果是，则需要在模式串中规范为：%Y-%m-%d %H:%i:%s
例如出问题的语句为：

* | SELECT date_format(date_trunc('minute', __time__), '%H:%i') AS time, COUNT(1) AS count, status GROUP BY time, status ORDER BY time

需要更改为：

* | SELECT date_format(date_trunc('minute', __time__), '%Y-%m-%d %H:%i:%s') AS time, COUNT(1) AS count, status GROUP BY time, status ORDER BY time

6.3 如何联系日志服务

钉钉群