A module to extract metrics from Ansible scripts
Project description
For full documentation visit the radon-h2020.github.io.
AnsibleMetrics
AnsibleMetrics is a Python-based static source code analyzer for Ansible blueprints that helps to quantify the characteristics of infrastructure code to support DevOps engineers when maintaining and evolving it. It currently supports 46 source code metrics, though other metrics can be derived by combining the implemented ones.
It represents a step forward towards closing the gap for the implementation of software quality in-struments to support DevOps engineers when developing and maintaining infrastructure code and the development of measurement models for its quality!
How to install
Installation is made simple by the PyPI repository. Download the tool and install it with:
pip install ansible-metrics
or, alternatively from the source code project directory:
pip install -r requirements.txt
pip install .
How to use
Command-line
Run ansible-metrics --help
for instructions about the usage:
usage: ansible-metrics [-h] [--omit-zero-metrics] [-d DEST] [-o] [-v] src
Extract metrics from Ansible scripts.
positional arguments:
src source file (playbook or tasks file) or
directory
optional arguments:
-h, --help show this help message and exit
--omit-zero-metrics omit metrics with value equal 0
-d DEST, --dest DEST destination path to save results
-o, --output shows output
-v, --version show program's version number and exit
Assume that the following example is named playbook1.yml:
---
- hosts: webservers
vars:
http_port: 80
remote_user: root
tasks:
- name: ensure apache is at the latest version
yum:
name: httpd
state: latest
- hosts: databases
remote_user: root
tasks:
- name: ensure postgresql is at the latest version
yum:
name: postgresql
state: latest
- name: ensure that postgresql is started
service:
name: postgresql
state: started
and is located within the folder playbooks as follows:
playbooks
|- playbook1.yml
|- playbook3.yml
|- playbook3.yml
Also, assume the user's working directory is the playbooks folder. Then, it is possible to extract source code characteristics from that blueprint by running the following command:
ansible-metrics --omit-zero-metrics playbook1.yml --dest report.json
For this example, the \textit{report.json} will result in
{
"filepath": "playbook1.yml",
"avg_play_size": 10,
"avg_task_size": 4,
"lines_blank": 4,
"lines_code": 20,
"num_keys": 20,
"num_parameters": 6,
"num_plays": 2,
"num_tasks": 3,
"num_tokens": 50,
"num_unique_names": 3,
"num_vars": 1,
"text_entropy": 4.37
}
Python
AnsibleMetrics currently supports up to 46 source code metrics, implemented in Python. To extract the value for a given metric follow this pattern:
from io import StringIO
from ansiblemetrics.<general|playbook>.<metric> import <Metric>
script = 'a valid yaml script'
value = <Metric>(StringIO(script).count()
where has to be replaced with the name of the desired metric module to compute the value of a specific metric.
The difference between the general and the playbook modules lies in the fact that the playbook module contains metrics specific to playbooks (for example, the number of plays and tasks), while the general module contains metrics that can be generalized to other languages (for example, the lines of code).
For example, to count the number of lines of code:
from io import StringIO
from ansiblemetrics.general.loc import LOC
script = """
---
- hosts: all
tasks:
- name: This is a task!
debug:
msg: "Hello World"
"""
metric = LOC(StringIO(script))
print('Lines of executable code:', metric.count())
# This will result in
# > Lines of executable code: 5
To extract the value for the 46 metrics at once, import the ansiblemetrics.metrics_extractor
package and call the method extract_all()
(in this case the return value will be a json object):
from io import StringIO
from ansiblemetrics.metrics_extractor import extract_all
script = """
---
- hosts: all
tasks:
- name: This is a task!
debug:
msg: "Hello World"
"""
metrics = extract_all(StringIO(script))
print('Lines of executable code:', metrics['lines_code'])
# This will result in
# > Lines of executable code: 5
How to contribute
First, clone the repository as following:
git clone https://github.com/radon-h2020/radon-ansible-metrics.git
Then, move to the folder location and run
pip install -r requirements.txt
to install dependencies.
Execute pytest
to run the test suite.
Step 1: Create a new branch to work on the metric
Create a branch to implement (or update) and test a given metrics.
Move to project folder and run the following commands:
git checkout master
to move to branchmaster
git pull
to be sure to be updated with the latest versiongit checkout -b <metric_name>
to create and move to the new working branch.
Step 2: Document metric
First, document the new metric with the intended behaviour and examples in the docs folder.
Name the documentation file with the metric name and follow the format present in the existing metrics to describe it.
Step 3: Create Test Case
Create a test case in the tests folder and name it as tests_<metric>_count.py.
Step 4: Implement metric
Finally, create the script that implement the metric in the folder ansiblemetrics/<general|playbook>.
Define the method to test with an empty body.
Run pytest
to make sure test cases implemented at Step 3 fail.
Implement the body of the method.
Run pytest
again to make sure test cases implemented at Step 3 pass.
Step 4: Commit your work
Move to project folder and run the following commands:
-
git add <modified_file>
for each modified files,git add .
to add all modified files (be carefull that the right files are added when using this option); -
git status
is helpful to check what files have been changed/added/deleted; -
Once ready, run
git commit -m "A message describing the work done"
; -
Finally,
git push origin/<branch_name>
and open a pull request if you desire to integrate your changes to the master branch;
CHANGELOG
For information about the releases history see the CHANGELOG
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ansiblemetrics-0.3.8-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e8bd74f18429c6349c95b06d90b25ec364302a8b8e447742949c2b8c33bb2185 |
|
MD5 | b5dcfef20985d7894efe51672a7352c1 |
|
BLAKE2b-256 | 6051eb5246a00798ebf5fff2d642c0a045be7813daf5067ee43cb0411b1bc831 |