shell: support more mustache tags #6525

grondo · 2024-12-19T02:23:25Z

This PR adds new mustache tags specific to tasks and nodes (shell rank, really), formatted as {{task.*}} and {{node.*}}, with a couple special cases. The node tags use the "rank info" object in the shell to render results, which has been updated with additional items for mustache tag use.

Since there are many more supported tags to document, a new MUSTACHE TEMPLATES section is added to the job submission ccommands' manual pages, pasted here since it contains the set of supported tags:

MUSTACHE TEMPLATES

Submission commands support a simplified version of mustache templates in select options (e.g., --output, --error, --dump), and job commands/arguments. These templates are replaced by job details once available. A mustache template is a tag in double braces, like {{tag}}.

The following is a list of currently supported tags:

Note
The template system in the job shell allows plugins to extend the set of supported mustache tags. Check with your installation of Flux to determine if extra tags are available locally.

Job mustache tags:

{{id}} or {{jobid}}
Expands to the current jobid in F58 encoding. If needed, an alternate encoding may be selected by using a subkey with the name of the desired encoding, e.g., {{id.dec}}. Supported encodings include f58 (the default), dec, hex, dothex, and words.
{{name}}
Expands to the current job name. If a name is not set for the job, then the basename of the command will be used.
{{nnodes}}
Expands to the number of nodes allocated to the job.
{{size}} or {{ntasks}}
Expands to the job size, or total number of tasks in the job.

Node-specific tags

Node-specific tags are prefixed with node., and support any of the keys present in the object returned by flux_shell_get_rank_info. These include:

{{node.id}}
Expands to the current node index within the job (0 - nnodes-1).
{{node.name}}
Expands to the hostname of the current node.
{{node.broker_rank}}
Expands to the broker rank of the enclosing instance on this node.
{{node.cores}}
Expands to the core id list assigned to the current node in idset form. For example, 0-3 or 1.
{{node.gpus}}
Expands to the GPU id list assigned to the job on this node in idset form, e.g., 0-1 or 4.
{{node.ncores}}
Expands to the number of cores allocated to the job on this node.

Task-specific tags

Task-specific tags are prefixed with task., with the special case of {{taskid}}, which is an alias for {{task.id}}.

Note
The --output and --error options do not support task-specific tags at this time.

{{task.id}}, {{task.rank}}, or {{taskid}}
Expands to the global rank for the current task
{{task.index}} or {{task.localid}}
Expands to the local rank for the current task

Other tags:

{{tmpdir}}
Expands to the path of the job temporary directory on the local system.

If an unknown mustache tag is encountered, an error message may be displayed and the unknown template will appear in the result.

garlick

LGTM! Just a couple minor nits

garlick · 2024-12-20T19:41:54Z

src/shell/shell.c

@@ -577,6 +577,8 @@ static json_t *flux_shell_get_rank_info_object (flux_shell_t *shell, int rank)
    char *taskids = NULL;


commit message: s/usefule/useful/

garlick · 2024-12-20T19:43:22Z

doc/man1/flux-shell.rst

@@ -610,13 +610,17 @@ supported. Job shell specific functions and tables are described below:
  then the current rank is used.  Returns a table of rank-specific
  information including:

