More examples of how to customize output in commands

[wihobbs]

This is sort of a meta-issue: a user mentioned to me that it would be nice if they had more examples of how to customize output from Flux commands.

An example of this is the default in flux-jobs(1):

          {id.f58:>12} ?:{queue:<8.8} {username:<8.8} {name:<10.10+} \
          {status_abbrev:>2.2} {ntasks:>6} {nnodes:>6h} \
          {contextual_time!F:>8h} {contextual_info}

I wonder if it would be helpful (even though it is the default) to include some sample output with this, and maybe another example. These are well documented and familiar syntax for Python users but maybe there's an opportunity to do better.

Maybe this belongs somewhere other than the manpages, too.

The user specifically mentioned wanting the ability to have a one-liner that takes a jobid and returns its current state (running, queued, etc). The easiest way I thought to do this was flux jobs --format="{status}" -n JOBID.

[grondo]

The easiest way I thought to do this was flux jobs --format="{status}" -n JOBID

Correct. But a bit less typing to just do flux jobs -no {status} JOBID

[grondo]

Another good one liner is to use flux jobs to just print jobids, e.g. to get ids of running jobs:

$ flux jobs -Ano {id} -f running

You can get them in basemoji:

$ flux jobs -c 5 -Ano {id.emoji} -f running 
😚📕🐱🚉🐌🔌🔞
😚📕🐱🍸👳🔜🌼
😚📕🐱🍑🗾🌺🏃
😚📕🐱🐲👰🏬🕓
😚📕🐱👯🙆👸💞

[vsoch]

New output type - job stories!

• 😚📕🐱🚉🐌🔌🔞 Once upon a time, there was a whistling book cat, and he took a train ride. The train hit a snail, and the snail was electrocuted, and the result was rated R.
• 😚📕🐱🍸👳🔜🌼 Once upon a time, there was a whistling book cat, and he had a margarita made by an excellent chef. He then soon blossomed into a social butterfly.
• 😚📕🐱🍑🗾🌺🏃Once upon a time, there was a whistling book cat, and he had a pain in his 🍑 and couldn't run. He took a trip to Japan, discovered a new species of flower, and made a new ointment that cured him!
• 😚📕🐱🐲👰🏬🕓Once upon a time, there was a whistling book cat that inside was a dragon. He didn't think anyone could love a dragon, but found and married someone that appreciated him just as he was. They moved to the city, and had a good time.
• 😚📕🐱👯🙆👸💞 Once upon a time, there was a whistling book cat that was a dancer in a conga line. He twirled so many times he was crowned the twirly king, and was beloved across the land!

[wihobbs]

With your comment @grondo and your recommendation on my flux-sched issue yesterday I wonder if better than "examples of how to customize output," a sheet of "flux one-liners" would be helpful. We could expand the current flux cheat sheet or add a new one with things like:

• how to get the jobid of your allocation
• how to get the status of JOBID
• how to get the list of all your running jobs
• ...

Edit: I often want to connect to my most recent running job, (which is usually flux job last but maybe I submitted a bad job last) so I use flux proxy $(flux jobs -no {id.f58}). I also often add -u flux to the flux jobs call to connect to a multi-user subinstance.

[cmoussa1]

IMHO a new sheet (perhaps on the docs site) with the most frequently and most useful options could be nice for an "ever-expanding" list of examples. You could create one batch of 10 jobs (5 running, 3 scheduled, 2 completed, etc.) and use a varying list of flux jobs commands to list different lists of jobs based on the formats you discussed above? And we could start with the most basic examples and build on this whenever we think of another convenient example to have?

[wihobbs]

And we could start with the most basic examples and build on this whenever we think of another convenient example to have?

Yeah! I think even if it isn't super frequently or most useful to our bulk user base, we should have somewhere to put it (maybe a "flux cheat sheet for hackers and super nerds" 😆). We have a growing base of power users and developers at this point (FWIW the initial request for this issue came from @behlendorf). I like your idea @cmoussa1 of including sample output with the examples, I think people often start backwards from what do I want to see? when looking at documentation. Or at least I do.

[chu11]

As an aside, I did write this tutorial a long time ago.

https://flux-framework.readthedocs.io/en/latest/tutorials/commands/flux-jobs.html

some of the one liners I think are within it. Could update that as well?

[grondo]

Edit: I often want to connect to my most recent running job, (which is usually flux job last but maybe I submitted a bad job last) so I use flux proxy $(flux jobs -no {id.f58}). I also often add -u flux to the flux jobs call to connect to a multi-user subinstance.

A couple points:

• the default for {id} is f58
• you could get into trouble here because flux jobs will return all pending and running jobs by default. You probably just want to return one jobid -c 1, and you don't want pending jobs so add -f running: flux jobs -f running -c1 -no {id}

Edit: also I'll just mention here that bash tab completion will work with flux proxy, so if you just have 1 running job, flux proxy <tab> should complete the jobid.b