Browse Source

Convert README to reStructuredText

* Add PyPI validation check for README.rst [1]
* Add docutils to test-requirements.txt
* Add lower bound for jira

[1] https://docs.openstack.org/project-team-guide/project-setup/python.html#running-the-style-checks

Change-Id: I5d90ccb1b919c4bab66b468a8ddb714ffc5f1635
Story: 2001980
Task: 20013
Witold Bedyk 10 months ago
parent
commit
20d6557744
6 changed files with 144 additions and 111 deletions
  1. 0
    109
      README.md
  2. 139
    0
      README.rst
  3. 1
    0
      lower-constraints.txt
  4. 2
    2
      setup.cfg
  5. 1
    0
      test-requirements.txt
  6. 1
    0
      tox.ini

+ 0
- 109
README.md View File

@@ -1,109 +0,0 @@
1
-Team and repository tags
2
-========================
3
-
4
-[![Team and repository tags](https://governance.openstack.org/tc/badges/monasca-notification.svg)](https://governance.openstack.org/tc/reference/tags/index.html)
5
-
6
-<!-- Change things from this point on -->
7
-
8
-# Notification Engine
9
-
10
-This engine reads alarms from Kafka and then notifies the customer using their configured notification method.
11
-Multiple notification and retry engines can run in parallel up to one per available Kafka partition.  Zookeeper
12
-is used to negotiate access to the Kafka partitions whenever a new process joins or leaves the working set.
13
-
14
-# Architecture
15
-The notification engine generates notifications using the following steps:
16
-1. Reads Alarms from Kafka, with no auto commit. - KafkaConsumer class
17
-2. Determine notification type for an alarm. Done by reading from mysql. - AlarmProcessor class
18
-3. Send Notification. - NotificationProcessor class
19
-4. Successful notifications are added to a sent notification topic. - NotificationEngine class
20
-5. Failed notifications are added to a retry topic. - NotificationEngine class
21
-6. Commit offset to Kafka - KafkaConsumer class
22
-
23
-The notification engine uses three Kafka topics:
24
-1. alarm_topic: Alarms inbound to the notification engine.
25
-2. notification_topic: Successfully sent notifications.
26
-3. notification_retry_topic: Unsuccessful notifications.
27
-
28
-A retry engine runs in parallel with the notification engine and gives any
29
-failed notification a configurable number of extra chances at succeess.
30
-
31
-The retry engine generates notifications using the following steps:
32
-1. Reads Notification json data from Kafka, with no auto commit. - KafkaConsumer class
33
-2. Rebuild the notification that failed. - RetryEngine class
34
-3. Send Notification. - NotificationProcessor class
35
-4. Successful notifictions are added to a sent notification topic. - RetryEngine class
36
-5. Failed notifications that have not hit the retry limit are added back to the retry topic. - RetryEngine class
37
-6. Failed notifications that have hit the retry limit are discarded. - RetryEngine class
38
-6. Commit offset to Kafka - KafkaConsumer class
39
-
40
-The retry engine uses two Kafka topics:
41
-1. notification_retry_topic: Notifications that need to be retried.
42
-2. notification_topic: Successfully sent notifications.
43
-
44
-## Fault Tolerance
45
-When reading from the alarm topic no committing is done. The committing is done only after processing. This allows
46
-the processing to continue even though some notifications can be slow. In the event of a catastrophic failure some
47
-notifications could be sent but the alarms not yet acknowledged. This is an acceptable failure mode, better to send a
48
-notification twice than not at all.
49
-
50
-The general process when a major error is encountered is to exit the daemon which should allow the other processes to
51
-renegotiate access to the Kafka partitions.  It is also assumed the notification engine will be run by a process
52
-supervisor which will restart it in case of a failure. This way any errors which are not easy to recover from are
53
-automatically handled by the service restarting and the active daemon switching to another instance.
54
-
55
-Though this should cover all errors there is risk that an alarm or set of alarms can be processed and notifications
56
-sent out multiple times. To minimize this risk a number of techniques are used:
57
-
58
-- Timeouts are implemented with all notification types.
59
-- An alarm TTL is utilized. Any alarm older than the TTL is not processed.
60
-
61
-# Operation
62
-Yaml config file by default is in '/etc/monasca/notification.yaml', a sample is in this project.
63
-
64
-## Monitoring
65
-statsd is incorporated into the daemon and will send all stats to statsd server launched by monasca-agent.
66
-Default host and port points at **localhost:8125**.
67
-
68
-- Counters
69
-    - ConsumedFromKafka
70
-    - AlarmsFailedParse
71
-    - AlarmsNoNotification
72
-    - NotificationsCreated
73
-    - NotificationsSentSMTP
74
-    - NotificationsSentWebhook
75
-    - NotificationsSentPagerduty
76
-    - NotificationsSentFailed
77
-    - NotificationsInvalidType
78
-    - AlarmsFinished
79
-    - PublishedToKafka
80
-- Timers
81
-    - ConfigDBTime
82
-    - SendNotificationTime
83
-
84
-# Future Considerations
85
-- More extensive load testing is needed
86
-  - How fast is the mysql db? How much load do we put on it. Initially I think it makes most sense to read notification
87
-    details for each alarm but eventually I may want to cache that info.
88
-  - How expensive are commits to Kafka for every message we read?  Should we commit every N messages?
89
-  - How efficient is the default Kafka consumer batch size?
90
-  - Currently we can get ~200 notifications per second per NotificationEngine instance using webhooks to a local 
91
-    http server.  Is that fast enough?
92
-  - Are we putting too much load on Kafka at ~200 commits per second?
93
-
94
-# License
95
-
96
-Copyright (c) 2014 Hewlett-Packard Development Company, L.P.
97
-
98
-Licensed under the Apache License, Version 2.0 (the "License");
99
-you may not use this file except in compliance with the License.
100
-You may obtain a copy of the License at
101
-
102
-    http://www.apache.org/licenses/LICENSE-2.0
103
-
104
-Unless required by applicable law or agreed to in writing, software
105
-distributed under the License is distributed on an "AS IS" BASIS,
106
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
107
-implied.
108
-See the License for the specific language governing permissions and
109
-limitations under the License.

+ 139
- 0
README.rst View File

@@ -0,0 +1,139 @@
1
+Team and repository tags
2
+========================
3
+
4
+|Team and repository tags|
5
+
6
+.. raw:: html
7
+
8
+   <!-- Change things from this point on -->
9
+
10
+Notification Engine
11
+===================
12
+
13
+This engine reads alarms from Kafka and then notifies the customer using
14
+the configured notification method. Multiple notification and retry
15
+engines can run in parallel, up to one per available Kafka partition.
16
+Zookeeper is used to negotiate access to the Kafka partitions whenever a
17
+new process joins or leaves the working set.
18
+
19
+Architecture
20
+============
21
+
22
+The notification engine generates notifications using the following
23
+steps:
24
+
25
+1. Read Alarms from Kafka, with no auto commit. -
26
+   monasca\_common.kafka.KafkaConsumer class
27
+2. Determine notification type for an alarm. Done by reading from mysql. - AlarmProcessor class
28
+3. Send notification. - NotificationProcessor class
29
+4. Add successful notifications to a sent notification topic. - NotificationEngine class
30
+5. Add failed notifications to a retry topic. - NotificationEngine class
31
+6. Commit offset to Kafka - KafkaConsumer class
32
+
33
+The notification engine uses three Kafka topics:
34
+
35
+1. alarm\_topic: Alarms inbound to the notification engine.
36
+2. notification\_topic: Successfully sent notifications.
37
+3. notification\_retry\_topic: Failed notifications.
38
+
39
+A retry engine runs in parallel with the notification engine and gives
40
+any failed notification a configurable number of extra chances at
41
+success.
42
+
43
+The retry engine generates notifications using the following steps:
44
+
45
+1. Read notification json data from Kafka, with no auto commit. - KafkaConsumer class
46
+2. Rebuild the notification that failed. - RetryEngine class
47
+3. Send notification. - NotificationProcessor class
48
+4. Add successful notifications to a sent notification topic. - RetryEngine class
49
+5. Add failed notifications that have not hit the retry limit back to the retry topic. -
50
+   RetryEngine class
51
+6. Discard failed notifications that have hit the retry limit. - RetryEngine class
52
+7. Commit offset to Kafka. - KafkaConsumer class
53
+
54
+The retry engine uses two Kafka topics:
55
+
56
+1. notification\_retry\_topic: Notifications that need to be retried.
57
+2. notification\_topic: Successfully sent notifications.
58
+
59
+Fault Tolerance
60
+---------------
61
+
62
+When reading from the alarm topic, no committing is done. The committing
63
+is done only after processing. This allows the processing to continue
64
+even though some notifications can be slow. In the event of a
65
+catastrophic failure some notifications could be sent but the alarms
66
+have not yet been acknowledged. This is an acceptable failure mode,
67
+better to send a notification twice than not at all.
68
+
69
+The general process when a major error is encountered is to exit the
70
+daemon which should allow the other processes to renegotiate access to
71
+the Kafka partitions. It is also assumed that the notification engine
72
+will be run by a process supervisor which will restart it in case of a
73
+failure. In this way, any errors which are not easy to recover from are
74
+automatically handled by the service restarting and the active daemon
75
+switching to another instance.
76
+
77
+Though this should cover all errors, there is the risk that an alarm or
78
+a set of alarms can be processed and notifications are sent out multiple
79
+times. To minimize this risk a number of techniques are used:
80
+
81
+-  Timeouts are implemented for all notification types.
82
+-  An alarm TTL is utilized. Any alarm older than the TTL is not
83
+   processed.
84
+
85
+Operation
86
+=========
87
+
88
+``oslo.config`` is used for handling configuration options. A sample
89
+configuration file ``etc/monasca/notification.conf.sample`` can be
90
+generated by running:
91
+
92
+::
93
+
94
+    tox -e genconfig
95
+
96
+Monitoring
97
+----------
98
+
99
+StatsD is incorporated into the daemon and will send all stats to the
100
+StatsD server launched by monasca-agent. Default host and port points to
101
+**localhost:8125**.
102
+
103
+-  Counters
104
+
105
+   -  ConsumedFromKafka
106
+   -  AlarmsFailedParse
107
+   -  AlarmsNoNotification
108
+   -  NotificationsCreated
109
+   -  NotificationsSentSMTP
110
+   -  NotificationsSentWebhook
111
+   -  NotificationsSentPagerduty
112
+   -  NotificationsSentFailed
113
+   -  NotificationsInvalidType
114
+   -  AlarmsFinished
115
+   -  PublishedToKafka
116
+
117
+-  Timers
118
+
119
+   -  ConfigDBTime
120
+   -  SendNotificationTime
121
+
122
+Future Considerations
123
+=====================
124
+
125
+- More extensive load testing is needed:
126
+
127
+   - How fast is the mysql db? How much load do we put on it. Initially I
128
+     think it makes most sense to read notification details for each alarm
129
+     but eventually I may want to cache that info.
130
+   - How expensive are commits to Kafka for every message we read? Should
131
+     we commit every N messages?
132
+   - How efficient is the default Kafka consumer batch size?
133
+   - Currently we can get ~200 notifications per second per
134
+     NotificationEngine instance using webhooks to a local http server. Is
135
+     that fast enough?
136
+   - Are we putting too much load on Kafka at ~200 commits per second?
137
+
138
+.. |Team and repository tags| image:: https://governance.openstack.org/tc/badges/monasca-notification.svg
139
+   :target: https://governance.openstack.org/tc/reference/tags/index.html

+ 1
- 0
lower-constraints.txt View File

@@ -4,6 +4,7 @@ bandit==1.4.0
4 4
 configparser==3.5.0
5 5
 coverage==4.0
6 6
 debtcollector==1.2.0
7
+docutils==0.11
7 8
 extras==1.0.0
8 9
 fixtures==3.0.0
9 10
 flake8==2.5.5

+ 2
- 2
setup.cfg View File

@@ -8,7 +8,7 @@ classifier=
8 8
   License :: OSI Approved :: Apache Software License
9 9
   Topic :: System :: Monitoring
10 10
 keywords = openstack monitoring email
11
-description-file = README.md
11
+description-file = README.rst
12 12
 home-page = https://github.com/stackforge/monasca-notification
13 13
 license = Apache
14 14
 
@@ -35,5 +35,5 @@ universal = 1
35 35
 
36 36
 [extras]
37 37
 jira_plugin =
38
-  jira
38
+  jira>=1.0.3
39 39
   Jinja2>=2.10 # BSD License (3 clause)

+ 1
- 0
test-requirements.txt View File

@@ -15,3 +15,4 @@ testrepository>=0.0.18 # Apache-2.0/BSD
15 15
 SQLAlchemy!=1.1.5,!=1.1.6,!=1.1.7,!=1.1.8,>=1.0.10 # MIT
16 16
 PyMySQL>=0.7.6 # MIT License
17 17
 psycopg2>=2.6.2 # LGPL/ZPL
18
+docutils>=0.11 # OSI-Approved Open Source, Public Domain

+ 1
- 0
tox.ini View File

@@ -43,6 +43,7 @@ basepython = python3
43 43
 commands =
44 44
   {[testenv:flake8]commands}
45 45
   {[testenv:bandit]commands}
46
+  python setup.py check --restructuredtext --strict
46 47
 
47 48
 [testenv:venv]
48 49
 basepython = python3

Loading…
Cancel
Save