alicloud-observability-sls-log-query

用途

该技能面向阿里云日志服务（SLS）的日志查询与故障排查，使用 SLS 的 query|analysis 语法配合 Python SDK，完成按时间范围的日志搜索、过滤与统计分析。适用于需要定位错误日志、按字段聚合统计等可观测性场景。

主要能力

日志搜索与过滤：通过查询子句筛选日志，例如 status:500。
统计分析：在查询子句后追加分析子句，格式为 query|analysis，例如 * | SELECT status, count(*) AS pv GROUP BY status。
时间范围控制：查询需指定起止时间，脚本支持 --last-minutes 等时间参数。
多 Logstore 支持：SLS_LOGSTORE 支持单个值或逗号分隔的多个值，脚本参数 --logstore 可重复或逗号分隔。
结果行数控制：通过 limit 限制返回行数，必要时收窄时间范围。
排查脚本：提供 troubleshoot.py，支持 --group-field、--error-query、--limit、--parallel 等参数。

使用方式

前置准备：

安装 SDK（建议使用虚拟环境以避免 PEP 668 限制）：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U aliyun-log-python-sdk

配置环境变量：

ALIBABA_CLOUD_ACCESS_KEY_ID
ALIBABA_CLOUD_ACCESS_KEY_SECRET
SLS_ENDPOINT（例如 cn-hangzhou.log.aliyuncs.com）
SLS_PROJECT
SLS_LOGSTORE（支持单个值或逗号分隔的多个值）

Python SDK 快速上手示例：

import os
import time
from aliyun.log import LogClient, GetLogsRequest

client = LogClient(
    os.environ["SLS_ENDPOINT"],
    os.environ["ALIBABA_CLOUD_ACCESS_KEY_ID"],
    os.environ["ALIBABA_CLOUD_ACCESS_KEY_SECRET"],
)

project = os.environ["SLS_PROJECT"]
logstore = os.environ["SLS_LOGSTORE"]

query = "status:500"
start_time = int(time.time()) - 15 * 60
end_time = int(time.time())

request = GetLogsRequest(project, logstore, start_time, end_time, query=query)
response = client.get_logs(request)
for log in response.get_logs():
    print(log.contents)

脚本快速上手：

python skills/observability/sls/alicloud-observability-sls-log-query/scripts/query_logs.py \
  --query "status:500" \
  --last-minutes 15

可选参数：--project、--logstore（可重复或逗号分隔）、--endpoint、--start、--end、--last-minutes、--limit、--parallel。

排查脚本：

python skills/observability/sls/alicloud-observability-sls-log-query/scripts/troubleshoot.py \
  --group-field status \
  --last-minutes 30 \
  --limit 20

可选参数：--error-query、--group-field、--limit、--logstore（可重复或逗号分隔）、--parallel，以及上述时间范围参数。

工作流程：

确保 Logstore 已开启索引（未开启索引时查询与分析会失败）。
编写查询子句，需要时追加分析子句。
通过 SDK 或脚本执行并检查结果。
使用 limit 控制返回行数，必要时收窄时间范围。

适用场景

按时间范围搜索日志，定位特定错误（如 status:500）。
对日志按字段进行聚合统计（如按 status 分组计数）。
通过排查脚本按分组字段快速汇总错误分布。

限制与注意事项

使用前必须确保 Logstore 已开启索引，否则查询与分析会失败。
需要配置有效的阿里云访问凭证及 SLS 相关环境变量。
查询需指定时间范围，返回行数受 limit 控制。
关于收费、价格、平台支持范围等具体信息，资料中暂未提供。

验证与输出

验证方式：对 scripts 目录下的 Python 文件执行 py_compile，命令退出码为 0 且生成 output/alicloud-observability-sls-log-query/validate.txt 即视为通过。

输出与证据：将产物、命令输出和 API 响应摘要保存到 output/alicloud-observability-sls-log-query/ 下，并在证据文件中包含关键参数（区域/资源 ID/时间范围）以便复现。

参考资料

语法与示例：references/query-syntax.md
Python SDK 初始化与查询：references/python-sdk.md
排查模板：references/templates.md
来源列表：references/sources.md