alibabacloud-sls-query

Alibaba Cloud SLS 查询与分析

场景描述

当用户想要执行以下操作时，使用此技能：

• 解释、改写、优化或执行现有查询
• 将自然语言需求转换为 SLS 索引查询、SQL 或 SPL 语句

---

前置条件

安装 Aliyun CLI

运行 aliyun version，验证版本是否 >= 3.3.8。如果尚未安装或版本过旧，请按照文档 references/cli-installation-guide.md 安装或更新。

更新插件

aliyun plugin update

检查是否已配置 Alibaba Cloud 凭证

运行 aliyun configure list，检查是否已配置凭证。 如果未显示有效的配置文件，立即停止，并请用户在本次会话之外运行 aliyun configure。

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户在对话中粘贴 AK/SK
• 仅使用 aliyun configure list 检查凭证状态

---

RAM 权限要求

API	CLI	Action	用途
GetLogsV2	get-logs-v2	log:GetLogStoreLogs	运行查询 / SQL / SPL 并读取结果
GetIndex	get-index	log:GetIndex	读取索引配置以验证前置条件

最小和完整的 RAM 策略 JSON，请参阅 references/ram-policies.md。

权限失败处理： 如果调用返回 Unauthorized 权限错误，请停止并向用户提供 references/ram-policies.md。未经用户明确确认，不要改用其他账号重试。

---

可观测性（每条 aliyun API 命令都必须遵循）

加载此技能后，生成一个随机会话 ID（32 位小写十六进制字符串），在整个会话中仅生成一次。将其用作下方的 {session-id}。

规则： 每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。本地实用程序命令（例如 configure、plugin、version）不支持此标志，应排除在外。

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sls-query/{session-id}"

示例（假设 session-id 为 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6）：

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 --query '*' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sls-query/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

调用任何 aliyun API 命令时，都不要跳过、修改格式或省略 --user-agent。

---

核心工作流

1. 读取索引配置（GetIndex）
2. 选择查询模式
3. 构建语句
4. 确定时间范围
5. 执行查询
6. 从响应中提取数据
7. 展示 CLI 命令和结果

步骤 1：读取索引配置（必需）

始终先调用 get-index——索引配置决定了步骤 2 中可用的查询模式。

aliyun sls get-index \
  --project <project> --logstore <logstore>

响应中的两个部分将决定后续所有操作：

部分	含义
line	全文索引——不存在表示全文搜索已禁用
keys	字段索引——字段 → { type, doc_value, token, caseSensitive, chn, ... } 的映射。doc_value: true 表示已为该字段启用统计功能

如果调用返回 IndexConfigNotExist（HTTP 404），或者响应中 line 和 keys 均未填充，则 Logstore 完全没有索引——请立即停止，并告知用户必须先创建索引，才能运行任何查询 / SQL / SPL。

• 响应可能很大——仅提取当前查询相关的字段。按 logstore 缓存，并在会话中重复使用。

有关字段类型、分词以及 get-index 与功能支持的对应关系，请参阅 references/related-apis.md 和 references/query-analysis.md。

---

步骤 2：选择查询模式（关键）

查询语句采用以下形式之一：

优先级	模式	语句形式	适用场景	要求
1	索引搜索	<index-search>	筛选原始日志；按时间排序并分页返回日志	全文索引（line）或任意字段索引（keys.<field>）
2	SQL	<index-search> | <SQL>	聚合、GROUP BY、排序、窗口、Top-N、投影及其他分析操作	目标字段具有 keys.<field>，且 doc_value: true
3	SQL 扫描	<index-search> | <SQL scan>	用户明确要求	无
4	SPL	<index-search> | <SPL>	用户明确要求	无

选择规则：

• 始终优先选择索引搜索，速度最快。
• 当用户需要分析操作或字段投影，而不是检索全部原始日志时，使用索引搜索 + SQL，例如聚合、GROUP BY、排序、窗口分析、Top-N，或仅返回所需字段／列。
• 不要主动选择SQL 扫描或 SPL；仅在用户明确要求时使用。

