名称：elasticsearch-analysis 描述：使用Lucene查询语法和Query DSL进行Elasticsearch/OpenSearch日志分析。在通过ELK栈、OpenSearch或任何基于Elasticsearch的日志系统调查问题时使用。允许工具：Bash(python *)

Elasticsearch分析

认证

重要：凭据由代理层自动注入。请勿检查环境变量中的ELASTICSEARCH_URL、ES_USER或ES_PASSWORD——它们对您不可见。直接运行脚本即可；认证已透明处理。

强制要求：统计优先调查

切勿转储原始日志。 始终遵循此模式：

统计 → 采样 → 模式 → 关联

统计优先 - 在采样前了解日志量、错误率和顶级模式
战略采样 - 基于统计选择正确的策略
模式提取 - 聚类相似错误以找到根本原因
上下文关联 - 围绕异常时间戳进行调查

可用脚本

所有脚本位于.claude/skills/observability-elasticsearch/scripts/

主要调查脚本

get_statistics.py - 始终从这里开始

综合统计与模式提取。

python .claude/skills/observability-elasticsearch/scripts/get_statistics.py [--index 索引] [--time-range 分钟]

# 示例：
python .claude/skills/observability-elasticsearch/scripts/get_statistics.py --time-range 60
python .claude/skills/observability-elasticsearch/scripts/get_statistics.py --index logs-production

输出包括：

总计数、错误计数、错误率百分比
状态分布（信息、警告、错误）
按日志量排名的顶级服务/来源
顶级错误模式（快速分类的关键）
可操作建议

sample_logs.py - 战略采样

基于统计选择正确的采样策略。

python .claude/skills/observability-elasticsearch/scripts/sample_logs.py --strategy 策略 [--index 索引] [--limit N]

# 策略：
#   errors_only   - 仅错误日志（默认用于事件）
#   warnings_up   - 警告和错误日志
#   around_time   - 围绕特定时间戳的日志
#   all           - 所有日志级别

# 示例：
python .claude/skills/observability-elasticsearch/scripts/sample_logs.py --strategy errors_only --index logs-production
python .claude/skills/observability-elasticsearch/scripts/sample_logs.py --strategy around_time --timestamp "2026-01-27T05:00:00Z" --window 5

Lucene查询语法

基本搜索

# 简单术语
error

# 短语
"connection refused"

# 字段搜索
level:ERROR

# 通配符
message:timeout*

# 多术语（隐式OR）
error warning

# 必需术语（AND）
+error +timeout

字段查询

# 精确匹配
level:ERROR

# 通配符
host:web-*

# 范围（数字）
status:[400 TO 599]

# 范围（日期）
@timestamp:[2024-01-15T10:00:00 TO 2024-01-15T11:00:00]

# 存在
_exists_:error.stack_trace

布尔运算符

# AND
error AND timeout

# OR
error OR warning

# NOT
error NOT debug

# 分组
(error OR warning) AND service:api

查询DSL（JSON）

匹配查询

{
  "query": {
    "match": {
      "message": "connection error"
    }
  }
}

术语查询（精确匹配）

{
  "query": {
    "term": {
      "level": "ERROR"
    }
  }
}

布尔查询（复合）

{
  "query": {
    "bool": {
      "must": [
        {"term": {"level": "ERROR"}},
        {"match": {"message": "timeout"}}
      ],
      "must_not": [
        {"term": {"service": "healthcheck"}}
      ],
      "filter": [
        {"range": {"@timestamp": {"gte": "now-1h"}}}
      ]
    }
  }
}

聚合

{
  "size": 0,
  "aggs": {
    "errors_by_service": {
      "terms": {
        "field": "service.keyword",
        "size": 10
      }
    }
  }
}

调查工作流程

标准事件调查

┌─────────────────────────────────────────────────────────────┐
│ 1. 统计优先（强制）                                           │
│    python get_statistics.py --index <索引>                    │
│    → 了解日志量、错误率、顶级模式                               │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
                     高错误率？
               ┌─────────────┴─────────────┐
               │                           │
       是 (>5%)                          否
               │                           │
               ▼                           ▼
┌─────────────────────────────┐  ┌───────────────────────────────────────────┐
│ 2. 快速路径                  │  │ 2. 目标调查                                │
│    直接采样错误             │  │    按特定标准过滤                          │
│    python sample_logs.py    │  │    python sample_logs.py --strategy all   │
│    --strategy errors_only   │  │    → 查找异常                              │
└─────────────────────────────┘  └───────────────────────────────────────────┘

快速命令参考

目标	命令
开始调查	`get_statistics.py --index X`
仅采样错误	`sample_logs.py --strategy errors_only --index X`
调查峰值	`sample_logs.py --strategy around_time --timestamp T`
所有日志	`sample_logs.py --strategy all --index X --limit 20`

常见聚合模式

错误随时间变化

{
  "size": 0,
  "query": {"term": {"level": "ERROR"}},
  "aggs": {
    "errors_over_time": {
      "date_histogram": {
        "field": "@timestamp",
        "fixed_interval": "5m"
      }
    }
  }
}

顶级错误消息

{
  "size": 0,
  "query": {"term": {"level": "ERROR"}},
  "aggs": {
    "top_errors": {
      "terms": {
        "field": "message.keyword",
        "size": 10
      }
    }
  }
}

嵌套聚合（按服务，然后按消息）

{
  "size": 0,
  "aggs": {
    "by_service": {
      "terms": {"field": "service.keyword", "size": 10},
      "aggs": {
        "by_message": {
          "terms": {"field": "message.keyword", "size": 5}
        }
      }
    }
  }
}

字段类型

关键词 vs 文本

keyword：精确匹配，可聚合（service.keyword）
text：全文搜索，不可聚合（message）

// 用于聚合，使用.keyword后缀
"terms": {"field": "service.keyword"}

// 用于全文搜索，使用文本字段
"match": {"message": "connection error"}

要避免的反模式

❌ 切勿跳过统计 - get_statistics.py是强制第一步
❌ 无限制查询 - 始终指定时间范围和限制
❌ 获取所有日志 - 使用采样策略，而非无限制搜索
❌ 忽略错误率 - 高错误率需立即调查
❌ 在聚合中使用文本字段 - 使用.keyword后缀进行术语聚合
❌ 通配符前缀 - *error成本高，优先使用error*或精确匹配

名称：elasticsearch-analysis 描述：使用Lucene查询语法和Query DSL进行Elasticsearch/OpenSearch日志分析。在通过ELK栈、OpenSearch或任何基于Elasticsearch的日志系统调查问题时使用。 允许工具：Bash(python *)