commands: add new `clear-usage` command to reset a bank's job usage by cmoussa1 · Pull Request #804 · flux-framework/flux-accounting

cmoussa1 · 2026-01-13T17:23:04Z

Problem

There is no way to clear and reset the usage for a given bank in bank_table without fully deleting the bank and re-adding it. New grant cycles generally have a mix of new and returning / continuing projects. For returning / continuing projects, the same bank name tends to be kept while also zeroing out and resetting the usage for the bank at the start of the new grant.

This PR adds a new clear-usage command to the flux-accounting command suite. clear-usage takes one positional argument: a list of banks to have their usage reset. When a bank's usage is reset, their job_usage value is reset to 0. Any users under this bank will also have their job_usage value reset to 0.

Example usage:

flux account clear-usage my_bank

When the bank's usage is reset, the job usage for the rest of the hierarchy is updated to account for the change in overall usage.

Even though a bank's usage is reset to 0, the old jobs submitted under this bank are still kept in the jobs table. These jobs are ignored in subsequent usage updates by filtering the table against an ignore_older_than timestamp, a new column added to the bank_table which represents a timestamp for which all jobs that have completed before said timestamp are ignored:

SELECT ...,b.ignore_older_than
FROM jobs ...
LEFT JOIN bank_table b
...
AND r.t_inactive > b.ignore_older_than

If the clear-usage command is run without any additional arguments, the ignore_older_than timestamp is set to the time in which the command is run, i.e. that bank will begin to ignore any jobs older than when clear-usage was run. An optional --ignore-older-than optional argument has also been added to clear-usage (as well as add-bank and view-bank) to allow further customization for banks in relation to which jobs are or are not ignored. The format can be any timestamp accepted by Flux's parse_datetime() function.

Some basic unit tests and sharness tests are added which test clearing usage for a bank and ensuring that all of its users' usage also gets cleared along with any and all parent banks.

Fixes #801

cmoussa1 · 2026-01-13T17:39:31Z

@ryanday36 if you want to take a high-level look at this and let me know if this looks like what you had in mind in #801, let me know!

Problem: There is a need for flux-accounting to be able to reset the usage for a given bank at any given time. To do this, the database needs to a) know which banks are being reset, and b) which jobs that exist in the "jobs" table to ignore. Add a new column to bank_table called "ignore_older_than", which will store a timestamp (in the format of seconds-since-epoch) that will signal to all scripts updating job usage and fair-share values to ignore jobs that have completed before this time. Update DB_SCHEMA_VERSION as a result of adding a new column to bank_table. Update tests that look at columns output by the view-bank and list-banks commands to account for the addition of the ignore_older_than column.

Problem: The flux-accounting database from before the addition of the new "ignore_older_than" column to the bank_table is not in the testsuite, but it should be a part of the update-db tests since the schema has changed. Add a flux-accounting DB with schema version 31 to the testsuite.

Problem: The add-bank and edit-bank commands don't accept an --ignore-older-than option to set and modify a timestamp for a bank to ignore jobs older than said timestamp. Add a new optional argument to the add-bank and edit-bank commands to do so.

Problem: If a bank has an ignore_older_than timestamp configured, then the query that fetches new jobs needs to account for the fact that jobs older than that timestamp need to be filtered out. Add a LEFT JOIN to the query that fetches new jobs to filter any jobs that should be ignored by a bank with an ignore_older_than timestamp configured.

jameshcorbett

Looks great! Just a couple of small things

jameshcorbett · 2026-02-10T22:07:56Z

t/python/t1008_banks_output.py

        """
        )
        test = b.list_banks(conn)
+        print(test)


Do you mean for this to remain in the PR?

No I did not 🤦 thanks for catching this. Will remove

jameshcorbett · 2026-02-10T22:45:32Z

src/bindings/python/fluxacct/accounting/job_usage_calculation.py

+        ignore_older_than: The timestamp in which all older jobs will not be considered
+            towards job usage.
+    """
+    if len(banks) > 0:


This could be if banks:

jameshcorbett · 2026-02-10T22:54:27Z

src/bindings/python/fluxacct/accounting/job_usage_calculation.py

+        # one or more banks has been passed in to have their usage wiped
+        for bank in banks:
+            # first, get the current usage for this bank and reset it
+            cur.execute("SELECT job_usage FROM bank_table WHERE bank=?", (bank,))


Where are the records returned by this SELECT call used?

Ah, good catch! That query was left over by accident for some troubleshooting and I never removed it. I will remove this query