完整的决策指南请参阅 references/query-analysis.md。

---

步骤 3：编写语句

3.1 先构建索引搜索部分（| 左侧）

收集所有可用索引搜索语法表达的筛选条件，并将它们放在第一个 | 之前。如果没有适用的筛选条件，请使用 *。

* and "payment failed" and status: "500" and not path: "/healthz"

• * 匹配全部；"..." 表示全文搜索（需要全文索引）。
• key: "value" 是字段筛选条件（需要字段索引）。
• 使用 and／or／not 组合；使用括号分组。
• key: * 表示字段存在。范围（>、>=、[a, b]）仅适用于 long／double。

如果无需聚合或逐行处理即可完整回答需求，请在此处结束——这已经是完整的索引搜索。完整的索引搜索语法请参阅 references/query-analysis.md。

3.2 追加 SQL —— 用于聚合／分析

status: 500 | SELECT date_trunc('minute', __time__) AS minute,
                    count(*) AS errors
              FROM log
              GROUP BY minute
              ORDER BY minute

• 查询与 SQL 规则请参阅 references/query-analysis.md
• 表名为 log（建议省略）。
• SQL 遵循 get-index 返回的索引字段类型——long／double 字段可直接比较（status >= 500）。仅当字段被索引为 text，但需要按数值语义处理时才进行类型转换（使用 try_cast 可抑制错误）。
• 不常见的函数选择（聚合、JSON、正则表达式、日期时间、IP 地理位置等）请参阅 references/functions-guide.md

3.3 追加 SPL —— 用于逐行处理／灵活筛选

status: 500 and service: payment
| where try_cast(latency as BIGINT) > 1000
| extend latency_ms = try_cast(latency as BIGINT)
| project service, latency_ms, message

SPL 语法、管道命令和字段处理规则请参阅 references/spl-guide.md。

3.4 追加 SQL 扫描 —— 当目标字段没有索引／统计信息时的备用方案

语法遵循常规 SQL（参见 3.2），但有一点不同：每个字段都是 varchar，因此在数值比较或算术运算前，始终使用 cast()／try_cast()。扫描语义请参阅 references/query-analysis.md。

* | set session mode=scan; SELECT api, count(1) AS pv FROM log GROUP BY api

---

第 4 步：确定时间范围

在构建 CLI 命令前，先生成 --from / --to，格式为秒级 Unix 时间戳。--from 包含在范围内，--to 不包含在范围内。

选择以下三种输入模式之一：

1. 相对时间 —— 用户说“最近 / 过去 N 分钟|小时|天”。
2. 不带时区的自然语言绝对时间 —— 先规范化为 YYYY-MM-DD HH:MM:SS，然后使用机器的本地时区解析。
3. 带明确时区的绝对时间 —— 使用客户提供的时区或 UTC 偏移量解析。

1. 相对时间

# recent 15 minutes
FROM=$(($(date +%s) - 900))
TO=$(date +%s)

2. 不带时区的自然语言绝对时间

如果用户提供了日期/时间但未指定时区，请使用机器的本地时区。先将 2026年3月13日12点 这类自然语言规范化为 2026-03-13 12:00:00，然后将其作为本地时间解析。

# Example: 2026年3月13日12点 -> 2026-03-13 12:00:00

# Linux (GNU date): local timezone
FROM=$(date -d "2026-03-13 12:00:00" +%s)

# macOS (BSD date): local timezone
FROM=$(date -j -f "%Y-%m-%d %H:%M:%S" "2026-03-13 12:00:00" +%s)

对于“2026年3月13日12点到13点”这样的时间范围，以相同方式计算两个端点。对于单个时间点的请求，根据用户的意图推断一个合适的时间窗口；如果不明确，请在执行前询问时间范围。

