Job Budgeting CLI Client Tools

This section covers the command-line utilities get_energy and get_energy_admin used to query job energy consumption and (for admins) monitoring data for partitions or nodes.

These tools are typically installed as binaries available in your $PATH (e.g., on cluster login nodes). You do not need access to this repository to use them.

Important behavior

1. -c/--cluster-name is required in both tools and must match a valid cluster name for your deployment.
2. You must provide at least one filter, otherwise the tool prints help and exits.
3. Ctrl+C cancels an in-flight request on the server.

Standard User Guide: get_energy

Use this tool to query energy consumption for your finished jobs, or for finished jobs in projects where you share membership with another user. Running jobs are not supported.

Basic usage

get_energy -c <cluster_name> --all

Filters and access rules

• --all returns all your jobs in the specified time window.
• -j/--job-id filters by a specific SLURM job ID.
• -u/--username is allowed only if you and the requested user share at least one account.
• -a/--account is allowed only if you are a member of that account.
• -s1/--submit-time-start, -s2/--submit-time-end, -s3/--submit-time-exact filter by submit time.
  • Times are UNIX timestamps.
  • If you do not pass -s1, the tool sets a default start time to “now minus ~182 days”.

If you do not pass -a/--account, the tool automatically queries all accounts returned by sacctmgr for your user and submits them as the project filter to the API.

Output options

• -f/--format selects sum (default) or list.
  • sum aggregates totals across all matching jobs.
  • list returns per-job rows and includes job-level errors.
• -o/--output selects table (default), json, or csv.
  • csv writes a file. Use --output-path to control the path or directory.
• -x/--calculate-if-missing retries missing energy calculations (may take longer).

Examples

# All your jobs on a cluster in the last ~182 days (default window)
get_energy -c <cluster_name> --all

# Single job, sum output in JSON
get_energy -c <cluster_name> -j 123456 -o json

# Jobs in a specific account (must be your account)
get_energy -c <cluster_name> -a my_project --all

# Jobs submitted in a specific range (timestamps)
get_energy -c <cluster_name> --all -s1 1735689600 -s2 1738291200

# CSV export to a specific file
get_energy -c <cluster_name> --all -o csv --output-path energy_cluster.csv

Admin Guide: get_energy_admin

This tool supports two modes:

• jobs (default): query job energy consumption for any account or user.
• monitoring: query energy consumption for partitions or specific nodes.

Basic usage

get_energy_admin -c <cluster_name> -m jobs -j 123456

Jobs mode

Filters are similar to get_energy but without user/account restrictions.

• -j/--job-id, -u/--username, -a/--account
• -s1/--submit-time-start, -s2/--submit-time-end, -s3/--submit-time-exact
• -f/--format (sum or list)
• -o/--output (json default, or table)
• -x/--calculate-if-missing

Example:

get_energy_admin -c <cluster_name> -m jobs -u alice -s1 1735689600 -s2 1738291200 -f list -o table

Monitoring mode

Monitoring queries require either a partition name or a node list.

• -p/--partition_name supports x86_cnx, x86_gnx, arm_cna.
• -n/--node_list is a comma-separated list, e.g. cnx481,cnx482,cnx483.
• -s/--start_time and -e/--end_time define the time window and must be provided together if used.

Examples:

# Partition-wide monitoring (latest available window on server)
get_energy_admin -c <cluster_name> -m monitoring -p x86_cnx

# Specific nodes for a time window
get_energy_admin -c <cluster_name> -m monitoring -n cnx481,cnx482 -s 1735689600 -e 1738291200