在AWS中国区的EMR集群中实现基于向量语义搜索的HBase运维诊断系统

HBase 作为大规模分布式数据库，其日志分散在 Master 和多个 RegionServer 节点上。当集群出现异常时，运维人员需要：

1. SSH 到多个节点 手动收集日志
2. grep 关键字 查找 ERROR/WARN
3. 人工关联 多节点日志时序
4. 依赖经验 判断根因

这个过程耗时长、易遗漏，尤其对于 HBase 这类复杂系统，问题根因往往隐藏在跨节点、跨时间维度的日志关联中。

参考 AWS Blog Detect and resolve HBase inconsistencies faster with AI on Amazon EMR 的思路可以通过如下方式来优化这一过程，即将日志转换为向量嵌入，支持自然语言查询。然后利用大语言模型理解日志语义，提供诊断建议

系统架构设计

整体架构
用户交互层
EC2处理节点
HBase集群
日志归档
日志归档
日志归档
日志归档
process_logs.py
hbase_ai.py
Master 节点

hbase-master
RegionServer 节点 1

hbase-rs
RegionServer 节点 2

hbase-rs
...
S3 Bucket

aws-logs-.../

elasticmapreduce/

j-XXX/node/
S3 Download

(boto3)
Log Parser

(regex)
Embedding API
zvec 向量数据库

(WAL持久化)
用户输入: RegionServer 为什么宕机?

1. Embedding: 问题 → 向量

2. zvec 查询: 向量相似度搜索

3. 上下文构建: Top-K 日志

4. LLM 分析: 日志 + 问题 → 诊断报告
   输出: 根因分析 + 影响范围 + 修复步骤 + 预防措施

核心概念

向量语义搜索

传统关键字搜索基于词法匹配 (Lexical Matching)，如 grep "ERROR"，只能找到包含 "ERROR" 的行。但问题在于用户问 "RegionServer 为什么宕机"，日志里没有 "宕机" 这个词，并且同一概念有多种表达："abort", "shutdown", "exit", "fail", "crash"

向量语义搜索通过将文本映射到高维向量空间，语义相似的文本向量距离近来解决这个问题，语义相似的查询和日志，即使没有共同关键词，向量距离也近。

这里选择zvec作为测试的向量数据库，核心操作如下

import zvec

# 1. 创建 collection
schema = zvec.CollectionSchema(
    name="hbase_logs",
    fields=[
        zvec.FieldSchema("level", zvec.DataType.STRING),
        zvec.FieldSchema("message", zvec.DataType.STRING),
        # ...
    ],
    vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 1024),
)
collection = zvec.create_and_open(path="zvec_data", schema=schema)

# 2. 插入文档
doc = zvec.Doc(
    id="log_001",
    vectors={"embedding": [0.1, 0.2, ...]},  # 1024 维向量
    fields={"level": "ERROR", "message": "..."},
)
collection.insert([doc])

# 3. 查询
results = collection.query(
    zvec.VectorQuery("embedding", vector=query_vector),
    topk=20,
)

HBase 日志格式

标准格式

2026-05-18T15:33:25,471 INFO  [main] regionserver.HRegionServer: STARTING ...
│                      │      │      │ │                                │
│                      │      │      │ │                                └─ 消息内容
│                      │      │      │ └─ 日志源 (类名)
│                      │      │      └─ 线程名
│                      │      └─ 日志级别
│                      └─ 时间戳 (ISO 8601)
└─ 日期

多行异常堆栈

2026-05-18T15:33:25,471 ERROR [main] regionserver.HRegionServer: RegionServer abort
java.lang.RuntimeException: HRegionServer Aborted
        at org.apache.hadoop.hbase.regionserver.HRegionServerCommandLine.start(...)
        at org.apache.hadoop.hbase.regionserver.HRegionServerCommandLine.run(...)
Caused by: java.io.IOException: Connection refused
        at org.apache.hadoop.hbase.ipc.AbstractRpcClient....

解析时需要将堆栈合并到前一条日志的 message 字段。

LLM Agent 设计

System Prompt

SYSTEM_PROMPT = """你是 HBase 运维专家。根据提供的日志上下文分析问题，回答包含:
1. 根因分析
2. 影响范围
3. 修复步骤（含具体命令）
4. 预防措施

用中文回答，技术术语保留英文。"""

上下文构建

