简体中文 | English | 旧版README | Old Version README
日志服务 SLS 是云原生观测分析平台，为Log/Metric/Trace等数据提供大规模、低成本、实时平台化服务。一站式提供数据采集、加工、分析、告警可视化与投递功能，全面提升研发、运维、运营和安全等场景数字化能力。官方文档
本仓库为阿里云日志服务Grafana数据源插件。使用本插件的前提，需要您使用日志服务产品，并拥有至少1个已配置采集的LogStore。
依赖 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
在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保存后清空 , 且不会回显。
时序库也可以配置为SLS插件的形式，使用这种接入方式，则支持SQL查询时序库，以及使用PromQL算子查询时序库（详情请查阅：时序查询语法简介）。配置方式与1.1节一致，在LogStore中填写metricStore名称即可。
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仪表盘互相转化）
从实践上，唯一推荐的写法是：${var_name}。
从理论上，Grafana支持3种写法，分别是$varname、${var_name}、[[varname]]。但是不加大括号的写法有可能会变量名范围识别错误、双中扩号的写法在未来将会逐步抛弃。参考来源。
对于大部分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选择与全选。
在配置SLS存储数据源中提到， SLS时序库支持Prometheus原生方式配置，也支持SLS插件方式配置。若使用SLS插件配置，则通常需要搭配promql算子，其使用方式与语法详见：时序数据查询和分析简介。
以下给出一个示例，该示例获取时序库中所有指标名。
首先配置一个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时显示为：
该功能在仪表盘时间范围选择非常长的时候，可以很方便地进行时间打点密度的控制。
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
其他场景：
在线图场景下也可以显示为单值图，但不推荐这种写法。
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
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
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
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
xcol写法：<空>
ycol写法：<空>
示例1：
图表类型: Logs
xcol:
ycol:
query: host: www.vt.mock.com
图表类型: 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
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
注意：此功能在 SLS Grafana Plugin 2.30 版本及以上才可使用。
您可以在Explore界面和仪表盘界面中，随时跳转到SLS控制台进行比对了，同时也可以使用SLS控制台更强大的功能和更灵活的日志检索。
跳转到SLS控制台，将附带query、时间信息，无需手动输入。
此种跳转方式是直接跳转到SLS控制台，不涉及任何配置，但需要您的浏览器登录了SLS控制台，否则会显示登录页面。
步骤：
- 访问RAM控制台https://ram.console.aliyun.com/roles/，创建一个**有且只有AliyunLogReadOnlyAccess**权限策略的角色。建议最大会话时间为3600秒。在基本信息处可复制roleArn信息。
- 访问RAM控制台授权界面https://ram.console.aliyun.com/permissions，给在Grafana DataSource配置的AccessKey对应的用户，赋予AliyunRAMReadOnlyAccess、AliyunSTSAssumeRoleAccess权限。（或更换Grafana DataSource配置的AccessKey、AccessSecret，必须保证用户有该权限）
- 在DataSource界面配置roleArn。
- 再次回到Explore界面，尝试gotoSLS按钮，即可免登STS跳转。
注意：如果配置的roleArn有误、权限范围有误，均会导致免登失效，将仍按照一般逻辑进行跳转。
若配置STS跳转，为权限安全考虑，需要满足以下两个条件：
- 配置DataSource的accessKey对应的用户，需要有
AliyunRAMReadOnlyAccess权限、AliyunSTSAssumeRoleAccess权限 - 配置DataSource的roleArn，里面的权限策略，必须有且只有
AliyunLogReadOnlyAccess
原理参考：控制台内嵌及分享
如果您配置了免登跳转，请一定要注意数据源是否涉及Grafana仪表盘公开访问的分享，如果涉及公开访问，可能会造成潜在的流量成本上升、潜在的日志内容公开暴露。
- 排查xcol、ycol是否配置规范，详情见本文第4章。
- 将xcol、ycol置空，已表格形式查看数据是否正确。
- 排查是否数值列中混有非数字字符或特殊字符。
- Query Inspector中查看是否有数据返回。
- 联系我们查看此问题。
请检查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钉钉群
