Cli agent display number of jobs

[ajzobro]

Description

Added command line interface to support display of number of jobs per queue that a given agent is monitoring. Depending on the number of other agents monitoring the same queues that a given agent is monitoring, this agent could be responsible for anywhere from 0 to all of the jobs on those queues.

The following will now also show the job count on queues rather than return a list (potentially breaking change if users are looping over the values (queue names) in the current list and would likely end up up looping over job counts in the new structure)

testflinger-cli agent-status <agent_name> --json

before	{"agent": "agent3", "provision_streak_count": 1, "provision_streak_type": "pass", "queues": ["test_queue6", "test_queue3", "test_queue7", "test_queue0", "test_queue8", "test_queue1", "test_queue5"], "restricted_to": {}, "status": "waiting", "updated_at": {"$date": "2026-01-05T18:06:00.631Z"}}
after	{"agent": "agent3", "provision_streak_count": 1, "provision_streak_type": "pass", "queues": {"test_queue0": {"num_jobs": 0}, "test_queue1": {"num_jobs": 1}, "test_queue3": {"num_jobs": 0}, "test_queue5": {"num_jobs": 3}, "test_queue6": {"num_jobs": 0}, "test_queue7": {"num_jobs": 2}, "test_queue8": {"num_jobs": 2}}, "restricted_to": {}, "status": "waiting", "updated_at": {"$date": "2026-01-05T18:06:00.631Z"}}

And added a much more human-readable YAML option to support displaying the same information in a way that is non-breaking and does not introduce yet another format in printed text.

testflinger-cli agent-status <agent_name> --yaml

agent: agent3
provision_streak_count: 1
provision_streak_type: pass
queues:
  test_queue0:
    num_jobs: 0
  test_queue1:
    num_jobs: 1
  test_queue3:
    num_jobs: 0
  test_queue5:
    num_jobs: 3
  test_queue6:
    num_jobs: 0
  test_queue7:
    num_jobs: 2
  test_queue8:
    num_jobs: 2
restricted_to: {}
status: waiting
updated_at:
  $date: '2026-01-05T18:06:00.631Z'

Note: the observation has been made that jq can be used to prettify the testflinger JSON output, e.g.: testflinger agent-status agent2 --json | jq "." --indent 4. However this does not resolve the fact that the changes to the JSON structure are breaking changes.

As a side note, the yq command can also be used to convert to JSON and even prove the same results are achieved by both, e.g.: diff <(testflinger agent-status agent2 --yaml | yq e "." --indent 4 -o json) <(testflinger agent-status agent2 --json | jq "." --indent 4)

Options:

• Resistance to adding another output format
  • Option: Pipe output to jq "." --indent 4
  • Favor --json over --yaml if both provided (current proposed behavior, undocumented)
• Avoid breaking changes:
  • Update JSON structure with additional (new) key and leave existing queues as a list:
    • Another list of same length representing job_count for queue of same index into the list
    • A new queues_with_data dictionary matching the format proposed above

Resolved issues

Relates to CERTF-756. (#853)

Documentation

See docs/
docs/how-to/view-agent-status.rst

Web service API changes

N/A

Tests

Tests added for new YAML output and updated for adjusted JSON output format.

[codecov]

Codecov Report

❌ Patch coverage is 75.47170% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.06%. Comparing base (563acb6) to head (438fa0d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #859      +/-   ##
==========================================
- Coverage   71.38%   71.06%   -0.33%     
==========================================
  Files         108      108              
  Lines        9674     9601      -73     
  Branches      860      856       -4     
==========================================
- Hits         6906     6823      -83     
- Misses       2595     2607      +12     
+ Partials      173      171       -2     

Flag	Coverage Δ		*Carryforward flag
agent	72.56% <ø> (-0.30%)	⬇️	Carriedforward from 38ec676
cli	87.90% <75.47%> (-0.01%)	⬇️
device	54.23% <ø> (-0.98%)	⬇️	Carriedforward from 38ec676
server	87.71% <ø> (-0.01%)	⬇️	Carriedforward from 38ec676

*This pull request uses carry forward flags. Click here to find out more.

Components	Coverage Δ
Agent	72.56% <ø> (-0.30%)	⬇️
CLI	87.90% <75.47%> (-0.01%)	⬇️
Common	∅ <ø> (∅)
Device Connectors	54.23% <ø> (-0.98%)	⬇️
Server	87.71% <ø> (-0.01%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.