3. 带明确时区的绝对时间

要将本地日期/时间转换为 Unix 时间戳：使用 date -u 将输入解析为 UTC，然后减去时区的 UTC 偏移量（秒）。

公式：unix_ts = date_utc_parse(input) − (UTC_offset_hours × 3600)

# Example: 2025-01-15 10:30:00 Beijing Time (UTC+8)
# Beijing is UTC+8, so subtract 8 × 3600 = 28800

# Linux (GNU date)
FROM=$(( $(date -u -d "2025-01-15 10:30:00" +%s) - 28800 ))

# macOS (BSD date)
FROM=$(( $(date -u -j -f "%Y-%m-%d %H:%M:%S" "2025-01-15 10:30:00" +%s) - 28800 ))

# Example: 2025-01-15 10:30:00 New York Time (UTC-5)
# New York is UTC-5, so subtract -5 × 3600 = subtract -18000 = add 18000

# Linux (GNU date)
FROM=$(( $(date -u -d "2025-01-15 10:30:00" +%s) + 18000 ))

# macOS (BSD date)
FROM=$(( $(date -u -j -f "%Y-%m-%d %H:%M:%S" "2025-01-15 10:30:00" +%s) + 18000 ))

常见 UTC 偏移量（要减去的值）：

时区	UTC 偏移小时数	要减去的秒数
北京（UTC+8）	+8	28800
东京（UTC+9）	+9	32400
伦敦（UTC）	0	0
纽约（UTC-5）	-5	-18000

---

第 5 步：通过 get-logs-v2 执行

使用 aliyun sls get-logs-v2 执行查询。运行 aliyun help sls get-logs-v2 查看 CLI 参数用法；阅读 references/related-apis.md 了解详细的 API 参数说明。

必需的 CLI 标志：

• --project：SLS 项目名称
• --logstore：项目中的 Logstore 名称
• --from：时间范围的起始时间，秒级 Unix 时间戳（包含）
• --to：时间范围的结束时间，秒级 Unix 时间戳（不包含）
• --query：第 3 步构建的语句

分页方式取决于语句中是否包含 |：

5.1 仅索引搜索 —— 使用 --offset / --line 分页

aliyun sls get-logs-v2 \
  --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 \
  --query '* and "payment failed" and status: "500"' \
  --line 100 --offset 0 --reverse true

• 分页：--line 是页面大小（1–100，必需）；--offset 是起始行（可选，默认为 0）。
• 排序：--reverse true 按最新到最旧返回；默认值 false 表示按最旧到最新返回。

5.2 使用 SQL —— 在语句中通过 LIMIT 分页

aliyun sls get-logs-v2 \
  --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 \
  --query 'status: "500" | SELECT request_uri, count(*) AS cnt FROM log GROUP BY request_uri ORDER BY cnt DESC LIMIT 20'

• SQL 默认最多返回 100 行。如需获取更多结果或分页：
  • LIMIT count —— 提高上限（例如，LIMIT 500 最多返回 500 行）
  • LIMIT offset, count —— 分页（例如，LIMIT 20, 20 表示第 21–40 行；LIMIT 40, 20 表示第 41–60 行）。offset+count 最大为 1000000。
  • 不要使用 LIMIT count OFFSET offset 语法——此语法不受支持。始终使用 LIMIT offset, count。
• 排序：使用 ORDER BY <field> DESC/ASC 排序。

结果完整性检查： 每个响应都包含 meta.progress。如果值为 Incomplete，请重新发送相同请求，直到返回 Complete。

步骤 6：从响应中提取数据

get-logs-v2 返回：

{
  "meta": { "progress": "Complete", "count": 10, ... },
  "data": [ { "field1": "value1", ... }, ... ]
}

字段	含义
meta.progress	Complete 或 Incomplete（参见步骤 5）
meta.count	返回的行数
data	日志条目或聚合行数组；可能包含 __time__（Unix 秒，字符串）

