From a3f91274b371dc2a80600decb36946d5b4612d1d Mon Sep 17 00:00:00 2001 From: Pilou Date: Tue, 15 Aug 2017 03:40:00 +0200 Subject: [PATCH] circonus_annotation: DOCUMENTATION & argument_spec cleaning (#26832) * circonus_annotation: clean description - add 'default' field - default value for 'required' field is false - use formatting function * circonus_annotation: clean argument_spec remove useless conversion default of 'required' False use 'default' when possible * circonus_annotation: fix pep8 * circonus_annotation: add RETURN block * circonus_annotation: check_mode isn't supported, add a note --- .../modules/monitoring/circonus_annotation.py | 99 +++++++++++++++---- test/sanity/pep8/legacy-files.txt | 1 - 2 files changed, 79 insertions(+), 21 deletions(-) diff --git a/lib/ansible/modules/monitoring/circonus_annotation.py b/lib/ansible/modules/monitoring/circonus_annotation.py index fa745992eb..9375bbb020 100644 --- a/lib/ansible/modules/monitoring/circonus_annotation.py +++ b/lib/ansible/modules/monitoring/circonus_annotation.py @@ -25,6 +25,8 @@ requirements: - urllib3 - requests - time +notes: + - Check mode isn’t supported. options: api_key: description: @@ -44,16 +46,16 @@ options: required: true start: description: - - Unix timestamp of event start, defaults to now - required: false + - Unix timestamp of event start + default: I(now) stop: description: - - Unix timestamp of event end, defaults to now + duration - required: false + - Unix timestamp of event end + default: I(now) + I(duration) duration: description: - - Duration in seconds of annotation, defaults to 0 - required: false + - Duration in seconds of annotation + default: 0 ''' EXAMPLES = ''' # Create a simple annotation event with a source, defaults to start and end time of now @@ -78,6 +80,65 @@ EXAMPLES = ''' start_time: 1395940006 end_time: 1395954407 ''' + +RETURN = ''' +annotation: + description: details about the created annotation + returned: success + type: complex + contains: + _cid: + description: annotation identifier + returned: success + type: string + sample: /annotation/100000 + _created: + description: creation timestamp + returned: success + type: int + sample: 1502236928 + _last_modified: + description: last modification timestamp + returned: success + type: int + sample: 1502236928 + _last_modified_by: + description: last modified by + returned: success + type: string + sample: /user/1000 + category: + description: category of the created annotation + returned: success + type: string + sample: alerts + title: + description: title of the created annotation + returned: success + type: string + sample: WARNING + description: + description: description of the created annotation + returned: success + type: string + sample: Host is down. + start: + description: timestamp, since annotation applies + returned: success + type: int + sample: Host is down. + stop: + description: timestamp, since annotation ends + returned: success + type: string + sample: Host is down. + rel_metrics: + description: Array of metrics related to this annotation, each metrics is a string. + returned: success + type: list + sample: + - 54321_kbps +''' import json import time import traceback @@ -93,7 +154,7 @@ def post_annotation(annotation, api_key): base_url = 'https://api.circonus.com/v2' anootate_post_endpoint = '/annotation' resp = requests.post(base_url + anootate_post_endpoint, - headers=build_headers(api_key), data=json.dumps(annotation)) + headers=build_headers(api_key), data=json.dumps(annotation)) resp.raise_for_status() return resp @@ -101,10 +162,7 @@ def post_annotation(annotation, api_key): def create_annotation(module): ''' Takes ansible module object ''' annotation = {} - if module.params['duration'] is not None: - duration = module.params['duration'] - else: - duration = 0 + duration = module.params['duration'] if module.params['start'] is not None: start = module.params['start'] else: @@ -112,9 +170,9 @@ def create_annotation(module): if module.params['stop'] is not None: stop = module.params['stop'] else: - stop = int(time.time())+ duration - annotation['start'] = int(start) - annotation['stop'] = int(stop) + stop = int(time.time()) + duration + annotation['start'] = start + annotation['stop'] = stop annotation['category'] = module.params['category'] annotation['description'] = module.params['description'] annotation['title'] = module.params['title'] @@ -124,8 +182,8 @@ def create_annotation(module): def build_headers(api_token): '''Takes api token, returns headers with it included.''' headers = {'X-Circonus-App-Name': 'ansible', - 'Host': 'api.circonus.com', 'X-Circonus-Auth-Token': api_token, - 'Accept': 'application/json'} + 'Host': 'api.circonus.com', 'X-Circonus-Auth-Token': api_token, + 'Accept': 'application/json'} return headers @@ -133,15 +191,16 @@ def main(): '''Main function, dispatches logic''' module = AnsibleModule( argument_spec=dict( - start=dict(required=False, type='int'), - stop=dict(required=False, type='int'), + start=dict(type='int'), + stop=dict(type='int'), category=dict(required=True), title=dict(required=True), description=dict(required=True), - duration=dict(required=False, type='int'), + duration=dict(default=0, type='int'), api_key=dict(required=True, no_log=True) - ) ) + ) + annotation = create_annotation(module) try: resp = post_annotation(annotation, module.params['api_key']) diff --git a/test/sanity/pep8/legacy-files.txt b/test/sanity/pep8/legacy-files.txt index b54eeaba5e..8a0a374abe 100644 --- a/test/sanity/pep8/legacy-files.txt +++ b/test/sanity/pep8/legacy-files.txt @@ -218,7 +218,6 @@ lib/ansible/modules/files/tempfile.py lib/ansible/modules/files/xattr.py lib/ansible/modules/monitoring/bigpanda.py lib/ansible/modules/monitoring/boundary_meter.py -lib/ansible/modules/monitoring/circonus_annotation.py lib/ansible/modules/monitoring/datadog_event.py lib/ansible/modules/monitoring/icinga2_feature.py lib/ansible/modules/monitoring/librato_annotation.py