context = "\n".join([
    f"[{r.timestamp}] [{r.level}] {r.source} ({r.host}) --- {r.message[:300]}"
    for r in results[:15]  # Top 15 日志
])

prompt = f"""## 相关日志
{context}

## 问题
{user_question}"""

实现详解

日志解析器 process_logs.py

LOG_PATTERN = re.compile(
    r"(?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2},\d{3})\s+"
    r"(?P<level>INFO|WARN|ERROR|FATAL|DEBUG)\s+"
    r"\[(?P<thread>[^\]]+)\]\s+"
    r"(?P<source>[^\s:]+(?:\.[^\s:]+)*):\s+"
    r"(?P<message>.*)"
)

多行堆栈合并

def parse_log_content(content: str, log_type: str, host: str) -> list[dict]:
    entries = []
    current = None

    for line in content.splitlines():
        m = LOG_PATTERN.match(line)
        if m:
            # 新日志条目开始
            if current:
                entries.append(current)
            current = {
                "timestamp": m.group("timestamp"),
                "level": m.group("level"),
                "thread": m.group("thread"),
                "source": m.group("source"),
                "message": m.group("message"),
                "log_type": log_type,
                "host": host,
            }
        elif current:
            # 多行续行: 异常堆栈
            stripped = line.strip()
            if line.startswith(("\t", "        ")) or stripped.startswith(("Caused by:", "at ", "... ")):
                current["message"] += "\n" + stripped

    if current:
        entries.append(current)
    return entries

S3 日志发现

def list_hbase_log_keys(cluster_id: str) -> list[dict]:
    """列出指定集群下所有 HBase 相关日志的 S3 key"""
    prefix = f"elasticmapreduce/{cluster_id}/node/"
    keys = []

    paginator = s3.get_paginator("list_objects_v2")
    for page in paginator.paginate(Bucket=LOG_BUCKET, Prefix=prefix):
        for obj in page.get("Contents", []):
            key = obj["Key"]
            # 只取 hbase 日志
            if "applications/hbase/" in key and key.endswith(".log.gz"):
                if any(k in key for k in [
                    "hbase-hbase-master-",
                    "hbase-hbase-regionserver-",
                    "hbase-master-manual-",  # 手动上传
                    "hbase-regionserver-manual-",  # 手动上传
                ]):
                    keys.append({"key": key, "size": obj["Size"]})

    return keys

向量化

批量 Embedding关键参数:

• batch_size = 8: 每批 8 条日志，平衡吞吐和内存
• timeout = 60s: 向量化较慢，需足够超时

def generate_embeddings(texts: list[str]) -> list[list[float]]:
    """调用本地 Embedding API"""
    r = requests.post(
        f"{API_BASE}/embeddings",
        headers=HEADERS,
        json={"input": texts, "model": EMBEDDING_MODEL},
        timeout=60,
    )
    r.raise_for_status()
    data = r.json()
    return [d["embedding"] for d in data["data"]]

zvec 入库

def get_collection():
    schema = zvec.CollectionSchema(
        name="hbase_logs",
        fields=[
            zvec.FieldSchema("timestamp", zvec.DataType.STRING),
            zvec.FieldSchema("level", zvec.DataType.STRING),
            zvec.FieldSchema("thread", zvec.DataType.STRING),
            zvec.FieldSchema("source", zvec.DataType.STRING),
            zvec.FieldSchema("message", zvec.DataType.STRING),  # 最大 1000 字符
            zvec.FieldSchema("log_type", zvec.DataType.STRING),
            zvec.FieldSchema("host", zvec.DataType.STRING),
            zvec.FieldSchema("cluster_id", zvec.DataType.STRING),
        ],
        vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 1024),
    )
    return zvec.create_and_open(path=ZVEC_DIR, schema=schema)

# 插入
docs = [
    zvec.Doc(
        id=f"{cluster_id}_{i}",
        vectors={"embedding": embeddings[i]},
        fields={
            "timestamp": entry["timestamp"],
            "level": entry["level"],
            # ...
        },
    )
    for i, entry in enumerate(batch)
]
collection.insert(docs)

AI 助手逻辑

hbase_ai.py语义搜索

def search(query, top_k=20):
    # 1. 问题向量化
    vec = embed(query)
    
    # 2. zvec 查询
    col = zvec.open(ZVEC_DIR)
    results = col.query(zvec.VectorQuery("embedding", vector=vec), topk=top_k)
    
    return results

