Working with Callback Plugins

1. Understanding Callback Plugins

Property	Description	Default Value
callback_plugins	List of callback plugins to enable	None
callback_enabled	Enable or disable specific callback plugins	None
callback_filter	Filter which events are sent to callback plugins	None

Example: Enabling a Callback Plugin

callback_plugins:
  - timer
  - mail

Example: Configuring Callback Plugin Settings

callback_plugins:
  - timer
callback_enabled:
  - mail: true
  - timer: false

Note: Callback plugins can be used to send notifications, log events, or modify output formatting.

2. Using JSON Callback

Option	Values	Notes
callback_plugins	`json`	Enables the JSON callback plugin to output results in JSON format
callback_output_dir	`/var/log/ansible`	Directory where JSON output files are stored
callback_json_file	`ansible_output.json`	Name of the output file for JSON results

Example: Using JSON Callback Plugin

ansible-playbook site.yml -v --callback json --output-dir /var/log/ansible

Note: The JSON callback plugin outputs detailed execution results in structured JSON format, useful for integration with monitoring tools or CI/CD pipelines.

3. Using YAML Callback

Option	Values	Notes
callback_plugins	`yaml`	Enables the YAML callback plugin for output formatting
callback_output_format	`yaml`	Specifies the output format as YAML (default is json)

Example: YAML Callback Configuration

---
callback_plugins:
  - yaml
callback_output_format: yaml

Note: The YAML callback plugin outputs results in YAML format, which can be more human-readable than JSON for complex data structures.

4. Using Timer Plugin

Option	Values	Notes
callback_plugins	`timer`	Enable the timer callback plugin

Example: Timer Plugin Configuration

callback_plugins = timer

Note: The timer plugin logs the execution time of each task and the total playbook execution time.

Timer Plugin Features

Logs execution time for each task
Reports total playbook execution time
Helps in performance analysis and optimization

5. Creating Custom Callbacks

Property	Description	Values
callback_plugins	Directory where custom callback plugins are stored	`callback_plugins/`

Example: Custom Callback Plugin Structure

# callback_plugins/my_callback.py
from ansible.plugins.callback import CallbackBase

class CallbackModule(CallbackBase):
    CALLBACK_NAME = 'my_callback'
    CALLBACK_VERSION = '1.0'
    CALLBACK_TYPE = 'notification'

    def v2_runner_on_ok(self, result):
        self._display.display(f"Task completed: {result._task.name}")

    def v2_runner_on_failed(self, result):
        self._display.display(f"Task failed: {result._task.name}")

Note: Callback plugins must inherit from CallbackBase and define at least CALLBACK_NAME.

Key Methods in Callback Plugins

v2_runner_on_ok — Triggered on successful task completion
v2_runner_on_failed — Triggered on task failure
v2_playbook_on_start — Triggered when playbook starts
v2_playbook_on_end — Triggered when playbook ends

6. Enabling Multiple Callbacks

Example: Configuring Multiple Callbacks

---
callback_plugins: ["default", "slack", "mail"]

Callback Plugin	Description	Configuration Option	Notes
default	Default Ansible callback plugin	`callback_plugins`	Always enabled by default
slack	Sends results to Slack channels	`callback_plugins`	Requires `slack` plugin and configuration
mail	Sends results via email	`callback_plugins`	Requires `mail` plugin and configuration
json	Outputs results in JSON format	`callback_plugins`	Useful for integration with other tools
timer	Measures and logs execution time	`callback_plugins`	Helps in performance analysis

Note: Multiple callback plugins can be enabled by specifying them in a list under the callback_plugins configuration key.

Warning: Enabling too many callback plugins can impact performance and increase log verbosity.

7. Using Oneline Callback

Option	Values	Notes
callback_plugins	`oneline`	Enables the one-line callback plugin
display_skipped_hosts	`false`	Hide skipped hosts in output
display_ok_hosts	`true`	Show successful hosts in output

Example: Using Oneline Callback

ansible-playbook site.yml -v --callback oneline

Note: The oneline callback provides a compact output format, ideal for CI/CD environments or when minimal console output is preferred.

8. Configuring Callbacks

Configuration Option	Values	Description
callback_plugins	`["default", "timer"]`	List of callback plugins to enable. Default includes basic output and timing.
callback_enabled	`["default", "timer"]`	Alias for `callback_plugins`; enables specified plugins.
callback_filter	`["stdout", "debug"]`	Filters which events are sent to the callback plugins.

Example: Enabling custom callback plugin

callback_plugins:
  - custom_logger
  - timer

callback_enabled:
  - default
  - custom_logger

Note: Callback plugins can be configured in ansible.cfg, via CLI with -c, or through environment variables like ANSIBLE_CALLBACK_PLUGINS.

Warning: Custom callback plugins must be in the correct plugin directory or specified via ANSIBLE_CALLBACK_PLUGINS to be loaded.

Plugin	Description	Use Case
default	Basic output formatting for task results.	Standard logging and output display.
timer	Measures and logs task execution times.	Performance analysis and optimization.
custom_logger	Custom logging to external systems (e.g., Slack, email).	Integration with monitoring or alerting tools.

9. Sending Notifications

Option	Values	Notes
callback_plugins	`["notification"]`	Enable notification callback plugin
notification_url	`https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`	Slack webhook URL for sending notifications
notification_message	`Ansible playbook run completed successfully.`	Custom message to send in notification

Example: Slack Notification Configuration

callback_plugins: ['notification']
notification_url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'
notification_message: 'Ansible playbook run completed successfully.'

Note: Ensure the webhook URL is kept secure and not exposed in version control.

10. Logging Results

Option	Values	Description
callback_plugins	`default`, `json`, `yaml`	Specifies the callback plugins to use for logging results
callback_output_format	`json`, `yaml`	Determines the format of the logged output
callback_log_dir	`/var/log/ansible`	Directory where the logs will be stored

Example: Configuring JSON logging

callback_plugins: ["json"]
callback_output_format: "json"
callback_log_dir: "/var/log/ansible"

Note: The json callback plugin logs results in JSON format, which is useful for integration with other systems.

Warning: Ensure that the log directory has appropriate permissions to allow Ansible to write logs.