新增sreport功能

[haofangTu-bot]

1、功能描述：sreport的命令通用语法结构：sreport <全局选项> <报告实体> <报告类型> <过滤器>

（1）<报告实体> (Report Entity): 这是报告的核心主语，即用户希望分析的对象。sreport主要围绕四个核心实体构建报告 ： cluster: 关注整个集群的宏观状态和资源使用情况；job: 关注作业的聚合特征，如规模分布；user: 关注单个或多个用户的资源消耗行为；reservation: 关注资源预留的使用情况。

（2）<报告类型> (Report Type): 针对选定的实体，用户可以指定具体的报告类型，以获得不同维度的洞察。
对于 cluster 实体，可以选择 Utilization (利用率) 报告。
对于 user 实体，可以选择 TopUsage (顶级用户) 报告。
对于 job 实体，可以选择 SizesByAccount (按账户统计的作业规模) 报告。

（3）<过滤器> (Filters): 这些是附加的条件，用于缩小报告的数据范围，使其更加精确。
最常用的过滤器包括：
Users=<user_list>: 按用户过滤；
Accounts=<account_list>: 按账户过滤；
Partitions=<partition_list>: 按分区过滤（请注意，此过滤器对某些报告类型如 cluster utilization 无效；
Start= 和 End=: 定义报告的时间范围，这是最关键的过滤器之一。

（4）<全局选项> (Global Options): 这些参数作用于整个命令，用于控制最终报告的呈现方式，例如输出格式（是否适合脚本解析）、时间单位（是小时还是分钟）等。

a、输出格式化：

• -p, --parsable: 生成以竖线 (|) 分隔的输出，并且在每行末尾也附加一个竖线。这种格式是为Shell脚本处理量身定制的，可以非常方便地通过 awk、cut 等命令行工具进行解析。
• -P, --parsable2: 与 -p 类似，同样生成以竖线 (|) 分隔的输出，但行尾不附加竖线。这种格式更为“干净”，是直接导入到CSV文件、电子表格或数据库的理想选择。
• -n, --noheader: 禁止输出报告的表头。当用户需要将多个sreport命令的输出结果拼接成一个文件时，此选项可以避免表头重复出现，非常实用。

b、时间单位格式化 (-t )：
此选项用于控制报告中时间相关字段（如 Used 列）的显示单位，默认单位是分钟 (Minutes) 。选择合适的单位能极大提升报告的可读性。

• 常用时间单位: Seconds (秒), Minutes (分钟), Hours (小时) 。
• 百分比格式: Percent (占总量的百分比) 。
• 复合格式: MinPer (分钟/百分比), HourPer (小时/百分比) 。例如，使用-t Hours 生成以“CPU小时”为单位的报告，远比默认的“CPU分钟”更为直观易懂。

c、时间范围过滤 (Start= 和 End=)：

• Start= 和 End= 是sreport中最核心的过滤器，它们共同定义了报告所涵盖的时间周期。
• 默认行为: 如果不指定，Start 默认为前一天的 00:00:00，End 默认为前一天的 23:59:59
  时间格式字符串：
  YYYY-MM-DD
  MM/DD[/YY]
  now
  yesterday
  midnight
  now-N[unit]

d、按资源类型报告 (-T, --tres=)：
将报告的维度从单一的CPU扩展到了Slurm管理的所有可追踪资（Trackable Resources, TRES）。

• 默认行为: 如果不使用此选项，所有报告都默认基于CPU使用量。
• 指定其他资源: 可以生成基于任何TRES的报告，例如：
  • 内存使用: --tres=mem
  • 节点占用: --tres=node
  • 通用资源 (GRES)，如GPU: --tres=gres/gpu
  • 计费权重 (Billing TRES): --tres=billing
• 多资源报告: 可以提供一个以逗号分隔的列表来同时报告多种TRES的使用情况，例如 --tres=cpu,mem,gres/gpu

2、集群级报告

sreport cluster utilization 是评估集群整体利用率最核心、最直接的命令。它展示了在指定时间段内，集群中所有节点的总时间是如何分配的。
sreport cluster AccountUtilizationByUser: 此报告以账户为中心，按层级结构展示资源使用情况。它会列出指定账户，并进一步细分到该账户下的每个用户所消耗的资源。

• sreport cluster UserUtilizationByAccount: 此报告提供一个“扁平化”的视图，将每个“用户-账户”组合作为独立的一行来显示，并按使用量排序。这对于快速找出哪些特定的用户/账户组合是资源消耗的主力非常有用。

如果在sreport cluster utilization命令中添加Partitions=<partition_name>过滤器，会发现该过滤器被完全忽略，输出结果依然是整个集群的利用率 。统计在指定分区上运行的作业所消耗的资源总量需要使用sacct来完成。

3、以用户为中心分析

a、寻找“重度用户”：user TopUsage，sreport user TopUsage是快速定位资源消耗最多用户的首选报告；

• 默认情况下，该命令会列出按CPUTime（CPU时间）排序的前10名用户；
• 可以使用TopCount=选项来指定显示的用户的数量，例如TopCount=5将显示前5名用户；
• 默认情况下，如果一个用户关联了多个账户，报告中会为每个“用户-账户”组合显示单独的一行。可以使用group选项将一个用户的所有账户使用量合并在一起显示；

b、sreport通过-T, --tres选项，让管理员能够从不同资源的维度来回答这个问题，从而揭示出“顶级用户”的定义完全取决于所衡量的资源类型。这对于实现公平的资源管理和科学的容量规划具有深远意义。

• 按不同资源排序
  • 按CPU（默认）: sreport user TopUsage...
  • 按内存: sreport user TopUsage --tres=mem...；报告的“Used”列将以MB-分钟（或通过-t指定的其他单位）为单位显示内存使用量。
  • 按GPU: sreport user TopUsage --tres=gres/gpu...；报告将显示GPU卡时（GPU-Hours）的使用情况。
  • 按计费单位（Billing TRES）: sreport user TopUsage --tres=billing...，这是在实施资源计费或成本回收时最重要的指标。billing TRES反映的是资源的配置成本，而不仅仅是物理数量。例如，一个GPU节点的计费权重可能远高于一个CPU节点。因此，按billing排序能最真实地反映出谁消耗了集群中“价值”最高的资源。

4、基于作业的报告

a、分析作业规模资源消耗分布：

• job SizesByAccount，将作业根据其使用的CPU核心数（或其他TRES）进行“分箱”（binning），然后报告每个箱子内所有作业消耗的资源总量。分箱的边界由Grouping=选项定义。例如，Grouping=1,2,4,8,16会创建以下几个箱子：1核的作业、2-3核的作业、4-7核的作业、8-15核的作业，以及16核及以上的作业。通过观察资源消耗在不同规模箱子间的分布，可以快速判断出集群的主要工作负载是串行任务、小规模并行任务还是大规模并行任务。
• 输出将显示一个表格，列为不同的CPU核心数范围，值为落在该范围内的作业所消耗的总CPU小时数。

b、从“资源消耗量”到“作业数量”
job SizesBy...系列报告还有一个非常有用的选项：PrintJobCount。使用该选项后，报告将不再显示每个箱子消耗的资源总量，而是显示落在该箱子内的作业数量。

5、基于reservation 的报告

sreport reservation Utilization 命令就是用来审计这些被“锁定”的资源的。

输出字段：
Name
Nodes
Start / End
TotalTime
Allocated
Idle
Flags

参考文档：https://slurm.schedmd.com/sreport.html
调研文档：https://e26ruh1viz.feishu.cn/wiki/HH6Kwhwepi1EtHkSIjfcCRXCnMe