charts ansible custom module

Description : ℹ️

charts is a custom module for ansible that generate charts in image format on the ansible control node.

Purpose : 👀

The purpose of this project is to use ansible's control node to generate charts in image format. To do this, some of the functions of the Python Plotly library are used.
This module is very basic and uses only a few functions in comparison with the vast number of possibilities offered by the Plotly library.

• Official link Plotly Python
• Official link Plotly Python GitHub

It is currently possible to generate charts of this type:

• line
• bar
• pie
• donut

In images of these formats:

• png
• jpeg
• webp
• svg
• pdf
• eps

Repo files: 📂

├── /library                
│   └── write_charts.py     ##<-- python custom module

Requirements : ✔️

First of all, in order to use this module you MUST have installed the necessary library on your control node and/or in your environment.

Python lib:

• Plotly
• Kaleido

You can install these libraries directly from pip
If you have no way of modifying your control node or environment, you can install the libraries by the pip module directly via the playbook that will use this module.

SAMPLE: ▶️

  - name: Install plotly
    become: false
    ansible.builtin.pip:
      name: plotly=6.0.0
    delegate_to: localhost

You can also install the libraries via .whl files

  - name: Install plotly
    become: false
    ansible.builtin.pip:
      name: /tmp/plotly-6.0.0-py3-none-any.whl
    delegate_to: localhost

Parameters : 📋

Parameter	Type	Required	Sample	Comment
titlechart	str	❌ No	"CPU Usage Over Time"	Title displayed at the top of the chart.
type	str	✅ Yes	"line"	Type of chart. Options: "line", "bar", "pie", "donut".
xaxis	list	❌ No	["2025-02-06T12:10", "2025-02-06T12:20"]	X-axis data values (time or categories).
xaxisname	str	❌ No	"Timestamp"	Label for the X-axis.
yaxis	list	❌ No	[[12.3, 14.5, 13.1], [5.2, 6.3, 5.8]]	List of Y-axis data series.
yaxisname	list	❌ No	["User %", "System %"]	List of labels for Y-axis data series.
yaxiscolor	list	❌ No	["red", "blue"]	Colors for each Y-axis series.
imgwidth	int	❌ No	1920	Width of the output image (pixels).
imgheight	int	❌ No	1080	Height of the output image (pixels).
shape_line	str	❌ No	"spline"	Shape of lines in line charts. Options: "spline", "linear".
format	str	❌ No	"png"	Output format. Options: "png", "jpeg", "webp", "svg", "pdf", "eps".
path	str	✅ Yes	"/charts"	Directory where the chart image is saved.
filename	str	✅ Yes	"cpu_usage"	Name of the saved image file (without extension).
fontsize	int	❌ No	20	Font size for text elements.
fontcolor	str	❌ No	"#333333"	Font color for all chart text.
titlelegend	str	❌ No	"CPU Breakdown"	Title displayed for the legend.
slicedata	list	❌ No	[50, 30, 20]	Values for pie or donut charts.
slicelabel	list	❌ No	["Cache", "Swap", "RAM"]	Labels for pie or donut chart slices.
slicecolor	list	❌ No	["orange", "blue", "green"]	Colors assigned to each slice in pie or donut charts.
sizehole	float	❌ No	0.5	Size of the hole in a donut chart (0 for pie).

Attributes : 📋

Attribute	Support	Description
check_mode	full	Can run in check_mode and return changed status prediction without modifying target.

EXAMPLES : 📊

This portion of code converts the load average data collected by sar using my other module sar_facts.

    - name: Collect CPU Usage Data
      sar_facts:
        type: "cpu"
        date_start: "2025-02-06"
        date_end: "2025-02-07"

    - name: Generate CPU Usage Line Chart
      charts:
        titlechart: "CPU Usage Over Time (Multi-Day)"
        type: "line"
        xaxis: "{{ ansible_facts.sar_cpu | map(attribute='date') | zip(ansible_facts.sar_cpu | map(attribute='time')) | map('join', 'T') | list }}"
        xaxisname: "Timestamp"
        yaxis:
          - "{{ ansible_facts.sar_cpu | selectattr('%user', 'defined') | map(attribute='%user') | map('float') | list }}"
          - "{{ ansible_facts.sar_cpu | selectattr('%system', 'defined') | map(attribute='%system') | map('float') | list }}"
          - "{{ ansible_facts.sar_cpu | selectattr('%idle', 'defined') | map(attribute='%idle') | map('float') | list }}"
        yaxisname: ["User %", "System %", "Idle %"]
        yaxiscolor: ["#FF5733", "#33A1FF", "#28A745"]
        imgwidth: 1920
        imgheight: 1080
        shape_line: "spline"
        format: "png"
        path: "/tmp"
        filename: "cpu_usage_chart_multi_day"
        titlelegend: "CPU Breakdown"
      delegate_to: localhost

Return :

• This module return 'changed': True

Key	Type	Sample
changed	boolean	True

Integration

1. Assuming you are in the root folder of your ansible project.

Specify a module path in your ansible configuration file.

$ vim ansible.cfg

[defaults]
...
library = ./library
...

Create the directory and copy the python modules into that directory

$ mkdir library
$ cp path/to/module library

2. If you use Ansible AWX and have no way to edit the control node, you can add the /library directory to the same directory as the playbook .yml file

├── root repository
│   ├── playbooks
│   │    ├── /library                
│   │    │   └── write_charts.py        ##<-- python custom module
│   │    └── your_playbook.yml          ##<-- you playbook