Consider adding the handlers in the graph

[haidaraM]

Discussed in #212

^{Originally posted by sphakka December 3, 2024}
Hi there,
I'm possibly missing something, but it looks like notify/handlers are ignored.

MWE: test.yml

- name: Test grapher
  hosts: foobar
  gather_facts: False

  tasks:
    - name: foo
      assert: { that: true }
      changed_when: true

    - name: bar
      assert: { that: true }
      changed_when: true
      notify: quux

  handlers:
    - name: quux
      assert: { that: true }

Notice the notify from task bar to handler quux.

Then (expect handler to be triggered):

$ ansible-playbook --check test.yml
PLAY [Test grapher] ************************************************************

TASK [foo] *********************************************************************
changed: [foobar] => {
    "changed": true,
    "msg": "All assertions passed"
}

TASK [bar] *********************************************************************
changed: [foobar] => {
    "changed": true,
    "msg": "All assertions passed"
}

RUNNING HANDLER [quux] *********************************************************
ok: [foobar] => {
    "changed": false,
    "msg": "All assertions passed"
}

PLAY RECAP *********************************************************************
foobar                     : ok=3    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

I'd expect grapher to show a handler node linked to its notifying task node, but

$ ansible-playbook-grapher --renderer mermaid-flowchart test.yml

gives:

---
title: Ansible Playbook Grapher
---
%%{ init: { "flowchart": { "curve": "bumpX" } } }%%
flowchart LR
	%% Start of the playbook 'playbooks/test.yml'
	playbook_56f3dcb5("playbooks/test.yml")
		%% Start of the play 'Play: Test grapher (1)'
		play_b92d44b7["Play: Test grapher (1)"]
		style play_b92d44b7 fill:#1383b9,color:#ffffff
		playbook_56f3dcb5 --> |"1"| play_b92d44b7
		linkStyle 0 stroke:#1383b9,color:#1383b9
			task_44193561["[task]  foo"]
			style task_44193561 stroke:#1383b9,fill:#ffffff
			play_b92d44b7 --> |"1"| task_44193561
			linkStyle 1 stroke:#1383b9,color:#1383b9
			task_4efd8c98["[task]  bar"]
			style task_4efd8c98 stroke:#1383b9,fill:#ffffff
			play_b92d44b7 --> |"2"| task_4efd8c98
			linkStyle 2 stroke:#1383b9,color:#1383b9
		%% End of the play 'Play: Test grapher (1)'
	%% End of the playbook 'playbooks/test.yml'

Loading

No handler shown! Is it normal?

Cheers,
^s

[haidaraM]

@sphakka I will include the handlers as the last tasks of each play to make things easier and use a special shape/color (or something like that).

[haidaraM]

Can you give a try to the version on the main branch pip install "ansible-playbook-grapher @ git+https://github.com/haidaraM/ansible-playbook-grapher@main". There is a new flag to show the handlers: --show-handlers.

[sphakka]

Nice job, thanks!

Now, next iteration ;-) Ideally, an arc should link the notifying task node "bar" to the handler node "quux". And, don't forget that also a handler can notify another handler.

Example. The following playbook...

- name: Test grapher
  hosts: localhost
  gather_facts: False
  become: false

  tasks:
    - name: foo
      assert: { that: true }
      changed_when: true

    - name: bar
      assert: { that: true }
      changed_when: true
      notify: baz

  handlers:
    - name: baz
      assert: { that: true }
      notify: quux
      changed_when: true

    - name: quux
      assert: { that: true }

...could be rendered as (built in mermaidchart.com)

---
config:
  flowchart:
    curve: bumpX
title: Ansible Playbook Grapher
---
flowchart LR
    playbook_ee533f9f("playbooks/test.yml") -- 1 --> play_68c96938["Play: Test grapher (1)"]
    play_68c96938 -- 1 --> task_7d159d31["[task] foo"]
    play_68c96938 -- 2 --> task_8a415963["[task] bar"]
    play_68c96938 -. 3 .-> handler_5c2b84f9{{"[handler] baz"}}
    play_68c96938 -. 4 .-> handler_1e09d4a9{{"[handler] quux"}}
    task_8a415963 --> handler_5c2b84f9
    handler_5c2b84f9 --> handler_1e09d4a9
    style play_68c96938 stroke:#19b374,fill:#19b374,color:#ffffff
    style task_7d159d31 stroke:#19b374,fill:#ffffff
    style task_8a415963 stroke:#19b374,fill:#ffffff
    style handler_5c2b84f9 stroke:#19b374,fill:#ffffff,stroke-dasharray: 2
    style handler_1e09d4a9 stroke:#19b374,fill:#ffffff,stroke-dasharray: 2
    linkStyle 0 stroke:#19b374,color:#19b374,fill:none
    linkStyle 1 stroke:#19b374,color:#19b374,fill:none
    linkStyle 2 stroke:#19b374,color:#19b374,fill:none
    linkStyle 3 stroke:#19b374,color:#19b374,fill:none
    linkStyle 4 stroke:#19b374,color:#19b374,fill:none
    linkStyle 5 stroke:#D50000,fill:none
    linkStyle 6 stroke:#D50000

Loading

If you can handle that, you'll get kudos from all my students ^^

[haidaraM]

Welcome :-)

Yeah! I wanted to add this in the initial version but I didn't do it due to the additional complexity. It's already partially implemented in the code base.

My plan is to only show handlers that are referenced in the tasks. Happy to have your thoughts :-)

If you can handle that, you'll get kudos from all my students ^^

Haha! Now I'm interested to know your use cases of the project 👀

[sphakka]

Haha! Now I'm interested to know your use cases of the project 👀

I teach a bachelor course on Cloud and IT: provisioning and deployment workflows based on Terraform and Ansible are integral parts of it. Students often struggle understanding the logic of Ansible playbooks (YAML can be a nightmare when it comes to follow the notify-handler chain), thus a visual tool would help them (and me too!) quite a lot.

BTW, I stumbled on this: https://github.com/ansible/ansible-content-capture
...wondering if some AST information can help your work.

[haidaraM]

Haha! Now I'm interested to know your use cases of the project 👀

I teach a bachelor course on Cloud and IT: provisioning and deployment workflows based on Terraform and Ansible are integral parts of it. Students often struggle understanding the logic of Ansible playbooks (YAML can be a nightmare when it comes to follow the notify-handler chain), thus a visual tool would help them (and me too!) quite a lot.

Yes, opening a ton of YAML is the main reasons I built this tool.

BTW, I stumbled on this: https://github.com/ansible/ansible-content-capture

...wondering if some AST information can help your work.

Interesting. I didn't know this project. It can make my life a lot easier if Ansible provides itself all the ASTs and objects. Will definitely take a look.