TraceStudio

TraceStudio 是一个分布式的、节点式的自动化性能分析平台。它采用 Master-Worker 架构，旨在构建通用的性能数据分析与自动化流水线。

核心理念 (Core Concepts)

• 分布式架构:
  • Server (The Hub): 负责 API 网关、图解析与任务分发。
  • Client (The Worker): 无头（Headless）计算节点，负责算力贡献与自定义逻辑执行。
• BYOC (Bring Your Own Compute): 允许用户接入本地 Client，运行自己定义的私有节点逻辑，实现数据不出域或利用本地特定环境。
• 协议先行 (Protocol First): pytrace 核心库定义了一切契约（NodeBase, Specs, 序列化），Server 与 Client 必须严格遵守同一套标准。
• 去 UI 化: 后端不包含 Web 前端代码，仅提供 API 供外部前端调用。

架构拓扑 (Architecture)

/
├── pytrace/             # [核心共享库] (Python Package)
│   ├── api/             # [面向用户] Node, Decorators, IO
│   ├── runtime/         # [面向系统] Executor, Registry, Context
│   ├── model/           # [面向数据] Specs, Enums, Data
│   ├── internal/        # [面向框架] MetaMap, Constants
│   └── nodes/           # 通用标准节点库
├── server/              # [中心服务器] (The Hub)
│   ├── api/             # HTTP API (FastAPI)
│   └── dispatcher/      # 路由分发器 (基于能力的路由)
├── client/              # [计算节点] (The Headless Worker)
│   └── registry/        # 本地能力注册
└── docs/                # 协议文档

核心组件说明

1. Pytrace (Shared Library)

系统的“通用语言”。Server 和 Client 必须依赖完全一致的 pytrace 版本。

• TraceNode: 所有可执行节点的抽象基类。
• Specs: 使用 Pydantic 定义的数据模型 (NodeSpec, PortSpec, ParamSpec)，用于生成前端元数据。

2. Server (The Hub)

• 能力路由 (Capability-Based Routing): 维护一张路由表，记录哪个 Client 拥有哪个自定义 Node。
• 智能缓存: 基于 Hash(NodeVersion + InputData + Params) 进行结果缓存。

3. Client (The Worker)

• 握手机制: 启动时向 Server 汇报自己拥有的节点列表 (Capabilities)。
• 任务执行: 监听任务 -> 反序列化 (dill) -> 执行 -> 序列化结果 -> 返回。

开发指南：定义节点

TraceStudio 使用装饰器驱动的方式来定义节点。所有节点需继承自 pytrace.api.node.TraceNode。

示例代码

pip install -e .

from typing import Any
from pytrace.api.node import TraceNode
from pytrace.api.decorators import input_port, output_port, parameter, node_meta

@node_meta(
    display_name="Threshold Filter", 
    icon="filter-icon", 
    description="Filters data based on a numeric threshold."
)
class ThresholdFilterNode(TraceNode):
    
    # 定义输入端口 (注意: label 字段是必填的，用于 UI 显示)
    @input_port(name="data_in", label="Input Data", type="dataframe")
    
    # 定义输出端口
    @output_port(name="data_out", label="Filtered Data", type="dataframe")
    
    # 定义可配置参数
    @parameter(name="threshold", label="Threshold Value", type="float", default=0.5)
    def process(self, io: Any, context: Any) -> None:
        """
        节点的执行逻辑。
        """
        # 1. 获取输入
        # (假设 io 提供了 get_input 方法)
        data = io.get_input("data_in")
        
        # 2. 获取参数
        thresh = self.params.get("threshold", 0.5)
        
        # 3. 执行业务逻辑
        # result = data[data['value'] > thresh]
        
        # 4. 设置输出
        # io.set_output("data_out", result)
        pass

启动服务

uvicorn server.app.main:app --reload