a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[PR #9455/d887930e backport][stable-9] normalize docs in callback plugins (#9466) 

normalize docs in callback plugins (#9455)

* normalize docs in callback plugins

Normalize doc blocks for plugins

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit d887930e49)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
pull/9473/head
patchback[bot] 2024-12-29 21:24:13 +01:00 committed by GitHub
parent 015496fa9e
commit 6f3cfd3385
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
26 changed files with 1478 additions and 1489 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
plugins/callback/cgroup_memory_recap.py
View File

@ -7,21 +7,22 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: cgroup_memory_recap
type: aggregate
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: cgroup_memory_recap
type: aggregate
requirements:
- whitelist in configuration
- cgroups
short_description: Profiles maximum memory usage of tasks and full execution using cgroups
description:
- This is an ansible callback plugin that profiles maximum memory usage of ansible and individual tasks, and displays a recap at the end using cgroups.
notes:
- Requires ansible to be run from within a cgroup, such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
- This cgroup should only be used by ansible to get accurate results.
- To create the cgroup, first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile).
options:
short_description: Profiles maximum memory usage of tasks and full execution using cgroups
description:
- This is an Ansible callback plugin that profiles maximum memory usage of Ansible and individual tasks, and displays a
recap at the end using cgroups.
notes:
- Requires ansible to be run from within a C(cgroup), such as with C(cgexec -g memory:ansible_profile ansible-playbook ...).
- This C(cgroup) should only be used by Ansible to get accurate results.
- To create the C(cgroup), first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile).
options:
max_mem_file:
required: true
description: Path to cgroups C(memory.max_usage_in_bytes) file. Example V(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes).
@ -40,7 +41,7 @@ DOCUMENTATION = '''
ini:
- section: callback_cgroupmemrecap
key: cur_mem_file
'''
"""
import time
import threading

16
plugins/callback/context_demo.py
View File

@ -7,17 +7,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: context_demo
type: aggregate
short_description: demo callback that adds play/task context
description:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: context_demo
type: aggregate
short_description: demo callback that adds play/task context
description:
- Displays some play and task context along with normal output.
- This is mostly for demo purposes.
requirements:
requirements:
- whitelist in configuration
'''
"""
from ansible.plugins.callback import CallbackBase

18
plugins/callback/counter_enabled.py
View File

@ -9,20 +9,20 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: counter_enabled
type: stdout
short_description: adds counters to the output items (tasks and hosts/task)
description:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: counter_enabled
type: stdout
short_description: adds counters to the output items (tasks and hosts/task)
description:
- Use this callback when you need a kind of progress bar on a large environments.
- You will know how many tasks has the playbook to run, and which one is actually running.
- You will know how many hosts may run a task, and which of them is actually running.
extends_documentation_fragment:
extends_documentation_fragment:
- default_callback
requirements:
requirements:
- set as stdout callback in C(ansible.cfg) (C(stdout_callback = counter_enabled))
'''
"""
from ansible import constants as C
from ansible.plugins.callback import CallbackBase

29
plugins/callback/default_without_diff.py
View File

@ -7,23 +7,22 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
name: default_without_diff
type: stdout
short_description: The default ansible callback without diff output
version_added: 8.4.0
description:
- This is basically the default ansible callback plugin (P(ansible.builtin.default#callback)) without
showing diff output. This can be useful when using another callback which sends more detailed information
to another service, like the L(ARA, https://ara.recordsansible.org/) callback, and you want diff output
sent to that plugin but not shown on the console output.
author: Felix Fontein (@felixfontein)
extends_documentation_fragment:
DOCUMENTATION = r"""
name: default_without_diff
type: stdout
short_description: The default ansible callback without diff output
version_added: 8.4.0
description:
- This is basically the default ansible callback plugin (P(ansible.builtin.default#callback)) without showing diff output.
This can be useful when using another callback which sends more detailed information to another service, like the L(ARA,
https://ara.recordsansible.org/) callback, and you want diff output sent to that plugin but not shown on the console output.
author: Felix Fontein (@felixfontein)
extends_documentation_fragment:
- ansible.builtin.default_callback
- ansible.builtin.result_format_callback
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
# Enable callback in ansible.cfg:
ansible_config: |
[defaults]
@ -32,7 +31,7 @@ ansible_config: |
# Enable callback with environment variables:
environment_variable: |
ANSIBLE_STDOUT_CALLBACK=community.general.default_without_diff
'''
"""
from ansible.plugins.callback.default import CallbackModule as Default

12
plugins/callback/dense.py
View File

@ -7,19 +7,19 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: dense
type: stdout
short_description: minimal stdout output
extends_documentation_fragment:
- default_callback
- default_callback
description:
- When in verbose mode it will act the same as the default callback.
- When in verbose mode it will act the same as the default callback.
author:
- Dag Wieers (@dagwieers)
- Dag Wieers (@dagwieers)
requirements:
- set as stdout in configuration
'''
- set as stdout in configuration
"""
HAS_OD = False
try:

