es-analytics

name	es-analytics
metadata	{"version":"0.1.2"}
description	Elasticsearch / SLS 只读数据分析：索引探索、mapping、聚合统计、日志搜索、时间序列、多 Profile。

ES 数据分析技能

零依赖

仅使用 Python 3 标准库（urllib + json），不需要安装任何第三方包。

配置

添加连接

./es config add <profile-name> \
  --url <ES基础URL> \
  --user <用户名/AccessID> \
  --password <密码/AccessSecret> \
  [--default-index <默认索引名>] \
  [--sls]  \
  --test

--sls 标记该连接为阿里云 SLS ES 兼容端点。SLS 端点有以下行为差异，技能会自动处理：

• 默认只查最近 24h：所有查询自动注入全时间范围 range 条件（除非用户已指定）
• 嵌套字段无法聚合：terms 等聚合作用于未建索引的嵌套字段会报 sls_field_index_not_configed
• _source 过滤不可靠：部分嵌套字段在 _source 过滤后丢失

凭据存储在 ~/.agents/data/es-analytics/profiles.json（权限 0600），支持多 Profile。

管理连接

./es config list                    # 列出所有 profile
./es config use <profile-name>      # 切换默认 profile
./es config test [profile-name]     # 测试连接
./es config remove <profile-name>   # 删除 profile

脚本

query — ES 查询（只读）

./es query '{"size":10,"query":{"match_all":{}}}'
./es query -i my-index '{"size":5,"sort":[{"@timestamp":"desc"}]}'
./es query -p prod -i logs '{"query":{"match":{"level":"ERROR"}}}'
./es query --format csv '{"size":50,"query":{"term":{"status":"200"}}}'

选项：-p profile / -i 索引 / --format table|csv|json / --full-range（SLS 自动全时间范围）

indices — 索引列表

./es indices                        # 列出所有索引
./es indices -p prod                # 指定 profile
./es indices --filter "chat*"       # 过滤索引名

mapping — 查看索引 Mapping

./es mapping my-index               # 查看字段定义
./es mapping my-index -p prod       # 指定 profile

count — 文档计数

./es count my-index                             # 总数
./es count my-index '{"query":{"match":{"level":"ERROR"}}}'   # 按条件计数
./es count my-index --full-range                # SLS 全时间范围计数

extract — 全量去重提取（search_after 分页）

./es extract my-index --field auth_id                              # 提取去重字段
./es extract my-index --field auth_id --filter '{"match":{"auth_type":"user"}}'
./es extract my-index --field auth_id --full-range -o /tmp/uids.csv

高效分页提取指定字段的唯一值，自动 search_after，适合大数据量去重场景。

sample — 采样数据

./es sample my-index                # 最新 5 条数据，展示字段结构
./es sample my-index -n 10 -p prod  # 指定数量和 profile

SLS ES 兼容层注意事项

技能已内建以下保护机制：

1. SLS profile 的查询自动注入 range 条件覆盖全时间范围（可通过 --no-full-range 禁用）
2. 当聚合收到 sls_field_index_not_configed 错误时，自动降级为 search_after 分页 + Python 侧聚合
3. 不依赖 _source 过滤功能

安全策略

• 只读: 拦截 DELETE / PUT（非 _search） / POST（非 _search/_count/_mapping）
• 行数限制: query 默认添加 size: 200
• 凭据安全: 配置文件权限 0600，密码不出现在命令行输出

模块架构

es (Bash CLI 入口)
│
├── config    → config.py     多 Profile 连接管理 (add/list/use/test/remove)
├── query     → query.py      ES 只读查询 (table/csv/json 输出)
├── indices   → indices.py    索引列表
├── mapping   → mapping.py    Mapping 查看
├── count     → count.py      文档计数
├── extract   → extract.py    全量去重提取 (search_after)
└── sample    → sample.py     采样数据
               ↓
            es_core.py         核心引擎 (HTTP 连接 + 安全 + 输出格式化)
               ↓
         ~/.agents/data/es-analytics/
           └── profiles.json   连接配置