Metadata-Version: 2.4
Name: jupyterlab-server-monitor
Version: 0.2.0
Summary: An extensible JupyterLab server telemetry sidebar.
Project-URL: Homepage, https://github.com/wxyhgk/jupyterlab-server-monitor
Project-URL: Repository, https://github.com/wxyhgk/jupyterlab-server-monitor
Project-URL: Issues, https://github.com/wxyhgk/jupyterlab-server-monitor/issues
Author: wxyhgk
License: BSD-3-Clause
License-File: LICENSE
Keywords: gpu,jupyter,jupyterlab,monitoring,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: jupyter-server<3,>=2
Requires-Dist: jupyterlab<5,>=4.2
Requires-Dist: psutil>=5.9
Description-Content-Type: text/markdown

# JupyterLab Server Monitor

一个用于查看服务器健康状态和资源遥测信息的紧凑型 JupyterLab 4
侧边栏扩展。目前支持显示 CPU、内存、GPU、磁盘、网络、主机、
Jupyter 内核、终端以及 Jupyter Server 进程指标。

后端采用 Provider 平台架构。后续可以添加 Slurm、Codex CLI、
Claude Code 等集成，而不需要把采集逻辑耦合到 HTTP Handler 或
系统监控界面中。

## 安装

```bash
python -m pip install jupyterlab-server-monitor
```

前端开发环境：

```bash
npm install
npm run build
python -m pip install --force-reinstall --no-deps .
```

安装完成后重启 JupyterLab，并验证服务端扩展和前端扩展：

```bash
jupyter server extension list
jupyter labextension list
```

## 架构

```text
jupyterlab_server_monitor/
├── core/                  Provider 契约、注册表、调度器和缓存
├── providers/             内置指标采集器
├── defaults.json          采集命令、超时和过滤规则
├── handlers.py            需要认证的 Jupyter Server API
└── metrics.py             原始采样器的兼容适配层

src/
├── core/                  API 客户端、状态和面板调度
├── components/            可复用的圆环、指标网格和表格
├── providers/             Provider 专用前端视图
└── index.ts               JupyterLab 插件注册入口
```

每个 Provider 只负责一个边界明确的遥测领域。Provider 声明稳定名称、
分类和独立采集周期，并返回可以 JSON 序列化的数据。注册表拒绝重复名称，
同时通过 API 暴露 Provider 元数据。

调度器在后台独立采集每个 Provider，并将最新结果写入线程安全缓存。
浏览器请求只读取缓存，不会直接执行 `nvidia-smi`、集群调度器命令或
日志解析器。

Provider 的故障和超时相互隔离。某个可选集成不可用时，不会阻止系统指标
或 Jupyter 指标返回。

## API 契约

主要的认证指标接口为：

```text
GET <base_url>/jupyterlab-server-monitor/api/summary
```

响应使用带版本号的 Provider envelope：

```json
{
  "schema_version": 1,
  "generated_at": 1784956800.1,
  "providers": {
    "system": {
      "status": "ok",
      "updated_at": 1784956800.0,
      "duration_ms": 4.2,
      "data": {
        "timestamp": 1784956800.0,
        "cpu": {},
        "memory": {},
        "disk": {},
        "network": {}
      }
    },
    "gpu": {
      "status": "error",
      "updated_at": 1784956800.0,
      "duration_ms": 2001.3,
      "data": {},
      "error": "GPU collector is unavailable"
    }
  }
}
```

`schema_version` 用于标识外层契约版本。各 Provider 的 `data` 保持自己的
数据结构，并应尽量以兼容方式演进。

每个 Provider 项都包含：

- `status`：`pending`、`ok` 或 `error`
- `updated_at`：该 Provider 最近一次采集完成时间
- `duration_ms`：最近一次采集耗时
- `data`：Provider 专用数据
- `error`：可选的简短错误信息，不得包含敏感内容

`generated_at` 表示缓存快照的生成时间，`updated_at` 则属于各个 Provider。

原接口继续作为兼容别名，并返回相同的版本化 envelope：