+  **id**
+    The current shell rank (matches ``shell_rank`` input parameter


need a close paren

Problem: The `void *` arg for the mustache renderer is passed to mustache_renderer_create() and can't be changed, limiting flexibility. Move `arg` to mustache_render() from mustache_renderer_create(). Update callers.

Problem: The shell doesn't support expansion of task-specific tags in mustache templates. Add support for the following task-specific tags: - {{taskid}}, {{task.id}}, {{task.rank}} - global task rank - {{task.index}}, {{task.localid}} - local task rank

Problem: Some useful data is not included in the result object returned from flux_shell_get_rank_info(3). Add the following new items to the rank_info object: - id (int) The shell rank the object describes - name (str) hostname - resources.ncores (int) Count of cores

Problem: The new keys available in the shell "rank_info" object are not documented. Update the documentation in flux-shell(1) and flux_shell_get_rank_info(3).

Problem: The shell doesn't support expansion of any node-specific tags in mustache templates. Add support for expansion of node-specific data via a set of node.<key> mustache tags. The <key> is pulled directly from the shell "rank info" object, so any item present in that object can be expanded, including {{node.id}} for the nodeid (job local node rank), {{node.name}} for the hostname, {{node.taskids}} for the list of tasks assigned to the node, etc.

Problem: It would be useful to have mustache tags that expand to the job size/ntasks and total number of nodes in the current job, but this is currently not supported. Support these tags in the job shell mustache renderer.

Problem: Callers to flux_shell_mustache_render() may want to know if a tag or tags is not supported, but not necessarily have an error logged to the job. Return an error with errno=ENOENT instead of logging an error when a tag is not supported and it is practical to do so.

Problem: The current set of supported mustache tags is not documented in the submission cli manual pages. Add a new MUSTACHE TEMPLATES section in doc/man1/common/job-mustache-templates.rst and include it in relevant manuals, replacing the short bit of text in common/job-standard-io.rst.

Problem: There are no specific tests for testing shell mustache template expansion. Add t2620-job-shell-mustache.t for this purpose.

Problem: An R object used for alloc-bypass in the testsuite doesn't contain the nodelist key, which trips up the job shell. Ensure the Rv1 object is compliant with RFC 20, which requires that nodelist is present.

grondo · 2024-12-20T22:17:23Z

Thanks! Fixed those and I'll set MWP.

grondo · 2024-12-20T22:22:20Z

Thanks! Fixed those errors and will set MWP.

grondo · 2024-12-20T23:14:55Z

Hm, two builders failed in t0005-exec.t:

expecting success: 
  	cat 5Mfile | flux exec -r 0-3 --setopt=stdin_BUFSIZE=4096 ./stdin2file &&
  	test_must_fail ls cpy.0 &&
  	cmp 5Mfile cpy.1 &&
  	cmp 5Mfile cpy.2 &&
  	cmp 5Mfile cpy.3 &&
  	rm cpy.*
  
  flux-exec: flux_subprocess_write: Broken pipe
  not ok 45 - stdin flow control works (all ranks, one rank will exit early)

I assume this is unrelated to this PR so I'll restart those.

codecov · 2024-12-20T23:38:16Z

Codecov Report

Attention: Patch coverage is 88.33333% with 7 lines in your changes missing coverage. Please review.

Project coverage is 83.64%. Comparing base (9278fa8) to head (d8777dd).
Report is 11 commits behind head on master.

Files with missing lines	Patch %	Lines
src/shell/shell.c	87.71%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6525      +/-   ##
==========================================
+ Coverage   83.62%   83.64%   +0.01%     
==========================================
  Files         522      522              
  Lines       87809    87860      +51     
==========================================
+ Hits        73433    73488      +55     
+ Misses      14376    14372       -4

Files with missing lines	Coverage Δ
src/shell/mustache.c	`78.33% <100.00%> (-0.36%)`	⬇️
src/shell/shell.c	`79.23% <87.71%> (+0.74%)`	⬆️

... and 4 files with indirect coverage changes

grondo changed the title ~~shell: expand available mustache tags~~ shell: support more mustache tags Dec 19, 2024

grondo force-pushed the shell-templates branch from ee8f2e2 to fdf8226 Compare December 19, 2024 14:44

garlick approved these changes Dec 20, 2024

View reviewed changes

grondo added 10 commits December 20, 2024 22:14

shell: pass mustache_renderer arg to mustache_render()

1236354

Problem: The `void *` arg for the mustache renderer is passed to mustache_renderer_create() and can't be changed, limiting flexibility. Move `arg` to mustache_render() from mustache_renderer_create(). Update callers.

doc: update documentation for shell rank_info object

b42a40c

Problem: The new keys available in the shell "rank_info" object are not documented. Update the documentation in flux-shell(1) and flux_shell_get_rank_info(3).

shell: add {{nnodes}} and {{size|ntasks}} mustache tags

5af77df

Problem: It would be useful to have mustache tags that expand to the job size/ntasks and total number of nodes in the current job, but this is currently not supported. Support these tags in the job shell mustache renderer.

testsuite: add t2620-job-shell-mustache.t

03d810d

Problem: There are no specific tests for testing shell mustache template expansion. Add t2620-job-shell-mustache.t for this purpose.

testsuite: ensure Rv1 test object is RFC 20 compliant

d8777dd

Problem: An R object used for alloc-bypass in the testsuite doesn't contain the nodelist key, which trips up the job shell. Ensure the Rv1 object is compliant with RFC 20, which requires that nodelist is present.

grondo force-pushed the shell-templates branch from fdf8226 to d8777dd Compare December 20, 2024 22:16

grondo added the merge-when-passing label Dec 20, 2024

mergify bot merged commit bb3e8c7 into flux-framework:master Dec 20, 2024
35 checks passed

grondo deleted the shell-templates branch December 20, 2024 23:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

shell: support more mustache tags #6525

shell: support more mustache tags #6525

grondo commented Dec 19, 2024

garlick left a comment

garlick Dec 20, 2024

garlick Dec 20, 2024

grondo commented Dec 20, 2024

grondo commented Dec 20, 2024

grondo commented Dec 20, 2024

codecov bot commented Dec 20, 2024

		@@ -577,6 +577,8 @@ static json_t flux_shell_get_rank_info_object (flux_shell_t shell, int rank)
		char *taskids = NULL;

shell: support more mustache tags #6525

shell: support more mustache tags #6525

Conversation

grondo commented Dec 19, 2024

MUSTACHE TEMPLATES

Job mustache tags:

Node-specific tags

Task-specific tags

Other tags:

garlick left a comment

Choose a reason for hiding this comment

garlick Dec 20, 2024

Choose a reason for hiding this comment

garlick Dec 20, 2024

Choose a reason for hiding this comment

grondo commented Dec 20, 2024

grondo commented Dec 20, 2024

grondo commented Dec 20, 2024

codecov bot commented Dec 20, 2024

Codecov Report