jupyterlab-server-monitor 0.2.0

An extensible JupyterLab server telemetry sidebar.

JupyterLab Server Monitor

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

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

安装

python -m pip install jupyterlab-server-monitor

前端开发环境：

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

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

jupyter server extension list
jupyter labextension list

架构

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 契约

主要的认证指标接口为：

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

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

{
  "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：

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

Provider 元数据接口：

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 前，应审查其源码、配置和权限范围。

测试

python -m pytest
npm run build

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