LLM 分析

def ask_llm(context, question):
    r = requests.post(
        f"{API_BASE}/chat/completions",
        headers=HEADERS,
        json={
            "model": LLM_MODEL,
            "messages": [
                {"role": "system", "content": SYSTEM_PROMPT},
                {"role": "user", "content": f"## 相关日志\n{context}\n\n## 问题\n{question}"},
            ],
            "temperature": 0.3,  # 低温度，更确定性
            "max_tokens": 2048,
        },
        timeout=120,
    )
    r.raise_for_status()
    return r.json()["choices"][0]["message"]["content"]

REPL 交互

def main():
    console.print("[bold]HBase AI 故障排查助手[/bold]  (quit退出)\n")
    while True:
        q = input("🔍> ").strip()
        if q.lower() in ("quit", "exit", "q"):
            break
        
        # 搜索
        results = search(q)
        console.print(f"[green]{len(results)} 条相关日志[/green]")
        
        # 构建上下文
        ctx = "\n".join([
            f"[{r.fields['timestamp']}] [{r.fields['level']}] "
            f"{r.fields['source']} ({r.fields['host']}) --- "
            f"{r.fields['message'][:300]}"
            for r in results[:15]
        ])
        
        # LLM 分析
        console.print("[yellow]AI 分析中...[/yellow]")
        answer = ask_llm(ctx, q)
        console.print(Markdown(answer))

部署与测试

日志采集

EMR 集群启动时指定 --log-uri，日志自动归档到 S3：

aws emr create-cluster \
  --name "HBase Cluster" \
  --release-label emr-6.15.0 \
  --applications Name=HBase \
  --instance-type m5.xlarge \
  --instance-count 3 \
  --log-uri s3://aws-logs-ACCOUNT-cn-north-1/elasticmapreduce \
  ...

注意: DailyRollingFileAppender 每天午夜或达到大小阈值才滚动上传，运行中日志需手动采集。

手动采集脚本如下

#!/bin/bash
# 在 EMR Master 节点执行

CLUSTER_ID="j-2DRE1ETLDQFIW"
S3_BUCKET="aws-logs-<accountid>-cn-north-1"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Master 日志
aws s3 cp /var/log/hbase/hbase-hbase-master-*.log \
  s3://${S3_BUCKET}/elasticmapreduce/${CLUSTER_ID}/node/$(hostname)/applications/hbase/hbase-master-manual-${TIMESTAMP}.log.gz

# RegionServer 日志 (在各个 RS 节点执行)
aws s3 cp /var/log/hbase/hbase-hbase-regionserver-*.log \
  s3://${S3_BUCKET}/elasticmapreduce/${CLUSTER_ID}/node/$(hostname)/applications/hbase/hbase-regionserver-manual-${TIMESTAMP}.log.gz

处理测试

$ .venv/bin/python process_logs.py j-2DRE1ETLDQFIW

============================================================
处理集群: j-2DRE1ETLDQFIW
============================================================
  找到 4 个日志文件
    elasticmapreduce/j-2DRE1ETLDQFIW/node/.../hbase-hbase-master-*.log.gz (45.2 KB)
    elasticmapreduce/j-2DRE1ETLDQFIW/node/.../hbase-hbase-regionserver-*.log.gz (38.1 KB)
    ...

  [1/4] 下载: hbase-hbase-master-ip-192-168-29-215....log.gz
    解析到 591 条日志

  [2/4] 下载: hbase-hbase-regionserver-ip-192-168-27-59....log.gz
    解析到 342 条日志

  ...

  总计 981 条, 其中 WARN/ERROR/FATAL: 939 条

    8/939
    16/939
    ...
    936/939
    939/939

  完成! zvec 共 939 条

端到端测试

$ .venv/bin/python hbase_ai.py

HBase AI 故障排查助手  (quit退出)

🔍> RegionServer 启动失败

20 条相关日志

AI 分析中...

# HBase RegionServer 启动失败问题分析

## 1. 根因分析

### 关键现象识别
| 现象 | 分析 |
|------|------|
| `HRegionServer Aborted` | RegionServer 主动触发 abort 流程 |
| 多节点同时失败 | 集群级问题，非单节点故障 |

### 最可能的根因（按概率排序）

