# grafana-pipline

**Repository Path**: adif0028/pipline

## Basic Information

- **Project Name**: grafana-pipline
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-24
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Grafana Pipeline 使用说明

**文档版本**: v1.0  
**适用版本**: Grafana Pipeline v1.0+  
**最后更新**: 2026-03-24

---

## 目录

1. [简介](#1-简介)
2. [安装](#2-安装)
3. [快速开始](#3-快速开始)
4. [配置详解](#4-配置详解)
5. [运行方式](#5-运行方式)
6. [输出说明](#6-输出说明)
7. [断点续传](#7-断点续传)
8. [故障排查](#8-故障排查)
9. [最佳实践](#9-最佳实践)
10. [常见问题](#10-常见问题)

---

## 1. 简介

Grafana Pipeline 是一个批量将 Grafana 仪表盘转换为观测云（Guance Cloud）格式的工具。支持：

- **批量处理**: 同时处理 100+ 仪表盘
- **流式转换**: 内存处理，最小化磁盘 IO
- **智能限流**: 自动控制 Grafana API 请求频率
- **断点续传**: 支持中断后恢复执行
- **死信队列**: 失败任务完整上下文保存

### 系统架构

```
UID列表 → API获取 → 内存缓冲 → 脚本转换 → 输出文件
    ↑         ↓          ↓          ↓
    └────  失败重试  ←  状态记录  ←  错误处理
```

---

## 2. 安装

### 2.1 环境要求

- **操作系统**: Windows / Linux / macOS
- **Python**: 3.8 或更高版本
- **依赖包**: requests, pyyaml, openpyxl, xlrd, pyxlsb, odfpy, pandas

### 2.2 安装步骤

#### 步骤 1: 下载代码

```bash
# 克隆或下载项目到本地
cd /path/to/pipeline
```

#### 步骤 2: 安装依赖

```bash
pip install -r requirements.txt
```

> **注意**: 如果只需要处理纯文本 CSV，可只安装核心依赖 `requests` 和 `pyyaml`。若需处理 Excel 文件（.xlsx/.xls/.xlsb/.ods），请完整安装所有依赖。

#### 步骤 3: 确认转换脚本

确保 `guance_optimized.py` 位于以下位置之一：
- 项目根目录 (`./guance_optimized.py`)
- `scripts/` 目录 (`./scripts/guance_optimized.py`)

---

## 3. 快速开始

### 3.1 准备 UID 列表

创建文本文件，每行一个仪表盘 UID：

```bash
# uids.txt
dashboard-001
dashboard-002
dashboard-003
```

### 3.2 配置环境变量

```bash
# Windows (PowerShell)
$env:GRAFANA_URL="https://grafana.example.com"
$env:GRAFANA_API_KEY="glsa_xxxxxxxx"

# Windows (CMD)
set GRAFANA_URL=https://grafana.example.com
set GRAFANA_API_KEY=glsa_xxxxxxxx

# Linux/macOS
export GRAFANA_URL="https://grafana.example.com"
export GRAFANA_API_KEY="glsa_xxxxxxxx"
```

### 3.3 运行工具

#### 方式 1: 从文本文件加载（每行一个 UID）

```bash
python main.py --input uids.txt
```

#### 方式 2: 从 CSV 文件加载（推荐）

从 Grafana 导出的 CSV 文件直接加载：

```bash
python main.py --csv grafana_dashboards_report.csv
```

指定自定义列名（如果 CSV 标题不同）：

```bash
python main.py --csv export.csv --csv-column "dashboard_uid"
```

#### 方式 3: 从 Excel 文件加载

支持加载多种电子表格格式（无需手动另存为 CSV）：

```bash
# Excel 2007+ (.xlsx, .xlsm)
python main.py --csv grafana_dashboards_report.xlsx

# Excel 97-2003 (.xls)
python main.py --csv grafana_dashboards_report.xls

# Excel Binary (.xlsb)
python main.py --csv grafana_dashboards_report.xlsb

# OpenDocument Spreadsheet (.ods)
python main.py --csv grafana_dashboards_report.ods
```

> **提示**: 即使文件被错误地重命名为 `.csv`，只要其内部是 Excel/ODS 格式，工具也会自动识别并正确读取。

### 3.4 查看输出

转换后的仪表盘保存在 `./guance_output/` 目录：

```
guance_output/
├── {uid}_{title}.json       # 成功转换的仪表盘
├── failed/                  # 失败任务
│   ├── {uid}_raw.json       # 原始 Grafana JSON
│   └── {uid}_error.json     # 错误上下文
└── report_*.json            # 执行报告
```

---

## 4. 配置详解

### 4.1 配置文件方式

创建 `config.yaml`：

```yaml
# Grafana 连接配置
grafana_url: "${GRAFANA_URL}"           # 支持环境变量
grafana_api_key: "${GRAFANA_API_KEY}"
grafana_timeout: 30                      # 请求超时(秒)
grafana_max_retries: 3                   # 最大重试次数
grafana_rate_limit_qps: 10              # API限流(QPS)
grafana_rate_limit_burst: 5             # 突发容量

# 流水线配置
max_memory_mb: 500                       # 内存上限

# 转换器配置
script_path: "./guance_optimized.py"    # 转换脚本路径
measurement: "prom"                      # measurement名称
converter_timeout: 60                    # 转换超时(秒)
input_mode: "stdin"                      # 输入模式(stdin/temp_file)
temp_file_fallback: true                 # stdin失败时回退

# 输出配置
output_directory: "./guance_output"
output_failed_directory: "./guance_output/failed"

# 状态持久化
state_enabled: true
state_file: "./pipeline.state"
state_save_interval: 30

# 日志配置
log_level: "INFO"                        # DEBUG/INFO/WARNING/ERROR
log_file: "./logs/pipeline.log"
log_format: "text"                       # text/json
```

### 4.2 命令行参数方式

#### 从文本文件加载

```bash
python main.py \
    --url https://grafana.example.com \
    --api-key glsa_xxxxxxxx \
    --input uids.txt \
    --output ./output \
    --measurement prom \
    --fetcher-workers 5 \
    --converter-workers 8 \
    --log-level INFO
```

#### 从 CSV 文件加载

```bash
python main.py \
    --url https://grafana.example.com \
    --api-key glsa_xxxxxxxx \
    --csv grafana_dashboards_report.csv \
    --csv-column "大盘UID" \
    --output ./output \
    --measurement prom \
    --log-level INFO
```

### 4.3 参数优先级

1. 命令行参数（最高优先级）
2. 环境变量
3. 配置文件
4. 默认值

### 4.4 配置参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--url` | string | - | Grafana URL |
| `--api-key` | string | - | API Token |
| `--input` | string | - | UID列表文件路径（每行一个UID） |
| `--csv` | string | - | CSV/Excel 文件路径（支持 .csv 和 .xlsx） |
| `--csv-column` | string | `大盘UID` | CSV中UID列名 |
| `--output` | string | `./guance_output` | 输出目录 |
| `--measurement` | string | `prom` | measurement名称 |
| `--fetcher-workers` | int | CPU*4 | 获取并发数 |
| `--converter-workers` | int | CPU*2 | 转换并发数 |
| `--buffer-size` | int | 动态计算 | 缓冲区大小 |
| `--log-level` | string | `INFO` | 日志级别 |
| `--log-file` | string | - | 日志文件路径 |
| `--resume` | flag | false | 断点续传 |

---

## 5. 运行方式

### 5.1 基本运行

```bash
python main.py --input uids.txt
```

### 5.2 使用配置文件

```bash
python main.py --config config.yaml --input uids.txt
```

### 5.3 断点续传

如果执行中断，使用 `--resume` 恢复：

```bash
python main.py --config config.yaml --input uids.txt --resume
```

### 5.4 调试模式

```bash
python main.py --input uids.txt --log-level DEBUG
```

### 5.5 JSON 格式日志

```bash
python main.py --input uids.txt --log-format json
```

---

## 6. 输出说明

### 6.1 成功输出

**文件路径**: `{output_directory}/{uid}_{title}.json`

**示例**:
```
guance_output/
├── dashboard-001_My Dashboard.json
├── dashboard-002_System Metrics.json
└── dashboard-003_Application Logs.json
```

### 6.2 失败输出

**死信队列目录**: `{output_failed_directory}/`

| 文件 | 内容 |
|------|------|
| `{uid}_raw.json` | 原始 Grafana 仪表盘 JSON |
| `{uid}_error.json` | 错误上下文（含错误信息、堆栈、时间戳）|

**错误文件示例**:
```json
{
  "uid": "dashboard-001",
  "title": "My Dashboard",
  "status": "failed_convert",
  "error": {
    "message": "Script error: ...",
    "code": 201,
    "script_stderr": "详细错误输出..."
  },
  "timings": {
    "fetch_ms": 150,
    "convert_ms": 0
  },
  "timestamp": "2026-03-24T10:00:00"
}
```

### 6.3 执行报告

**文件路径**: `{output_directory}/report_{timestamp}.json`

**内容示例**:
```json
{
  "timestamp": "2026-03-24T10:00:00",
  "duration_seconds": 120.5,
  "config": {
    "grafana_url": "https://grafana.example.com",
    "measurement": "prom"
  },
  "statistics": {
    "total": 100,
    "success": 95,
    "failed_fetch": 3,
    "failed_convert": 2
  },
  "failed_tasks": [...]
}
```

---

## 7. 断点续传

### 7.1 工作原理

工具定期保存执行状态到 `pipeline.state` 文件。中断后使用 `--resume` 参数可从上次状态恢复。

### 7.2 使用步骤

1. **正常执行**（被中断）:
   ```bash
   python main.py --input uids.txt
   # 处理到 50/100 时被中断
   ```

2. **恢复执行**:
   ```bash
   python main.py --input uids.txt --resume
   # 从第 50 个继续处理
   ```

### 7.3 注意事项

- 状态文件默认保存间隔为 30 秒
- 已完成任务不会重复处理
- 状态文件在执行成功后自动清理

---

## 8. 故障排查

### 8.1 常见问题及解决

#### 问题 1: 找不到转换脚本

**症状**:
```
FileNotFoundError: 未找到 guance_optimized.py
```

**解决**:
```bash
# 确认脚本位置
ls -la guance_optimized.py
# 或
ls -la scripts/guance_optimized.py

# 在配置中指定正确路径
script_path: "/absolute/path/to/guance_optimized.py"
```

#### 问题 2: Grafana API 认证失败

**症状**:
```
HTTP 401: Unauthorized
```

**解决**:
- 检查 API Token 是否有效
- 确认 Token 有查看仪表盘权限
- 验证 Grafana URL 是否正确

#### 问题 3: 转换超时

**症状**:
```
Timeout (60s)
```

**解决**:
```yaml
# 增加超时时间
converter_timeout: 120
```

#### 问题 4: 内存不足

**症状**:
```
MemoryError 或系统卡顿
```

**解决**:
```yaml
# 降低并发数和缓冲区
fetcher_concurrency: 3
converter_concurrency: 4
buffer_size: 20
max_memory_mb: 200
```

#### 问题 5: 限流触发

**症状**:
```
HTTP 429: Too Many Requests
```
或日志中出现大量 `获取失败 [uid]: 认证/权限不足 (HTTP 401/403)`（部分 Grafana 实例在限流时返回 401/403）。

**原因**: 多线程并发请求频率过高，触发了 Grafana 的限流机制。

**解决**: 工具已内置自动保护机制：每个 FetcherWorker 成功拉取一个仪表盘后，会自动休息 1-3 秒（随机间隔），避免突发请求。如需进一步降低频率，可调整配置：
```yaml
# 降低 QPS
grafana_rate_limit_qps: 5
grafana_rate_limit_burst: 2

# 减少获取并发数
fetcher_concurrency: 4
```

#### 问题 6: 获取失败与转换失败的区分

流水线分为两个阶段，日志关键词不同：

| 阶段 | 日志关键词 | 含义 |
|------|-----------|------|
| **获取 (Fetch)** | `[Fetcher-X] 获取失败 [uid]: ...` | 从 Grafana API 获取 JSON 失败（404/401/超时/网络错误） |
| **转换 (Convert)** | `[Converter-X] 失败: uid - Script error: ...` | 调用 `guance_optimized.py` 转换 JSON 失败 |
| **转换回退** | `[ScriptConverter] stdin 模式失败，回退到 temp_file` | 转换子进程 stdin 传递失败，尝试备用模式（非致命） |

**常见获取失败原因**：
- `仪表盘不存在 (HTTP 404)` → UID 错误或该仪表盘已被删除
- `认证/权限不足 (HTTP 401/403)` → API Key 无效或权限不够
- `触发 Grafana 限流 (HTTP 429)` → 请求太快，建议降低 QPS
- `请求超时` → 网络不稳定或 Grafana 响应慢

**常见转换失败原因**：
- `无效JSON语法错误` → 获取到的 JSON 损坏（此前 Windows 中文环境有编码问题，已修复）
- `Script error` → `guance_optimized.py` 不支持该仪表盘中的某些面板类型

#### 问题 7: 日志中出现 #NAME? 等无效 UID

**症状**: 日志中出现 `#NAME? 失败(1/4)` 等获取失败记录。

**原因**: 数据源（Excel 文件）中包含公式错误值（如 `#NAME?`、`#REF!`），这些值被当作 UID 送入 Grafana API 后返回 404。

**解决**: 工具已自动过滤以下 Excel 公式错误值，无需手动清理：
```
#NAME?, #REF!, #VALUE!, #N/A, #NULL!, #DIV/0!, #NUM!
```
过滤情况会在日志中显示为 `无效 UID`。

#### 问题 8: 子进程编码错误（Windows 中文环境）

**症状**（旧版本）：
```
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xbe
```
或转换阶段全部失败，报 `Script error: 无效JSON语法错误`。

**原因**: Windows 中文环境下，转换子进程默认使用 GBK 编码读取 stdin，而父进程发送的是 UTF-8 编码的 JSON，导致 JSON 损坏。

**解决**: 已修复。工具会自动设置 `PYTHONIOENCODING=utf-8` 环境变量，确保子进程使用 UTF-8 编码。无需手动配置。

### 8.2 日志分析

**查看实时日志**:
```bash
tail -f logs/pipeline.log
```

**日志级别说明**:
- `DEBUG`: 详细调试信息
- `INFO`: 常规运行信息
- `WARNING`: 警告信息
- `ERROR`: 错误信息

**关键日志关键词**:
```bash
# 查看错误
grep ERROR logs/pipeline.log

# 查看进度
grep "进度" logs/pipeline.log

# 查看失败任务
grep "失败" logs/pipeline.log
```

### 8.3 调试技巧

#### 测试单个仪表盘

```bash
# 创建单 UID 文件
echo "dashboard-001" > test_uid.txt

# 调试模式运行
python main.py --input test_uid.txt --log-level DEBUG
```

#### 验证脚本功能

```bash
# 测试 stdin 模式
echo '{"title":"Test","panels":[]}' | \
  python guance_optimized.py convert-json --json - --measurement prom
```

---

## 9. 最佳实践

### 9.1 生产环境部署

1. **使用配置文件**:
   ```bash
   python main.py --config production.yaml --input uids.txt
   ```

2. **设置日志轮转**:
   ```bash
   # 使用 logrotate (Linux)
   # 或定时清理日志文件
   ```

3. **监控执行**:
   ```bash
   # 后台运行
   nohup python main.py --config config.yaml --input uids.txt > run.log 2>&1 &
   
   # 查看进度
   tail -f run.log
   ```

### 9.2 大规模处理

**分批处理**:
```bash
# 将 1000 个 UID 分成 10 批
split -l 100 uids.txt batch_

# 逐批处理
for batch in batch_*; do
  python main.py --input $batch --output ./output
  sleep 10
done
```

**调整并发**:
```yaml
# 根据 Grafana 性能调整
fetcher_concurrency: 10    # IO 密集型，可适当提高
converter_concurrency: 8   # CPU 密集型，根据核心数调整
```

**自动限流保护**:
工具内置了双重保护机制，无需手动控制：
1. **令牌桶限流器**：控制全局 API 请求频率（默认 QPS=10）
2. **请求后随机间隔**：每个 FetcherWorker 成功拉取一个仪表盘后，会自动休息 1-3 秒，避免突发请求触发 Grafana 限流

如需处理大量仪表盘（1000+），建议：
- 保持默认配置即可，自动间隔机制会自适应控制频率
- 如需加速，可适当提高 `fetcher_concurrency`，但不要超过 Grafana 实例的承载能力

### 9.3 失败重试

```bash
# 提取失败 UID
cat guance_output/report_*.json | \
  jq -r '.failed_tasks[].uid' > failed_uids.txt

# 重新处理
python main.py --input failed_uids.txt --output ./output_retry
```

---

## 10. 常见问题

### Q1: 支持哪些 Grafana 版本？

A: 支持 Grafana 6.x 及以上版本。工具通过 API 获取仪表盘，与版本关联较小。

### Q2: 如何处理私有 Grafana 实例？

A: 确保网络可达，配置正确的 URL 和 API Token 即可。

### Q3: 转换后的仪表盘如何导入观测云？

A: 使用观测云控制台的导入功能，选择生成的 JSON 文件。

### Q4: 是否支持增量更新？

A: 目前不支持。建议按需重新转换或选择性处理。

### Q5: 如何处理特殊字符的仪表盘名称？

A: 工具会自动清理文件名中的非法字符，无需手动处理。

### Q6: Windows 和 Linux 行为是否一致？

A: 核心功能一致。路径分隔符等细节会自动处理。

### Q7: CSV/Excel 文件中的无效 UID 会怎样处理？

A: 工具会自动过滤以下无效 UID：
- 全零值（如 `000000000`）
- 空值或仅包含空白
- `undefined`、`null`、`none` 等特殊值
- Excel 公式错误值：`#NAME?`、`#REF!`、`#VALUE!`、`#N/A`、`#NULL!`、`#DIV/0!`、`#NUM!`

过滤情况会在日志中显示。

### Q8: 如何确认 CSV/Excel 文件被正确读取？

A: 查看日志输出，应有类似以下内容：
```
INFO - 检测到电子表格格式 [xlsx]，读取: dashboard.csv
INFO - 电子表格加载统计: {'total_rows': 1000, 'valid_uids': 998, 'invalid_uids': 2, 'suspicious_uids': 0, 'duplicates': 0}
INFO - 成功加载 998 个有效 UID
```

### Q9: CSV 列名不是"大盘UID"怎么办？

A: 使用 `--csv-column` 参数指定正确的列名：
```bash
python main.py --csv export.csv --csv-column "dashboard_uid"
```

工具支持自动检测以下列名（按优先级）：`大盘UID`、`仪表盘UID`、`dashboard_uid`、`uid`、`UID`、`Dashboard UID`。也支持列名带前后空格的情况。

---

## 附录

### A. 命令行速查表

| 场景 | 命令 |
|------|------|
| 基本运行 | `python main.py --input uids.txt` |
| 从 CSV 运行 | `python main.py --csv grafana_dashboards_report.csv` |
| 从 Excel 运行 | `python main.py --csv grafana_dashboards_report.xlsx` |
| 从 .xls 运行 | `python main.py --csv grafana_dashboards_report.xls` |
| 从 .xlsb 运行 | `python main.py --csv grafana_dashboards_report.xlsb` |
| 从 .ods 运行 | `python main.py --csv grafana_dashboards_report.ods` |
| CSV 指定列名 | `python main.py --csv export.csv --csv-column "uid"` |
| 使用配置 | `python main.py --config config.yaml --input uids.txt` |
| 断点续传 | `python main.py --input uids.txt --resume` |
| 调试模式 | `python main.py --csv report.csv --log-level DEBUG` |
| JSON 日志 | `python main.py --input uids.txt --log-format json` |

### B. 配置文件模板

见本文档 [4.1 配置文件方式](#41-配置文件方式) 章节。

### C. 获取帮助

```bash
# 查看帮助
python main.py --help

# 查看版本
python main.py --version
```

---

**文档结束**

如有问题，请参考故障排查章节或查看执行报告。