```text
GET <base_url>/jupyterlab-server-monitor/api/metrics
```

Provider 元数据接口：

```text
GET <base_url>/jupyterlab-server-monitor/api/providers
```

客户端应使用强类型视图渲染已知 Provider，同时容忍未知 Provider、新字段、
陈旧数据以及单个 Provider 的错误。

## 添加 Provider

1. 在 `jupyterlab_server_monitor/providers/` 下新增一个模块。
2. 实现核心 Provider 契约，提供唯一且稳定的名称、合理的独立采集周期以及
   有界的采集超时。
3. 只返回可 JSON 序列化且可直接展示的遥测数据。解析和标准化逻辑应保留在
   对应 Provider 内。
4. 在后端组合入口注册 Provider，不要在 HTTP Handler 或调度器中增加
   Provider 专用分支。
5. 为解析、manifest 元数据、成功采集、超时和错误隔离、缓存行为添加
   聚焦测试。
6. 如果需要专用界面，在 `src/providers/` 下添加 renderer，并复用共享组件。
   未知 Provider 不得导致整个面板失效。

设置、命令名称、查询字段、过滤器和超时应存放在 `defaults.json` 等包配置中，
不要写死在采集流程里。包内数据必须通过 `importlib.resources` 加载，确保
安装后的 wheel 与源码目录行为一致。

## Slurm Provider 指南

Slurm Provider 可以显示队列摘要、资源分配状态、作业资源使用量、分区状态
和预计等待信息。第一版应保持只读。

- 只允许执行明确列入白名单的程序和子命令，例如 `squeue`、`sacct` 和
  `sinfo`。
- 使用 argv 列表并设置 `shell=False`，绝不把用户输入拼接到 shell 命令。
- 优先使用机器可读输出或明确分隔符，并验证每一个解析字段。
- 设置较短的超时和输出大小限制。Slurm 控制器缓慢或不可用时，只允许
  Slurm Provider 降级。
- 默认只返回当前认证用户的数据，除非管理员明确配置了更广的可见范围。
- 修改状态的操作必须放入独立的认证 actions API，并包含明确白名单、
  权限检查、审计日志和用户确认。

## AI 使用量 Provider 指南

Codex CLI、Claude Code 和其他 AI 集成只应显示汇总使用量，例如请求数、
token 总量、费用估算、速率限制状态以及按时间窗口统计的摘要。

采集器不得返回或上传以下内容：

- prompt 或模型回复
- 凭据、API key 和认证 token
- 完整命令历史
- 完整会话内容

只读取必要的本地文件，并对允许的路径和字段设置白名单。不需要展示的标识符
应进行脱敏。错误信息不得包含文件内容、原始命令输出或任何密钥。

本地 AI 使用量格式通常由具体工具定义，并且可能随版本变化。Provider 应检测
不支持的版本、进行防御性解析，并在无法可靠识别时报告自身 `error`，而不是
猜测数据。AI 使用量变化通常慢于 CPU 或网络指标，因此应使用独立且更长的
采集周期。

## 安全

所有接口都使用 Jupyter Server 身份认证，并继承服务器的 base URL。
Provider 使用 Jupyter Server 进程的权限执行，因此 Provider 本身属于服务器
的可信计算基础。

遥测功能默认保持只读。不得暴露环境变量、凭据、任意文件内容、prompt、
Notebook 内容或外部命令的原始输出。

外部进程必须满足以下要求：

- 可执行文件在明确白名单中
- 使用 argv 调用，不经过 shell
- 设置超时
- 限制输出大小

修改状态的 API 必须拥有比只读指标接口更严格的权限控制，并要求用户明确确认。

本扩展适用于可信的 Jupyter 部署。在多人共用的 JupyterHub 上启用新 Provider
前，应审查其源码、配置和权限范围。

## 测试

```bash
python -m pytest
npm run build
```

后端测试覆盖版本化契约、注册表校验、Provider 独立采集、缓存和错误隔离。
前端构建用于验证强类型 Provider 契约和预构建扩展。