**根因 #1: ZooKeeper 连接失败** ⭐ 最可能
- RegionServer 启动时必须连接 ZK 进行注册
...

## 2. 影响范围
...

## 3. 修复步骤
...

## 4. 预防措施
...

使用演示

RegionServer 异常退出

用户输入:

RegionServer 为什么会异常退出？

系统响应:

【语义搜索】找到 20 条相关日志:

1. [ERROR] regionserver.HRegionServerCommandLine
   主机: ip-192-168-27-59.cn-north-1.compute.internal
   消息: Region server exiting
   java.lang.RuntimeException: HRegionServer Aborted...

2. [ERROR] regionserver.HRegionServerCommandLine
   主机: ip-192-168-28-132.cn-north-1.compute.internal
   消息: Region server exiting...

...

【AI 分析】

根据提供的日志，我分析如下：

## 1. 根因分析

### 关键现象识别

| 现象 | 分析 |
|:---|:---|
| 多个 RegionServer 同时退出 | 时间集中在 15:33-15:34，非单点故障 |
| 日志中出现 `manual-20260518_162114` | 这是 **手动操作标识**，表明有人为干预 |
| 异常简洁，无详细堆栈 | 属于 **优雅退出** 而非崩溃 |

### 根因判定

**RegionServer 被手动触发 Rolling Restart（滚动重启）或集群维护操作**

具体证据：
- `manual-20260518_162114` 是 HBase 运维工具生成的操作标记
- 时间戳表示操作发起时间为 2026-05-18 16:21:14
- 多个节点在相近时间退出，符合 Rolling Restart 特征

## 2. 影响范围

| 维度 | 影响 |
|:---|:---|
| **服务可用性** | 短暂影响，Rolling Restart 期间部分 Region 不可读写 |
| **数据完整性** | 无数据丢失，HBase WAL 保证数据安全 |

## 3. 修复步骤

### 步骤 1：确认当前集群状态

echo "status 'detailed'" | hbase shell


### 步骤 2：若 RegionServer 未自动恢复，手动启动

sudo systemctl start hbase-regionserver

## 4. 预防措施

| 措施 | 具体配置/操作 |
|:---|:---|
| **操作审计** | 启用 HBase Audit Log |
| **变更窗口** | 将 Rolling Restart 限制在低峰期 |

WAL 目录丢失

用户输入:

WAL 目录丢失怎么办

系统响应:

【语义搜索】找到 18 条相关日志:

1. [ERROR] region.MasterRegion
   主机: ip-192-168-29-215.cn-north-1.compute.internal
   消息: UNEXPECTED: WAL directory for MasterRegion is missing.
   hdfs://.../user/hbase/WAL/MasterData/...

...

【AI 分析】

## 1. 根因分析

**HMaster 的 WAL 目录在 HDFS 上丢失**，可能原因：
1. HDFS 数据损坏
2. 误删除 `/user/hbase/WAL/MasterData/` 目录
3. HMaster 上次关闭时未正确清理

## 2. 修复步骤

```bash
# 1. 检查目录是否存在
hdfs dfs -ls /user/hbase/WAL/MasterData/

# 2. 如果丢失，手动创建
hdfs dfs -mkdir -p /user/hbase/WAL/MasterData/WALs/...

# 3. 重启 HMaster
sudo systemctl restart hbase-master

Region 分配问题

用户输入:

Region 分配状态异常

系统响应:

【语义搜索】找到 22 条相关日志:

1. [WARN] assignment.OpenRegionProcedure
   主机: ip-192-168-27-59.cn-north-1.compute.internal
   消息: Received report OPENED transition from ...
   for state=OPENING, server=completely different...

...

【AI 分析】

## 问题分析

存在 **Region 状态不一致**：
- RegionServer 报告 Region 已 OPENED
- 但 Master 记录的状态是 OPENING
- 这通常发生在 RegionServer 与 Master 网络分区或 RegionServer 重启后

## 修复步骤

```bash
# 使用 HBCK2 修复
hbase hbck -j /usr/lib/hbase/hbase-hbck2.jar assigns <region-encoded-name>

# 或 bypass 卡住的 procedure
hbase hbck -j /usr/lib/hbase/hbase-hbck2.jar bypass --fix <pid>

参考资料

• https://aws.amazon.com/cn/blogs/big-data/detect-and-resolve-hbase-inconsistencies-faster-with-ai-on-amazon-emr/