73
plugins/callback/diy.py
View File

@ -7,48 +7,43 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
name: diy
type: stdout
short_description: Customize the output
version_added: 0.2.0
description:
DOCUMENTATION = r"""
name: diy
type: stdout
short_description: Customize the output
version_added: 0.2.0
description:
- Callback plugin that allows you to supply your own custom callback templates to be output.
author: Trevor Highfill (@theque5t)
extends_documentation_fragment:
author: Trevor Highfill (@theque5t)
extends_documentation_fragment:
- default_callback
notes:
notes:
- Uses the P(ansible.builtin.default#callback) callback plugin output when a custom callback V(message(msg\)) is not provided.
- Makes the callback event data available via the C(ansible_callback_diy) dictionary, which can be used in the templating context for the options.
The dictionary is only available in the templating context for the options. It is not a variable that is available via the other
various execution contexts, such as playbook, play, task etc.
- Options being set by their respective variable input can only be set using the variable if the variable was set in a context that is available to the
respective callback.
Use the C(ansible_callback_diy) dictionary to see what is available to a callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output
the top level variable names available to the callback.
- Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For example,
C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}")
- "**Condition** for all C(msg) options:
if value C(is None or omit),
then the option is not being used.
**Effect**: use of the C(default) callback plugin for output"
- "**Condition** for all C(msg) options:
if value C(is not None and not omit and length is not greater than 0),
then the option is being used without output.
**Effect**: suppress output"
- "**Condition** for all C(msg) options:
if value C(is not None and not omit and length is greater than 0),
then the option is being used with output.
**Effect**: render value as template and output"
- "Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green), V(red), V(bright cyan),
V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta), V(bright magenta), V(normal)"
seealso:
- Makes the callback event data available using the C(ansible_callback_diy) dictionary, which can be used in the templating
context for the options. The dictionary is only available in the templating context for the options. It is not a variable
that is available using the other various execution contexts, such as playbook, play, task, and so on so forth.
- Options being set by their respective variable input can only be set using the variable if the variable was set in a context
that is available to the respective callback. Use the C(ansible_callback_diy) dictionary to see what is available to a
callback. Additionally, C(ansible_callback_diy.top_level_var_names) will output the top level variable names available
to the callback.
- Each option value is rendered as a template before being evaluated. This allows for the dynamic usage of an option. For
example, C("{{ 'yellow' if ansible_callback_diy.result.is_changed else 'bright green' }}").
- 'B(Condition) for all C(msg) options: if value C(is None or omit), then the option is not being used. B(Effect): use
of the C(default) callback plugin for output.'
- 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is not greater than 0), then the
option is being used without output. B(Effect): suppress output.'
- 'B(Condition) for all C(msg) options: if value C(is not None and not omit and length is greater than 0), then the option
is being used with output. B(Effect): render value as template and output.'
- 'Valid color values: V(black), V(bright gray), V(blue), V(white), V(green), V(bright blue), V(cyan), V(bright green),
V(red), V(bright cyan), V(purple), V(bright red), V(yellow), V(bright purple), V(dark gray), V(bright yellow), V(magenta),
V(bright magenta), V(normal).'
seealso:
- name: default – default Ansible screen output
description: The official documentation on the B(default) callback plugin.
link: https://docs.ansible.com/ansible/latest/plugins/callback/default.html
requirements:
requirements:
- set as stdout_callback in configuration
options:
options:
on_any_msg:
description: Output to be used for callback on_any.
ini:
@ -600,9 +595,9 @@ DOCUMENTATION = r'''
vars:
- name: ansible_callback_diy_playbook_on_setup_msg_color
type: str
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
ansible.cfg: >
# Enable plugin
[defaults]
@ -623,7 +618,7 @@ ansible.cfg: >
# Newline after every callback
# on_any_msg='{{ " " | join("\n") }}'
playbook.yml: >
playbook.yml: >-
---
- name: "Default plugin output: play example"
hosts: localhost
@ -782,7 +777,7 @@ playbook.yml: >
{{ white }}{{ ansible_callback_diy[key] }}
{% endfor %}
'''
"""
import sys
from contextlib import contextmanager

30
plugins/callback/elastic.py
View File

@ -5,17 +5,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Victor Martinez (@v1v) <VictorMartinezRubio@gmail.com>
name: elastic
type: notification
short_description: Create distributed traces for each Ansible task in Elastic APM
version_added: 3.8.0
description:
DOCUMENTATION = r"""
author: Victor Martinez (@v1v) <VictorMartinezRubio@gmail.com>
name: elastic
type: notification
short_description: Create distributed traces for each Ansible task in Elastic APM
version_added: 3.8.0
description:
- This callback creates distributed traces for each Ansible task in Elastic APM.
- You can configure the plugin with environment variables.
- See U(https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html).
options:
options:
hide_task_arguments:
default: false
type: bool
@ -39,13 +39,13 @@ DOCUMENTATION = '''
apm_secret_token:
type: str
description:
- Use the APM server token
- Use the APM server token.
env:
- name: ELASTIC_APM_SECRET_TOKEN
apm_api_key:
type: str
description:
- Use the APM API key
- Use the APM API key.
env:
- name: ELASTIC_APM_API_KEY
apm_verify_server_cert:
@ -61,13 +61,13 @@ DOCUMENTATION = '''
- The L(W3C Trace Context header traceparent,https://www.w3.org/TR/trace-context-1/#traceparent-header).
env:
- name: TRACEPARENT
requirements:
requirements:
- elastic-apm (Python library)
'''
"""
EXAMPLES = '''
examples: |
EXAMPLES = r"""
examples: |-
Enable the plugin in ansible.cfg:
[defaults]
callbacks_enabled = community.general.elastic
@ -76,7 +76,7 @@ examples: |
export ELASTIC_APM_SERVER_URL=<your APM server URL)>
export ELASTIC_APM_SERVICE_NAME=your_service_name
export ELASTIC_APM_API_KEY=your_APM_API_KEY
'''
"""
import getpass
import socket

26
plugins/callback/jabber.py
View File

@ -7,42 +7,42 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: jabber
type: notification
short_description: post task events to a jabber server
description:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: jabber
type: notification
short_description: post task events to a Jabber server
description:
- The chatty part of ChatOps with a Hipchat server as a target.
- This callback plugin sends status updates to a HipChat channel during playbook execution.
requirements:
requirements:
- xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
options:
options:
server:
description: connection info to jabber server
description: Connection info to Jabber server.
type: str
required: true
env:
- name: JABBER_SERV
user:
description: Jabber user to authenticate as
description: Jabber user to authenticate as.
type: str
required: true
env:
- name: JABBER_USER
password:
description: Password for the user to the jabber server
description: Password for the user to the Jabber server.
type: str
required: true
env:
- name: JABBER_PASS
to:
description: chat identifier that will receive the message
description: Chat identifier that will receive the message.
type: str
required: true
env:
- name: JABBER_TO
'''
"""
import os

18
plugins/callback/log_plays.py
View File

@ -7,17 +7,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: log_plays
type: notification
short_description: write playbook output to log file
description:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: log_plays
type: notification
short_description: write playbook output to log file
description:
- This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
requirements:
requirements:
- Whitelist in configuration
- A writeable C(/var/log/ansible/hosts) directory by the user executing Ansible on the controller
options:
options:
log_folder:
default: /var/log/ansible/hosts
description: The folder where log files will be created.
@ -27,7 +27,7 @@ DOCUMENTATION = '''
ini:
- section: callback_log_plays
key: log_folder
'''
"""
import os
import time

26
plugins/callback/loganalytics.py
View File

@ -6,19 +6,19 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: loganalytics
type: notification
short_description: Posts task results to Azure Log Analytics
author: "Cyrus Li (@zhcli) <cyrus1006@gmail.com>"
description:
DOCUMENTATION = r"""
name: loganalytics
type: notification
short_description: Posts task results to Azure Log Analytics
author: "Cyrus Li (@zhcli) <cyrus1006@gmail.com>"
description:
- This callback plugin will post task results in JSON formatted to an Azure Log Analytics workspace.
- Credits to authors of splunk callback plugin.
version_added: "2.4.0"
requirements:
version_added: "2.4.0"
requirements:
- Whitelisting this callback plugin.
- An Azure log analytics work space has been established.
options:
options:
workspace_id:
description: Workspace ID of the Azure log analytics workspace.
type: str
@ -37,10 +37,10 @@ DOCUMENTATION = '''
ini:
- section: callback_loganalytics
key: shared_key
'''
"""
EXAMPLES = '''
examples: |
EXAMPLES = r"""
examples: |-
Whitelist the plugin in ansible.cfg:
[defaults]
callback_whitelist = community.general.loganalytics
@ -51,7 +51,7 @@ examples: |
[callback_loganalytics]
workspace_id = 01234567-0123-0123-0123-01234567890a
shared_key = dZD0kCbKl3ehZG6LHFMuhtE0yHiFCmetzFMc2u+roXIUQuatqU924SsAAAAPemhjbGlAemhjbGktTUJQAQIDBA==
'''
"""
import hashlib
import hmac

18
plugins/callback/logdna.py
View File

@ -6,17 +6,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: logdna
type: notification
short_description: Sends playbook logs to LogDNA
description:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: logdna
type: notification
short_description: Sends playbook logs to LogDNA
description:
- This callback will report logs from playbook actions, tasks, and events to LogDNA (U(https://app.logdna.com)).
requirements:
requirements:
- LogDNA Python Library (U(https://github.com/logdna/python))
- whitelisting in configuration
options:
options:
conf_key:
required: true
description: LogDNA Ingestion Key.
@ -55,7 +55,7 @@ DOCUMENTATION = '''
- section: callback_logdna
key: conf_tags
default: ansible
'''
"""
import logging
import json

28
plugins/callback/logentries.py
View File

@ -6,20 +6,18 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: logentries
type: notification
short_description: Sends events to Logentries
description:
- This callback plugin will generate JSON objects and send them to Logentries via TCP for auditing/debugging purposes.
- Before 2.4, if you wanted to use an ini configuration, the file must be placed in the same directory as this plugin and named C(logentries.ini).
- In 2.4 and above you can just put it in the main Ansible configuration file.
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: logentries
type: notification
short_description: Sends events to Logentries
description:
- This callback plugin will generate JSON objects and send them to Logentries using TCP for auditing/debugging purposes.
requirements:
- whitelisting in configuration
- certifi (Python library)
- flatdict (Python library), if you want to use the O(flatten) option
options:
options:
api:
description: URI to the Logentries API.
type: str
@ -75,10 +73,10 @@ DOCUMENTATION = '''
ini:
- section: callback_logentries
key: flatten
'''
"""
EXAMPLES = '''
examples: >
EXAMPLES = r"""
examples: >-
To enable, add this to your ansible.cfg file in the defaults block
[defaults]
@ -97,7 +95,7 @@ examples: >
use_tls = true
token = dd21fc88-f00a-43ff-b977-e3a4233c53af
flatten = false
'''
"""
import os
import socket

25
plugins/callback/logstash.py
View File

@ -7,17 +7,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
author: Yevhen Khmelenko (@ujenmr)
name: logstash
type: notification
short_description: Sends events to Logstash
description:
DOCUMENTATION = r"""
author: Yevhen Khmelenko (@ujenmr)
name: logstash
type: notification
short_description: Sends events to Logstash
description:
- This callback will report facts and task events to Logstash U(https://www.elastic.co/products/logstash).
requirements:
requirements:
- whitelisting in configuration
- logstash (Python library)
options:
options:
server:
description: Address of the Logstash server.
type: str
@ -70,10 +70,9 @@ DOCUMENTATION = r'''
choices:
- v1
- v2
"""
'''
EXAMPLES = r'''
EXAMPLES = r"""
ansible.cfg: |
# Enable Callback plugin
[defaults]
@ -85,7 +84,7 @@ ansible.cfg: |
pre_command = git rev-parse HEAD
type = ansible
11-input-tcp.conf: |
11-input-tcp.conf: |-
# Enable Logstash TCP Input
input {
tcp {
@ -95,7 +94,7 @@ ansible.cfg: |
add_field => { "[@metadata][type]" => "ansible" }
}
}
'''
"""
import os
import json

13
plugins/callback/mail.py
View File

@ -7,16 +7,16 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: mail
type: notification
short_description: Sends failure events via email
short_description: Sends failure events through email
description:
- This callback will report failures via email.
- This callback will report failures through email.
author:
- Dag Wieers (@dagwieers)
- Dag Wieers (@dagwieers)
requirements:
- whitelisting in configuration
- whitelisting in configuration
options:
mta:
description:
@ -80,8 +80,7 @@ options:
- section: callback_mail
key: message_id_domain
version_added: 8.2.0
'''
"""
import json
import os

26
plugins/callback/nrdp.py
View File

@ -7,27 +7,27 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: nrdp
type: notification
author: "Remi VERCHERE (@rverchere)"
short_description: Post task results to a Nagios server through nrdp
description:
DOCUMENTATION = r"""
name: nrdp
type: notification
author: "Remi VERCHERE (@rverchere)"
short_description: Post task results to a Nagios server through nrdp
description:
- This callback send playbook result to Nagios.
- Nagios shall use NRDP to receive passive events.
- The passive check is sent to a dedicated host/service for Ansible.
options:
options:
url:
description: URL of the nrdp server.
required: true
env:
- name : NRDP_URL
- name: NRDP_URL
ini:
- section: callback_nrdp
key: url
type: string
validate_certs:
description: Validate the SSL certificate of the nrdp server. (Used for HTTPS URLs.)
description: Validate the SSL certificate of the nrdp server. (Used for HTTPS URLs).
env:
- name: NRDP_VALIDATE_CERTS
ini:
@ -37,7 +37,7 @@ DOCUMENTATION = '''
key: validate_certs
type: boolean
default: false
aliases: [ validate_nrdp_certs ]
aliases: [validate_nrdp_certs]
token:
description: Token to be allowed to push nrdp events.
required: true
@ -51,7 +51,7 @@ DOCUMENTATION = '''
description: Hostname where the passive check is linked to.
required: true
env:
- name : NRDP_HOSTNAME
- name: NRDP_HOSTNAME
ini:
- section: callback_nrdp
key: hostname
@ -60,12 +60,12 @@ DOCUMENTATION = '''
description: Service where the passive check is linked to.
required: true
env:
- name : NRDP_SERVICENAME
- name: NRDP_SERVICENAME
ini:
- section: callback_nrdp
key: servicename
type: string
'''
"""
from ansible.module_utils.six.moves.urllib.parse import urlencode
from ansible.module_utils.common.text.converters import to_bytes

16
plugins/callback/null.py
View File

@ -7,16 +7,16 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: 'null'
type: stdout
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: 'null'
type: stdout
requirements:
- set as main display callback
short_description: Don't display stuff to screen
description:
short_description: do not display stuff to screen
description:
- This callback prevents outputting events to screen.
'''
"""
from ansible.plugins.callback import CallbackBase

39
plugins/callback/opentelemetry.py
View File

@ -6,18 +6,19 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Victor Martinez (@v1v) <VictorMartinezRubio@gmail.com>
name: opentelemetry
type: notification
short_description: Create distributed traces with OpenTelemetry
version_added: 3.7.0
description:
DOCUMENTATION = r"""
author: Victor Martinez (@v1v) <VictorMartinezRubio@gmail.com>
name: opentelemetry
type: notification
short_description: Create distributed traces with OpenTelemetry
version_added: 3.7.0
description:
- This callback creates distributed traces for each Ansible task with OpenTelemetry.
- You can configure the OpenTelemetry exporter and SDK with environment variables.
- See U(https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html).
- See U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#opentelemetry-sdk-environment-variables).
options:
- See
U(https://opentelemetry-python.readthedocs.io/en/latest/sdk/environment_variables.html#opentelemetry-sdk-environment-variables).
options:
hide_task_arguments:
default: false
type: bool
@ -33,10 +34,10 @@ DOCUMENTATION = '''
type: str
description:
- Whether to enable this callback only if the given environment variable exists and it is set to V(true).
- This is handy when you use Configuration as Code and want to send distributed traces
if running in the CI rather when running Ansible locally.
- For such, it evaluates the given O(enable_from_environment) value as environment variable
and if set to true this plugin will be enabled.
- This is handy when you use Configuration as Code and want to send distributed traces if running in the CI rather when
running Ansible locally.
- For such, it evaluates the given O(enable_from_environment) value as environment variable and if set to true this
plugin will be enabled.
env:
- name: ANSIBLE_OPENTELEMETRY_ENABLE_FROM_ENVIRONMENT
ini:
@ -87,7 +88,7 @@ DOCUMENTATION = '''
store_spans_in_file:
type: str
description:
- It stores the exported spans in the given file
- It stores the exported spans in the given file.
env:
- name: ANSIBLE_OPENTELEMETRY_STORE_SPANS_IN_FILE
ini:
@ -110,15 +111,15 @@ DOCUMENTATION = '''
- section: callback_opentelemetry
key: otel_exporter_otlp_traces_protocol
version_added: 9.0.0
requirements:
requirements:
- opentelemetry-api (Python library)
- opentelemetry-exporter-otlp (Python library)
- opentelemetry-sdk (Python library)
'''
"""
EXAMPLES = '''
examples: |
EXAMPLES = r"""
examples: |-
Enable the plugin in ansible.cfg:
[defaults]
callbacks_enabled = community.general.opentelemetry
@ -130,7 +131,7 @@ examples: |
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer your_otel_token"
export OTEL_SERVICE_NAME=your_service_name
export ANSIBLE_OPENTELEMETRY_ENABLED=true
'''
"""
import getpass
import json

16
plugins/callback/say.py
View File

@ -8,17 +8,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: say
type: notification
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: say
type: notification
requirements:
- whitelisting in configuration
- the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
short_description: notify using software speech synthesizer
description:
short_description: notify using software speech synthesizer
description:
- This plugin will use the C(say) or C(espeak) program to "speak" about play events.
'''
"""
import platform
import subprocess

28
plugins/callback/selective.py
View File

@ -7,19 +7,19 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: selective
type: stdout
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: selective
type: stdout
requirements:
- set as main display callback
short_description: only print certain tasks
description:
- This callback only prints tasks that have been tagged with C(print_action) or that have failed.
This allows operators to focus on the tasks that provide value only.
short_description: only print certain tasks
description:
- This callback only prints tasks that have been tagged with C(print_action) or that have failed. This allows operators
to focus on the tasks that provide value only.
- Tasks that are not printed are placed with a C(.).
- If you increase verbosity all tasks are printed.
options:
options:
nocolor:
default: false
description: This setting allows suppressing colorizing output.
@ -30,11 +30,11 @@ DOCUMENTATION = '''
- section: defaults
key: nocolor
type: boolean
'''
"""
EXAMPLES = """
- ansible.builtin.debug: msg="This will not be printed"
- ansible.builtin.debug: msg="But this will"
EXAMPLES = r"""
- ansible.builtin.debug: msg="This will not be printed"
- ansible.builtin.debug: msg="But this will"
tags: [print_action]
"""

18
plugins/callback/slack.py
View File

@ -8,17 +8,17 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: slack
type: notification
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: slack
type: notification
requirements:
- whitelist in configuration
- prettytable (python library)
short_description: Sends play events to a Slack channel
description:
short_description: Sends play events to a Slack channel
description:
- This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution.
options:
options:
webhook_url:
required: true
description: Slack Webhook URL.
@ -55,7 +55,7 @@ DOCUMENTATION = '''
key: validate_certs
default: true
type: bool
'''
"""
import json
import os

34
plugins/callback/splunk.py
View File

@ -6,20 +6,20 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: splunk
type: notification
short_description: Sends task result events to Splunk HTTP Event Collector
author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>"
description:
DOCUMENTATION = r"""
name: splunk
type: notification
short_description: Sends task result events to Splunk HTTP Event Collector
author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>"
description:
- This callback plugin will send task results as JSON formatted events to a Splunk HTTP collector.
- The companion Splunk Monitoring & Diagnostics App is available here U(https://splunkbase.splunk.com/app/4023/).
- Credit to "Ryan Currah (@ryancurrah)" for original source upon which this is based.
requirements:
requirements:
- Whitelisting this callback plugin
- 'Create a HTTP Event Collector in Splunk'
- 'Define the URL and token in C(ansible.cfg)'
options:
options:
url:
description: URL to the Splunk HTTP collector source.
type: str
@ -37,9 +37,9 @@ DOCUMENTATION = '''
- section: callback_splunk
key: authtoken
validate_certs:
description: Whether to validate certificates for connections to HEC. It is not recommended to set to
V(false) except when you are sure that nobody can intercept the connection
between this plugin and HEC, as setting it to V(false) allows man-in-the-middle attacks!
description: Whether to validate certificates for connections to HEC. It is not recommended to set to V(false) except
when you are sure that nobody can intercept the connection between this plugin and HEC, as setting it to V(false) allows
man-in-the-middle attacks!
env:
- name: SPLUNK_VALIDATE_CERTS
ini:
@ -49,8 +49,8 @@ DOCUMENTATION = '''
default: true
version_added: '1.0.0'
include_milliseconds:
description: Whether to include milliseconds as part of the generated timestamp field in the event
sent to the Splunk HTTP collector.
description: Whether to include milliseconds as part of the generated timestamp field in the event sent to the Splunk
HTTP collector.
env:
- name: SPLUNK_INCLUDE_MILLISECONDS
ini:
@ -69,10 +69,10 @@ DOCUMENTATION = '''
key: batch
type: str
version_added: 3.3.0
'''
"""
EXAMPLES = '''
examples: >
EXAMPLES = r"""
examples: >-
To enable, add this to your ansible.cfg file in the defaults block
[defaults]
callback_whitelist = community.general.splunk
@ -83,7 +83,7 @@ examples: >
[callback_splunk]
url = http://mysplunkinstance.datapaas.io:8088/services/collector/event
authtoken = f23blad6-5965-4537-bf69-5b5a545blabla88
'''
"""
import json
import uuid

14
plugins/callback/sumologic.py
View File

@ -6,7 +6,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
name: sumologic
type: notification
short_description: Sends task result events to Sumologic
@ -15,8 +15,8 @@ description:
- This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source.
requirements:
- Whitelisting this callback plugin
- 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of V(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator
of V("timestamp": "(.*\)")'
- 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of V(yyyy-MM-dd HH:mm:ss ZZZZ) and
a custom timestamp locator of V("timestamp": "(.*\)")'
options:
url:
description: URL to the Sumologic HTTP collector source.
@ -26,10 +26,10 @@ options:
ini:
- section: callback_sumologic
key: url
'''
"""
EXAMPLES = '''
examples: |
EXAMPLES = r"""
examples: |-
To enable, add this to your ansible.cfg file in the defaults block
[defaults]
callback_whitelist = community.general.sumologic
@ -40,7 +40,7 @@ examples: |
Set the ansible.cfg variable in the callback_sumologic block
[callback_sumologic]
url = https://endpoint1.collection.us2.sumologic.com/receiver/v1/http/R8moSv1d8EW9LAUFZJ6dbxCFxwLH6kfCdcBfddlfxCbLuL-BN5twcTpMk__pYy_cDmp==
'''
"""
import json
import uuid

18
plugins/callback/syslog_json.py
View File

@ -7,16 +7,16 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: syslog_json
type: notification
requirements:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: syslog_json
type: notification
requirements:
- whitelist in configuration
short_description: sends JSON events to syslog
description:
short_description: sends JSON events to syslog
description:
- This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
options:
options:
server:
description: Syslog server that will receive the event.
type: str
@ -54,7 +54,7 @@ DOCUMENTATION = '''
- section: callback_syslog_json
key: syslog_setup
version_added: 4.5.0
'''
"""
import logging
import logging.handlers

25
plugins/callback/timestamp.py
View File

@ -10,18 +10,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
name: timestamp
type: stdout
short_description: Adds simple timestamp for each header
version_added: 9.0.0
description:
name: timestamp
type: stdout
short_description: Adds simple timestamp for each header
version_added: 9.0.0
description:
- This callback adds simple timestamp for each header.
author: kurokobo (@kurokobo)
options:
author: kurokobo (@kurokobo)
options:
timezone:
description:
- Timezone to use for the timestamp in IANA time zone format.
- For example C(America/New_York), C(Asia/Tokyo)). Ignored on Python < 3.9.
- For example V(America/New_York), V(Asia/Tokyo)). Ignored on Python < 3.9.
ini:
- section: callback_timestamp
key: timezone
@ -31,8 +31,7 @@ DOCUMENTATION = r"""
format_string:
description:
- Format of the timestamp shown to user in 1989 C standard format.
- >
Refer to L(the Python documentation,https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
- Refer to L(the Python documentation,https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)
for the available format codes.
ini:
- section: callback_timestamp
@ -41,13 +40,13 @@ DOCUMENTATION = r"""
- name: ANSIBLE_CALLBACK_TIMESTAMP_FORMAT_STRING
default: "%H:%M:%S"
type: string
seealso:
seealso:
- plugin: ansible.posix.profile_tasks
plugin_type: callback
description: >
description: >-
You can use P(ansible.posix.profile_tasks#callback) callback plugin to time individual tasks and overall execution time
with detailed timestamps.
extends_documentation_fragment:
extends_documentation_fragment:
- ansible.builtin.default_callback
- ansible.builtin.result_format_callback
"""

18
plugins/callback/unixy.py
View File

@ -8,18 +8,18 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
name: unixy
type: stdout
author: Al Bowles (@akatch)
short_description: condensed Ansible output
description:
DOCUMENTATION = r"""
name: unixy
type: stdout
author: Al Bowles (@akatch)
short_description: condensed Ansible output
description:
- Consolidated Ansible output in the style of LINUX/UNIX startup logs.
extends_documentation_fragment:
extends_documentation_fragment:
- default_callback
requirements:
requirements:
- set as stdout in configuration
'''
"""
from os.path import basename
from ansible import constants as C

34
plugins/callback/yaml.py
View File

@ -7,29 +7,27 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
author: Unknown (!UNKNOWN)
name: yaml
type: stdout
short_description: YAML-ized Ansible screen output
description:
- Ansible output that can be quite a bit easier to read than the
default JSON formatting.
extends_documentation_fragment:
DOCUMENTATION = r"""
author: Unknown (!UNKNOWN)
name: yaml
type: stdout
short_description: YAML-ized Ansible screen output
description:
- Ansible output that can be quite a bit easier to read than the default JSON formatting.
extends_documentation_fragment:
- default_callback
requirements:
requirements:
- set as stdout in configuration
seealso:
seealso:
- plugin: ansible.builtin.default
plugin_type: callback
description: >
There is a parameter O(ansible.builtin.default#callback:result_format) in P(ansible.builtin.default#callback)
that allows you to change the output format to YAML.
notes:
- >
With ansible-core 2.13 or newer, you can instead specify V(yaml) for the parameter O(ansible.builtin.default#callback:result_format)
description: >-
There is a parameter O(ansible.builtin.default#callback:result_format) in P(ansible.builtin.default#callback) that allows
you to change the output format to YAML.
notes:
- With ansible-core 2.13 or newer, you can instead specify V(yaml) for the parameter O(ansible.builtin.default#callback:result_format)
in P(ansible.builtin.default#callback).
'''
"""
import yaml
import json