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

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

Browse source 
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
Show stats Download patch file Download diff file Expand all files Collapse all files

12
plugins/callback/cgroup_memory_recap.py
View file

@ -16,15 +16,15 @@ DOCUMENTATION = '''
- 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
- 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)
- 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:
max_mem_file:
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:
- name: CGROUP_MAX_MEM_FILE
ini:
@ -32,7 +32,7 @@ DOCUMENTATION = '''
key: max_mem_file
cur_mem_file:
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:
- name: CGROUP_CUR_MEM_FILE
ini:

4
plugins/callback/context_demo.py
View file

@ -13,8 +13,8 @@ DOCUMENTATION = '''
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
- Displays some play and task context along with normal output.
- This is mostly for demo purposes.
requirements:
- whitelist in configuration
'''

2
plugins/callback/counter_enabled.py
View file

@ -21,7 +21,7 @@ DOCUMENTATION = '''
extends_documentation_fragment:
- default_callback
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

2
plugins/callback/dense.py
View file

@ -14,7 +14,7 @@ short_description: minimal stdout output
extends_documentation_fragment:
- 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)
requirements:

4
plugins/callback/jabber.py
View file

@ -13,10 +13,10 @@ DOCUMENTATION = '''
type: notification
short_description: post task events to a jabber server
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.
requirements:
- xmpp (python lib https://github.com/ArchipelProject/xmpppy)
- xmpp (Python library U(https://github.com/ArchipelProject/xmpppy))
options:
server:
description: connection info to jabber server

4
plugins/callback/log_plays.py
View file

@ -13,10 +13,10 @@ DOCUMENTATION = '''
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
- This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory.
requirements:
- 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:
log_folder:
default: /var/log/ansible/hosts

12
plugins/callback/logdna.py
View file

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

18
plugins/callback/logentries.py
View file

@ -13,15 +13,15 @@ DOCUMENTATION = '''
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 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.
requirements:
- whitelisting in configuration
- certifi (python library)
- flatdict (python library), if you want to use the 'flatten' option
- certifi (Python library)
- flatdict (Python library), if you want to use the 'flatten' option
options:
api:
description: URI to the Logentries API
description: URI to the Logentries API.
env:
- name: LOGENTRIES_API
default: data.logentries.com
@ -29,7 +29,7 @@ DOCUMENTATION = '''
- section: callback_logentries
key: api
port:
description: HTTP port to use when connecting to the API
description: HTTP port to use when connecting to the API.
env:
- name: LOGENTRIES_PORT
default: 80
@ -37,7 +37,7 @@ DOCUMENTATION = '''
- section: callback_logentries
key: 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:
- name: LOGENTRIES_TLS_PORT
default: 443
@ -45,7 +45,7 @@ DOCUMENTATION = '''
- section: callback_logentries
key: tls_port
token:
description: The logentries "TCP token"
description: The logentries C(TCP token).
env:
- name: LOGENTRIES_ANSIBLE_TOKEN
required: true
@ -54,7 +54,7 @@ DOCUMENTATION = '''
key: token
use_tls:
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:
- name: LOGENTRIES_USE_TLS
default: false
@ -63,7 +63,7 @@ DOCUMENTATION = '''
- section: callback_logentries
key: use_tls
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
default: false
env:

12
plugins/callback/logstash.py
View file

@ -13,13 +13,13 @@ DOCUMENTATION = r'''
type: notification
short_description: Sends events to Logstash
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:
- whitelisting in configuration
- logstash (python library)
- logstash (Python library)
options:
server:
description: Address of the Logstash server
description: Address of the Logstash server.
env:
- name: LOGSTASH_SERVER
ini:
@ -28,7 +28,7 @@ DOCUMENTATION = r'''
version_added: 1.0.0
default: localhost
port:
description: Port on which logstash is listening
description: Port on which logstash is listening.
env:
- name: LOGSTASH_PORT
ini:
@ -37,7 +37,7 @@ DOCUMENTATION = r'''
version_added: 1.0.0
default: 5000
type:
description: Message type
description: Message type.
env:
- name: LOGSTASH_TYPE
ini:
@ -54,7 +54,7 @@ DOCUMENTATION = r'''
env:
- name: LOGSTASH_PRE_COMMAND
format_version:
description: Logging format
description: Logging format.
type: str
version_added: 2.0.0
ini:

2
plugins/callback/null.py
View file

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

6
plugins/callback/say.py
View file

@ -14,12 +14,12 @@ DOCUMENTATION = '''
type: notification
requirements:
- 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
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:
- 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

2
plugins/callback/selective.py
View file

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

6
plugins/callback/slack.py
View file

@ -18,11 +18,11 @@ DOCUMENTATION = '''
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.
- 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:
webhook_url:
required: true
description: Slack Webhook URL
description: Slack Webhook URL.
env:
- name: SLACK_WEBHOOK_URL
ini:
@ -45,7 +45,7 @@ DOCUMENTATION = '''
- section: callback_slack
key: username
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:
- name: SLACK_VALIDATE_CERTS
ini:

10
plugins/callback/splunk.py
View file

@ -13,22 +13,22 @@ DOCUMENTATION = '''
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 "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.
requirements:
- Whitelisting this callback plugin
- '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:
url:
description: URL to the Splunk HTTP collector source
description: URL to the Splunk HTTP collector source.
env:
- name: SPLUNK_URL
ini:
- section: callback_splunk
key: url
authtoken:
description: Token to authenticate the connection to the Splunk HTTP collector
description: Token to authenticate the connection to the Splunk HTTP collector.
env:
- name: SPLUNK_AUTHTOKEN
ini:
@ -48,7 +48,7 @@ DOCUMENTATION = '''
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
sent to the Splunk HTTP collector.
env:
- name: SPLUNK_INCLUDE_MILLISECONDS
ini:

6
plugins/callback/sumologic.py
View file

@ -12,14 +12,14 @@ type: notification
short_description: Sends task result events to Sumologic
author: "Ryan Currah (@ryancurrah)"
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:
- 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
of C("timestamp": "(.*)")'
options:
url:
description: URL to the Sumologic HTTP collector source
description: URL to the Sumologic HTTP collector source.
env:
- name: SUMOLOGIC_URL
ini:
@ -28,7 +28,7 @@ options:
'''
EXAMPLES = '''
examples: >
examples: |
To enable, add this to your ansible.cfg file in the defaults block
[defaults]
callback_whitelist = community.general.sumologic

10
plugins/callback/syslog_json.py
View file

@ -15,11 +15,11 @@ DOCUMENTATION = '''
- whitelist in configuration
short_description: sends JSON events to syslog
description:
- 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
- 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.
options:
server:
description: syslog server that will receive the event
description: Syslog server that will receive the event.
env:
- name: SYSLOG_SERVER
default: localhost
@ -27,7 +27,7 @@ DOCUMENTATION = '''
- section: callback_syslog_json
key: syslog_server
port:
description: port on which the syslog server is listening
description: Port on which the syslog server is listening.
env:
- name: SYSLOG_PORT
default: 514
@ -35,7 +35,7 @@ DOCUMENTATION = '''
- section: callback_syslog_json
key: syslog_port
facility:
description: syslog facility to log as
description: Syslog facility to log as.
env:
- name: SYSLOG_FACILITY
default: user

2
plugins/callback/yaml.py
View file

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