Introducing the Logentries callback plugin for Ansible

ansible-le-plugin

Ansible is an automation tool for deploying, configuring and orchestrating systems. It’s written in python and it is easily extended.

A callback plugin for Ansible extends the functionality by being able to respond to events. These responses can be anything from executing tasks to logging information to different destinations.

The Logentries callback takes the result of each action from a playbook or and ad-hoc task and then sends this data to a token based log in the Logentries system. Each event is encoded as JSON before it is sent.

Once this plugin is enabled for a playbook all events are automatically sent to Logentries without further intervention from the operator.

In order to use the Logentries callback plugin you will need Ansible v2.0.0-0.6.rc1 or newer. The Logentries callback plugin has already been merged into the Ansible project. You’ll need to install a few extra python libraries too, namely ‘certifi’ and ‘flatdict’ from pip or from your packaging system.

pip install certifi flatdict

You will also need a log token which can be obtained from the Logentries service. Once you have a log token that you wish to send logs too, you can proceed to setup the plugin for your Ansible playbooks.

In this example, we assume the reader has used Ansible before and has an existing git repository filled with playbooks that are used for setting up systems and deploying applications.

Firstly, in your project you need to add an ‘ansible.cfg’ file if you do not have one already. Here is a sample of the bare minimum needed to run the plugin

[defaults]

callback_whitelist = logentries

Once the plugin is enabled you must set a few environment variables to decide how you want to use the plugin. In the following example, we configure the plugin to send data to the data.logentries.com endpoint on port 10000.

export LOGENTRIES_API=data.logentries.com

export LOGENTRIES_PORT=10000

export LOGENTRIES_ANSIBLE_TOKEN=dd21fc88-f00a-43ff-b977-e3a4233c53af

There are a number of other configurable parameters in the plugin which can be found by looking at the documentation and implementation at https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/callback/logentries.py

Once the environment variables are setup there are no changes to the existing workflow that you might have with running Ansible. For example, with this playbook:


- hosts: 127.0.0.1
  connection: local

  tasks:
    - debug: msg="Hello I'm running {{ ansible_distribution }}"

Executing will generate this output on stdout

PLAY **********************************************

TASK [setup] *************************************************

ok: [127.0.0.1]

TASK [debug msg=Hello I'm running {{ ansible_distribution }}] 
*************************************************

ok: [127.0.0.1] => {

"changed": false,

"msg": "Hello I'm running Ubuntu"

}

PLAY RECAP ****************************************************

127.0.0.1      : ok=2    changed=0    unreachable=0    failed=0

Behind the scenes, a formatted output event is sent to Logentries and appears as:

27 Nov 2015 14:58:05.669 { "hostname": "127.0.0.1", "le_jobid": "a1d7d933-f69d-43b1-b3b3-b91bf6522b24", "results": { "_ansible_no_log": false, "_ansible_verbose_always": true, "changed": false, "invocation": { "module_args": { "msg": "Hello I'm running Ubuntu" }, "module_name": "debug" }, "msg": "Hello I'm running Ubuntu" }, "status": "OK" }

With this callback plugin, we enable Ansible to send it’s output to Logentries. This can be useful in many scenarios, such as the debugging of continuous deployments and logging actions being carried out against targeted hosts for security and auditing purposes. Here at Logentries we use this plugin to log actions carried out by Ansible to help developers debug issues that may arise in our pipelines.


 

Ready to start getting insights from your applications? Sign up for a Logentries free trial today.

Tagged with: ,
Posted in DevOps, How To

Leave a Reply