Tshrag-MetricDB 0.1.0

MetricDB is a database for storing and querying time based metrics data.

MetricDB

MetricDB 是一个面向测试指标的轻量级时序数据库，提供灵活的指标元数据管理和高效的数据存储查询能力。

文档目录

1. 快速开始 - 基本安装和使用方法
2. 项目结构 - 代码组织结构说明
3. 核心模块 - 基础数据类型和存储引擎
4. API 设计 - 接口规范与实现细节
5. 客户端与服务端 - 系统组件交互说明

核心特性

• 支持多维指标元数据管理
• 提供 HTTP/WebSocket 双协议接口
• 内置时间序列数据存储引擎
• 强类型化的数据模型定义

1. 快速开始

安装依赖

pip install -r requirements.txt

启动服务

python -m metricdb.server

使用示例

管理指标元数据

# 创建指标
curl -X POST http://localhost:8000/metric/info/temperature \
     -H "Content-Type: application/json" \
     -d '{"desc": "设备温度", "unit": "℃"}'

# 查询指标
curl http://localhost:8000/metric/info/temperature

写入指标数据

# 添加记录
curl -X POST http://localhost:8000/metric/entry/temperature \
     -H "Content-Type: application/json" \
     -d '{"time": 1620000000, "value": 25.5}'

查询时序数据

# 获取最近1小时数据
curl "http://localhost:8000/metric/entry/temperature?start_time=1619996400&end_time=1620000000"

2. 项目结构

metricdb/
 ├── core/ # 核心数据类型
 │   ├── metric.py # 指标模型定义
 │   ├── time.py # 时间处理模块
 │   └── ...
 ├── api/
 │   ├── info/ # 元数据接口
 │   │   ├── http.py # HTTP 路由
 │   │   └── ws.py # WebSocket 路由
 │   └── entry/ # 时序数据接口
 ├── client/ # 客户端实现
 ├── server/ # 服务端入口
 └── test/ # 测试套件
     ├── test_api.py # 接口测试
     └── test_core_*.py # 核心模块测试

主要模块说明：

• Core: 定义基础数据类型和存储引擎
• API: 实现对外服务接口
• Client: 提供本地/远程访问客户端
• Server: 基于 FastAPI 的服务端实现

3. 核心模块

基础类型

• Time: 统一时间戳处理（纳秒精度）
• MetricKey: 指标唯一标识符（字符串类型）
• TestId/DutId: 测试/设备标识符

核心模型

class TMetricInfo:
    key: str           # 指标键
    desc: str          # 指标描述
    unit: str          # 计量单位
    create_time: int   # 创建时间戳

class TMetricEntry:
    time: int          # 记录时间
    value: float       # 指标数值
    test: Optional[str] # 关联测试ID
    dut: Set[str]      # 关联设备集合

存储引擎

MetricDB类提供：

• 内存索引的元数据管理
• 基于时间分片的存储优化
• 自动化的数据持久化

4. API 设计

接口规范

资源	HTTP 方法	路径格式	功能
元数据	GET	/metric/info/{key}	查询指标定义
	POST	/metric/info/{key}	更新指标定义
时序数据	GET	/metric/entry/{key}	查询数据记录
	POST	/metric/entry/{key}	添加数据记录

WebSocket 支持

• /metric/info: 实时元数据更新通道
• /metric/entry: 流式数据写入接口

查询参数

class QueryParams:
    start_time: int    # 起始时间戳
    end_time: int      # 结束时间戳
    test: Optional[str] # 测试过滤
    dut: List[str]     # 设备过滤

5. 客户端与服务端

服务端特性

• 基于 Uvicorn 的异步服务
• 支持 SQLite 后端存储
• 配置项：

  app = MdbAPI(
      db_path="metricdb.db",  # 数据库路径
      cache_size=1000        # 内存缓存条目数
  )
  

客户端类型

• 本地客户端：直连数据库引擎
• 远程客户端：通过 HTTP/WebSocket 通信

使用示例

from metricdb.client import MdbClient

# 创建远程客户端
client = MdbClient.remote("http://localhost:8000")

# 查询数据
entries = client.query_metric_entry(
    key="temperature",
    start_time=1619996400,
    end_time=1620000000
)