使用 jq（优先）或 --cli-query（JMESPath）提取用户需要的字段：

提取内容	jq	--cli-query（JMESPath）
数据行	| jq '.data'	--cli-query 'data'
进度	| jq '.meta.progress'	--cli-query 'meta.progress'
行数	| jq '.meta.count'	--cli-query 'meta.count'
特定字段	| jq '.data[] | {LogStore, read_mb}'	--cli-query 'data[].{LogStore: LogStore, read_mb: read_mb}'

---

步骤 7：展示 CLI 命令和结果

CLI 命令 — 始终展示完整且可直接复制粘贴的 aliyun sls get-logs-v2 ... 命令。对任何 AK/SK 进行脱敏。如果未执行查询（编写／解释场景），则展示用户应运行的命令。

结果 — 执行查询时，使用步骤 6 提取 data，并根据用户的要求（表格、列表、摘要等）进行格式化。追加一句话说明选择该查询模式的原因。

---

全局规则

• 始终优先使用索引查询，以最快速度检索原始日志；进行分析或字段投影时，使用索引查询 + SQL。
• 当用户只需要特定字段时，使用 SELECT 投影这些字段，而不是获取完整原始日志，以减少网络开销。目标字段需设置 doc_value: true（已在步骤 1 中确认）。
• 不要对 __time__ 过滤器进行硬编码 — 通过 --from / --to 传递时间范围。
• 已弃用的 API：绝不要调用 get-logs；始终使用 get-logs-v2。

---

故障排查

当用户报告“无数据”“结果错误”或 CLI 错误时，请严格按照以下顺序逐项检查：

1. 时间范围 — --from/--to 是否错误？是否误用了毫秒而不是秒？最近写入的数据是否仍在建立索引？
2. 索引配置 — 是否缺少字段索引？是否关闭了全文索引？目标字段是否不在 keys 中？
3. 字段类型／统计信息 — 是否在 text 字段上执行范围查询？是否对没有 doc_value 的字段执行 SQL？
4. 语法 — 是否混用了 SQL 和 SPL？模糊匹配中是否有开头的 *？SPL 字符串转义是否正确？
5. 模式选择 — 是否在索引查询即可满足需求时进行了扫描？是否使用 SPL 而不是 SQL 进行聚合？
6. 完整性 — meta.progress = Incomplete，调用方未重试（参见步骤 5）。
7. ProjectNotExist — 区域或端点错误。使用跨区域发现自动定位项目，或请用户确认区域。在调用 get-project --cross-region true 之前，必须阅读 references/regions.md 中的“跨区域发现”部分 — 此 API 只能通过 cn-zhangjiakou.log.aliyuncs.com 端点使用。
8. 网络故障（超时、连接被拒绝）— 尝试切换到内网端点。参见 references/regions.md。

如需查看完整的故障模式和错误代码目录，请参见 references/troubleshooting.md 和 references/related-apis.md 中的 Common Errors 表格。

---

参考文档

文档	描述
references/query-analysis.md	模式判定、索引搜索 / SQL 规则、扫描语义
references/spl-guide.md	SPL 管道语法、常用命令、字段处理
references/functions-guide.md	函数类别、SQL/SPL 差异、模板
references/troubleshooting.md	“无数据 / 结果错误 / 报错”排查指南
references/related-apis.md	GetLogsV2 和 GetIndex API 与 CLI 参考
references/ram-policies.md	最小和完整 RAM 策略
references/cli-installation-guide.md	Aliyun CLI 安装、身份验证模式、配置文件
references/regions.md	地域 / 终端节点配置、内部终端节点、跨地域发现（get-project --cross-region true，仅 cn-zhangjiakou）
references/acceptance-criteria.md	CLI 调用验收测试
references/query_analysis/*.yaml · references/spl/*.yaml · references/functions/*.yaml	此技能随附的事实来源 YAML 文件