Problem: There is no way to clear and reset the usage for a given bank in bank_table. New grant cycles generally have a mix of new and returning / continuing projects. For returning / continuing projects, the same bank name tends to be kept while *also* zeroing out and resetting the usage for the bank at the start of the new grant. Add a new clear-usage command to the flux-accounting command suite. clear-usage takes one positional argument: a list of banks to have their usage reset. When a bank's usage is reset, their job_usage value is reset to 0. Any users under this bank will also have their job_usage value reset to 0. When the bank's usage is reset, the job usage for the rest of the hierarchy is updated to account for the change in overall usage. An option to then set ignore_older_than is also provided to set a new date for which flux-accounting will no longer consider jobs towards usage that are older than that date. If no date is provided, the bank's ignore_older_than attribute is automatically set to the time in which the clear-usage command is run.

Problem: There are no tests for the clear_usage() function and its helper functions. Add some tests.

cmoussa1 · 2026-02-11T20:09:00Z

Thanks for approving this @jameshcorbett! Going to set MWP here

mergify · 2026-02-11T20:10:03Z

codecov · 2026-02-11T20:10:11Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.93%. Comparing base (f48e95f) to head (7525ede).
⚠️ Report is 7 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #804   +/-   ##
=======================================
  Coverage   82.93%   82.93%           
=======================================
  Files          27       27           
  Lines        2479     2479           
=======================================
  Hits         2056     2056           
  Misses        423      423

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

cmoussa1 added new feature new feature commands related to the flux-accounting commands/bindings labels Jan 13, 2026

cmoussa1 force-pushed the clear.banks.usage branch from 382e04d to a1dabb2 Compare January 21, 2026 18:46

cmoussa1 force-pushed the clear.banks.usage branch 2 times, most recently from 16393c1 to 516746f Compare January 29, 2026 15:52

cmoussa1 force-pushed the clear.banks.usage branch from 516746f to 0b04de9 Compare February 5, 2026 19:44

cmoussa1 added 4 commits February 10, 2026 07:37

cmd: add --ignore-older-than option

0db5af5

Problem: The add-bank and edit-bank commands don't accept an --ignore-older-than option to set and modify a timestamp for a bank to ignore jobs older than said timestamp. Add a new optional argument to the add-bank and edit-bank commands to do so.

cmoussa1 force-pushed the clear.banks.usage branch from 0b04de9 to 14fc807 Compare February 10, 2026 15:46

cmoussa1 requested a review from jameshcorbett February 10, 2026 15:51

jameshcorbett approved these changes Feb 10, 2026

View reviewed changes

cmoussa1 added 2 commits February 10, 2026 17:14

t: add tests for clear_usage()

7525ede

Problem: There are no tests for the clear_usage() function and its helper functions. Add some tests.

cmoussa1 force-pushed the clear.banks.usage branch from 14fc807 to 7525ede Compare February 11, 2026 01:14

cmoussa1 added the merge-when-passing label Feb 11, 2026

mergify bot added the queued label Feb 11, 2026

mergify bot merged commit 74da2be into flux-framework:master Feb 11, 2026
15 of 16 checks passed

mergify bot removed the queued label Feb 11, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

commands: add new `clear-usage` command to reset a bank's job usage#804

commands: add new `clear-usage` command to reset a bank's job usage#804
mergify[bot] merged 6 commits intoflux-framework:masterfrom
cmoussa1:clear.banks.usage

cmoussa1 commented Jan 13, 2026

Uh oh!

cmoussa1 commented Jan 13, 2026

Uh oh!

jameshcorbett left a comment

Uh oh!

jameshcorbett Feb 10, 2026

Uh oh!

cmoussa1 Feb 11, 2026

Uh oh!

jameshcorbett Feb 10, 2026

Uh oh!

jameshcorbett Feb 10, 2026

Uh oh!

cmoussa1 Feb 11, 2026

Uh oh!

cmoussa1 commented Feb 11, 2026

Uh oh!

Uh oh!

mergify bot commented Feb 11, 2026

Uh oh!

codecov bot commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

cmoussa1 commented Jan 13, 2026

Problem

Uh oh!

cmoussa1 commented Jan 13, 2026

Uh oh!

jameshcorbett left a comment

Choose a reason for hiding this comment

Uh oh!

jameshcorbett Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

cmoussa1 Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

jameshcorbett Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

jameshcorbett Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

cmoussa1 Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

cmoussa1 commented Feb 11, 2026

Uh oh!

Uh oh!

mergify bot commented Feb 11, 2026

Merge Queue Status

Uh oh!

codecov bot commented Feb 11, 2026

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants