1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00

[PR #5760/9e3a729d backport][stable-5] Improve callback docs (#5783)

Improve callback docs (#5760)

* Improve callback docs.

* Apply suggestions from code review

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* Update plugins/callback/logentries.py

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* More improvements.

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
(cherry picked from commit 9e3a729da9)

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
patchback[bot] 2023-01-07 11:45:09 +00:00 committed by GitHub
parent 2a6f91b4e4
commit b6e822aad2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 57 additions and 57 deletions

View file

@ -16,15 +16,15 @@ DOCUMENTATION = '''
- cgroups - cgroups
short_description: Profiles maximum memory usage of tasks and full execution using cgroups short_description: Profiles maximum memory usage of tasks and full execution using cgroups
description: 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 - 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: notes:
- Requires ansible to be run from within a cgroup, such as with C(cgexec -g memory:ansible_profile ansible-playbook ...) - 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 - 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) - 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: options:
max_mem_file: max_mem_file:
required: true required: true
description: Path to cgroups C(memory.max_usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes) description: Path to cgroups C(memory.max_usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes).
env: env:
- name: CGROUP_MAX_MEM_FILE - name: CGROUP_MAX_MEM_FILE
ini: ini:
@ -32,7 +32,7 @@ DOCUMENTATION = '''
key: max_mem_file key: max_mem_file
cur_mem_file: cur_mem_file:
required: true required: true
description: Path to C(memory.usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes) description: Path to C(memory.usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes).
env: env:
- name: CGROUP_CUR_MEM_FILE - name: CGROUP_CUR_MEM_FILE
ini: ini:

View file

@ -13,8 +13,8 @@ DOCUMENTATION = '''
type: aggregate type: aggregate
short_description: demo callback that adds play/task context short_description: demo callback that adds play/task context
description: description:
- Displays some play and task context along with normal output - Displays some play and task context along with normal output.
- This is mostly for demo purposes - This is mostly for demo purposes.
requirements: requirements:
- whitelist in configuration - whitelist in configuration
''' '''

View file

@ -21,7 +21,7 @@ DOCUMENTATION = '''
extends_documentation_fragment: extends_documentation_fragment:
- default_callback - default_callback
requirements: requirements:
- set as stdout callback in ansible.cfg (stdout_callback = counter_enabled) - set as stdout callback in C(ansible.cfg) (C(stdout_callback = counter_enabled))
''' '''
from ansible import constants as C from ansible import constants as C

View file

@ -14,7 +14,7 @@ short_description: minimal stdout output
extends_documentation_fragment: extends_documentation_fragment:
- default_callback - default_callback
description: 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: author:
- Dag Wieers (@dagwieers) - Dag Wieers (@dagwieers)
requirements: requirements:

View file

@ -13,10 +13,10 @@ DOCUMENTATION = '''
type: notification type: notification
short_description: post task events to a jabber server short_description: post task events to a jabber server
description: description:
- The chatty part of ChatOps with a Hipchat server as a target - 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. - This callback plugin sends status updates to a HipChat channel during playbook execution.
requirements: requirements:
- xmpp (python lib https://github.com/ArchipelProject/xmpppy) - xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
options: options:
server: server:
description: connection info to jabber server description: connection info to jabber server

View file

@ -13,10 +13,10 @@ DOCUMENTATION = '''
type: notification type: notification
short_description: write playbook output to log file short_description: write playbook output to log file
description: description:
- This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
requirements: requirements:
- Whitelist in configuration - Whitelist in configuration
- A writeable /var/log/ansible/hosts directory by the user executing Ansible on the controller - A writeable C(/var/log/ansible/hosts) directory by the user executing Ansible on the controller
options: options:
log_folder: log_folder:
default: /var/log/ansible/hosts default: /var/log/ansible/hosts

View file

@ -12,14 +12,14 @@ DOCUMENTATION = '''
type: notification type: notification
short_description: Sends playbook logs to LogDNA short_description: Sends playbook logs to LogDNA
description: description:
- This callback will report logs from playbook actions, tasks, and events to LogDNA (https://app.logdna.com) - This callback will report logs from playbook actions, tasks, and events to LogDNA (U(https://app.logdna.com)).
requirements: requirements:
- LogDNA Python Library (https://github.com/logdna/python) - LogDNA Python Library (U(https://github.com/logdna/python))
- whitelisting in configuration - whitelisting in configuration
options: options:
conf_key: conf_key:
required: true required: true
description: LogDNA Ingestion Key description: LogDNA Ingestion Key.
type: string type: string
env: env:
- name: LOGDNA_INGESTION_KEY - name: LOGDNA_INGESTION_KEY
@ -28,7 +28,7 @@ DOCUMENTATION = '''
key: conf_key key: conf_key
plugin_ignore_errors: plugin_ignore_errors:
required: false required: false
description: Whether to ignore errors on failing or not description: Whether to ignore errors on failing or not.
type: boolean type: boolean
env: env:
- name: ANSIBLE_IGNORE_ERRORS - name: ANSIBLE_IGNORE_ERRORS
@ -38,7 +38,7 @@ DOCUMENTATION = '''
default: false default: false
conf_hostname: conf_hostname:
required: false required: false
description: Alternative Host Name; the current host name by default description: Alternative Host Name; the current host name by default.
type: string type: string
env: env:
- name: LOGDNA_HOSTNAME - name: LOGDNA_HOSTNAME
@ -47,7 +47,7 @@ DOCUMENTATION = '''
key: conf_hostname key: conf_hostname
conf_tags: conf_tags:
required: false required: false
description: Tags description: Tags.
type: string type: string
env: env:
- name: LOGDNA_TAGS - name: LOGDNA_TAGS

View file

@ -13,15 +13,15 @@ DOCUMENTATION = '''
short_description: Sends events to Logentries short_description: Sends events to Logentries
description: description:
- This callback plugin will generate JSON objects and send them to Logentries via TCP for auditing/debugging purposes. - 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 logentries.ini - 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. - In 2.4 and above you can just put it in the main Ansible configuration file.
requirements: requirements:
- whitelisting in configuration - whitelisting in configuration
- certifi (python library) - certifi (Python library)
- flatdict (python library), if you want to use the 'flatten' option - flatdict (Python library), if you want to use the 'flatten' option
options: options:
api: api:
description: URI to the Logentries API description: URI to the Logentries API.
env: env:
- name: LOGENTRIES_API - name: LOGENTRIES_API
default: data.logentries.com default: data.logentries.com
@ -29,7 +29,7 @@ DOCUMENTATION = '''
- section: callback_logentries - section: callback_logentries
key: api key: api
port: port:
description: HTTP port to use when connecting to the API description: HTTP port to use when connecting to the API.
env: env:
- name: LOGENTRIES_PORT - name: LOGENTRIES_PORT
default: 80 default: 80
@ -37,7 +37,7 @@ DOCUMENTATION = '''
- section: callback_logentries - section: callback_logentries
key: port key: port
tls_port: tls_port:
description: Port to use when connecting to the API when TLS is enabled description: Port to use when connecting to the API when TLS is enabled.
env: env:
- name: LOGENTRIES_TLS_PORT - name: LOGENTRIES_TLS_PORT
default: 443 default: 443
@ -45,7 +45,7 @@ DOCUMENTATION = '''
- section: callback_logentries - section: callback_logentries
key: tls_port key: tls_port
token: token:
description: The logentries "TCP token" description: The logentries C(TCP token).
env: env:
- name: LOGENTRIES_ANSIBLE_TOKEN - name: LOGENTRIES_ANSIBLE_TOKEN
required: true required: true
@ -54,7 +54,7 @@ DOCUMENTATION = '''
key: token key: token
use_tls: use_tls:
description: description:
- Toggle to decide whether to use TLS to encrypt the communications with the API server - Toggle to decide whether to use TLS to encrypt the communications with the API server.
env: env:
- name: LOGENTRIES_USE_TLS - name: LOGENTRIES_USE_TLS
default: false default: false
@ -63,7 +63,7 @@ DOCUMENTATION = '''
- section: callback_logentries - section: callback_logentries
key: use_tls key: use_tls
flatten: flatten:
description: flatten complex data structures into a single dictionary with complex keys description: Flatten complex data structures into a single dictionary with complex keys.
type: boolean type: boolean
default: false default: false
env: env:

View file

@ -13,13 +13,13 @@ DOCUMENTATION = r'''
type: notification type: notification
short_description: Sends events to Logstash short_description: Sends events to Logstash
description: description:
- This callback will report facts and task events to Logstash https://www.elastic.co/products/logstash - This callback will report facts and task events to Logstash U(https://www.elastic.co/products/logstash).
requirements: requirements:
- whitelisting in configuration - whitelisting in configuration
- logstash (python library) - logstash (Python library)
options: options:
server: server:
description: Address of the Logstash server description: Address of the Logstash server.
env: env:
- name: LOGSTASH_SERVER - name: LOGSTASH_SERVER
ini: ini:
@ -28,7 +28,7 @@ DOCUMENTATION = r'''
version_added: 1.0.0 version_added: 1.0.0
default: localhost default: localhost
port: port:
description: Port on which logstash is listening description: Port on which logstash is listening.
env: env:
- name: LOGSTASH_PORT - name: LOGSTASH_PORT
ini: ini:
@ -37,7 +37,7 @@ DOCUMENTATION = r'''
version_added: 1.0.0 version_added: 1.0.0
default: 5000 default: 5000
type: type:
description: Message type description: Message type.
env: env:
- name: LOGSTASH_TYPE - name: LOGSTASH_TYPE
ini: ini:
@ -54,7 +54,7 @@ DOCUMENTATION = r'''
env: env:
- name: LOGSTASH_PRE_COMMAND - name: LOGSTASH_PRE_COMMAND
format_version: format_version:
description: Logging format description: Logging format.
type: str type: str
version_added: 2.0.0 version_added: 2.0.0
ini: ini:

View file

@ -15,7 +15,7 @@ DOCUMENTATION = '''
- set as main display callback - set as main display callback
short_description: Don't display stuff to screen short_description: Don't display stuff to screen
description: description:
- This callback prevents outputing events to screen - This callback prevents outputing events to screen.
''' '''
from ansible.plugins.callback import CallbackBase from ansible.plugins.callback import CallbackBase

View file

@ -14,12 +14,12 @@ DOCUMENTATION = '''
type: notification type: notification
requirements: requirements:
- whitelisting in configuration - whitelisting in configuration
- the '/usr/bin/say' command line program (standard on macOS) or 'espeak' command line program - the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program
short_description: notify using software speech synthesizer short_description: notify using software speech synthesizer
description: description:
- This plugin will use the 'say' or 'espeak' program to "speak" about play events. - This plugin will use the C(say) or C(espeak) program to "speak" about play events.
notes: notes:
- In 2.8, this callback has been renamed from C(osx_say) into M(community.general.say). - In Ansible 2.8, this callback has been renamed from C(osx_say) into M(community.general.say).
''' '''
import platform import platform

View file

@ -22,7 +22,7 @@ DOCUMENTATION = '''
options: options:
nocolor: nocolor:
default: false default: false
description: This setting allows suppressing colorizing output description: This setting allows suppressing colorizing output.
env: env:
- name: ANSIBLE_NOCOLOR - name: ANSIBLE_NOCOLOR
- name: ANSIBLE_SELECTIVE_DONT_COLORIZE - name: ANSIBLE_SELECTIVE_DONT_COLORIZE

View file

@ -18,11 +18,11 @@ DOCUMENTATION = '''
short_description: Sends play events to a Slack channel short_description: Sends play events to a Slack channel
description: description:
- This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution. - This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution.
- Before 2.4 only environment variables were available for configuring this plugin - Before Ansible 2.4 only environment variables were available for configuring this plugin.
options: options:
webhook_url: webhook_url:
required: true required: true
description: Slack Webhook URL description: Slack Webhook URL.
env: env:
- name: SLACK_WEBHOOK_URL - name: SLACK_WEBHOOK_URL
ini: ini:
@ -45,7 +45,7 @@ DOCUMENTATION = '''
- section: callback_slack - section: callback_slack
key: username key: username
validate_certs: validate_certs:
description: validate the SSL certificate of the Slack server. (For HTTPS URLs) description: Validate the SSL certificate of the Slack server for HTTPS URLs.
env: env:
- name: SLACK_VALIDATE_CERTS - name: SLACK_VALIDATE_CERTS
ini: ini:

View file

@ -13,22 +13,22 @@ DOCUMENTATION = '''
author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>" author: "Stuart Hirst (!UNKNOWN) <support@convergingdata.com>"
description: description:
- This callback plugin will send task results as JSON formatted events to a Splunk HTTP collector. - 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 "https://splunkbase.splunk.com/app/4023/" - 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. - Credit to "Ryan Currah (@ryancurrah)" for original source upon which this is based.
requirements: requirements:
- Whitelisting this callback plugin - Whitelisting this callback plugin
- 'Create a HTTP Event Collector in Splunk' - 'Create a HTTP Event Collector in Splunk'
- 'Define the url and token in ansible.cfg' - 'Define the URL and token in C(ansible.cfg)'
options: options:
url: url:
description: URL to the Splunk HTTP collector source description: URL to the Splunk HTTP collector source.
env: env:
- name: SPLUNK_URL - name: SPLUNK_URL
ini: ini:
- section: callback_splunk - section: callback_splunk
key: url key: url
authtoken: authtoken:
description: Token to authenticate the connection to the Splunk HTTP collector description: Token to authenticate the connection to the Splunk HTTP collector.
env: env:
- name: SPLUNK_AUTHTOKEN - name: SPLUNK_AUTHTOKEN
ini: ini:
@ -48,7 +48,7 @@ DOCUMENTATION = '''
version_added: '1.0.0' version_added: '1.0.0'
include_milliseconds: include_milliseconds:
description: Whether to include milliseconds as part of the generated timestamp field in the event description: Whether to include milliseconds as part of the generated timestamp field in the event
sent to the Splunk HTTP collector sent to the Splunk HTTP collector.
env: env:
- name: SPLUNK_INCLUDE_MILLISECONDS - name: SPLUNK_INCLUDE_MILLISECONDS
ini: ini:

View file

@ -12,14 +12,14 @@ type: notification
short_description: Sends task result events to Sumologic short_description: Sends task result events to Sumologic
author: "Ryan Currah (@ryancurrah)" author: "Ryan Currah (@ryancurrah)"
description: description:
- This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source - This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source.
requirements: requirements:
- Whitelisting this callback plugin - Whitelisting this callback plugin
- 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of C(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of C(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator
of C("timestamp": "(.*)")' of C("timestamp": "(.*)")'
options: options:
url: url:
description: URL to the Sumologic HTTP collector source description: URL to the Sumologic HTTP collector source.
env: env:
- name: SUMOLOGIC_URL - name: SUMOLOGIC_URL
ini: ini:
@ -28,7 +28,7 @@ options:
''' '''
EXAMPLES = ''' EXAMPLES = '''
examples: > examples: |
To enable, add this to your ansible.cfg file in the defaults block To enable, add this to your ansible.cfg file in the defaults block
[defaults] [defaults]
callback_whitelist = community.general.sumologic callback_whitelist = community.general.sumologic

View file

@ -15,11 +15,11 @@ DOCUMENTATION = '''
- whitelist in configuration - whitelist in configuration
short_description: sends JSON events to syslog short_description: sends JSON events to syslog
description: description:
- This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format.
- Before Ansible 2.9 only environment variables were available for configuration - Before Ansible 2.9 only environment variables were available for configuration.
options: options:
server: server:
description: syslog server that will receive the event description: Syslog server that will receive the event.
env: env:
- name: SYSLOG_SERVER - name: SYSLOG_SERVER
default: localhost default: localhost
@ -27,7 +27,7 @@ DOCUMENTATION = '''
- section: callback_syslog_json - section: callback_syslog_json
key: syslog_server key: syslog_server
port: port:
description: port on which the syslog server is listening description: Port on which the syslog server is listening.
env: env:
- name: SYSLOG_PORT - name: SYSLOG_PORT
default: 514 default: 514
@ -35,7 +35,7 @@ DOCUMENTATION = '''
- section: callback_syslog_json - section: callback_syslog_json
key: syslog_port key: syslog_port
facility: facility:
description: syslog facility to log as description: Syslog facility to log as.
env: env:
- name: SYSLOG_FACILITY - name: SYSLOG_FACILITY
default: user default: user

View file

@ -11,7 +11,7 @@ DOCUMENTATION = '''
author: Unknown (!UNKNOWN) author: Unknown (!UNKNOWN)
name: yaml name: yaml
type: stdout type: stdout
short_description: yaml-ized Ansible screen output short_description: YAML-ized Ansible screen output
description: description:
- Ansible output that can be quite a bit easier to read than the - Ansible output that can be quite a bit easier to read than the
default JSON formatting. default JSON formatting.