argus-api-client 0.7.0__tar.gz → 0.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/PKG-INFO +117 -16
  2. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/README.md +116 -15
  3. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/PKG-INFO +117 -16
  4. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/SOURCES.txt +5 -1
  5. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/__init__.py +2 -1
  6. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/api.py +13 -0
  7. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/async_api.py +8 -0
  8. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/async_client.py +69 -6
  9. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/client.py +68 -6
  10. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/models.py +15 -8
  11. argus_api_client-0.8.0/src/pyargus/multivaluedict.py +251 -0
  12. argus_api_client-0.8.0/src/pyargus/time.py +10 -0
  13. argus_api_client-0.8.0/tests/test_api.py +28 -0
  14. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/tests/test_async_api.py +6 -0
  15. argus_api_client-0.8.0/tests/test_async_client.py +110 -0
  16. argus_api_client-0.8.0/tests/test_client.py +99 -0
  17. argus_api_client-0.8.0/tests/test_models.py +62 -0
  18. argus_api_client-0.8.0/tests/test_multivaluedict.py +413 -0
  19. argus_api_client-0.7.0/tests/test_api.py +0 -14
  20. argus_api_client-0.7.0/tests/test_async_client.py +0 -35
  21. argus_api_client-0.7.0/tests/test_client.py +0 -31
  22. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/LICENSE +0 -0
  23. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/pyproject.toml +0 -0
  24. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/setup.cfg +0 -0
  25. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/dependency_links.txt +0 -0
  26. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/requires.txt +0 -0
  27. {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: argus-api-client
3
- Version: 0.7.0
3
+ Version: 0.8.0
4
4
  Summary: A Python API client library for the Argus alert aggregator server
5
5
  Author-email: Sikt - Kunnskapssektorens Tjenesteleverandør <kontakt@sikt.no>
6
6
  License-Expression: Apache-2.0
@@ -41,6 +41,8 @@ The `Client` class is found in `pyargus.client`, and the various supported data
41
41
  models, such as `Incident`, `Event`, `Acknowledgement` and `SourceSystem`, are
42
42
  implemented in `pyargus.models`.
43
43
 
44
+ **Note:** Always pass timezone-aware `datetime` objects (e.g. `datetime.now(tz=timezone.utc)`) to the client. pyargus serializes datetimes verbatim, so a naive value reaches Argus without a UTC offset and gets recorded at the wrong time.
45
+
44
46
  ### Listing open incidents that have not been acknowledged
45
47
 
46
48
  ```pycon
@@ -49,9 +51,9 @@ implemented in `pyargus.models`.
49
51
  >>> for incident in c.get_incidents(open=True, acked=False):
50
52
  ... print(incident)
51
53
  ...
52
- Incident(pk=4, start_time=datetime.datetime(2021, 4, 4, 16, 37, 43, 293726, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202430', details_url='http://localhost/search/event/202430', description='uninett-gsw2 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'room': '100', 'organization': 'uninett.srv', 'host': 'uninett-gsw2.uninett.no'}, stateful=True, open=True, acked=False)
53
- Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202429', details_url='http://localhost/search/event/202429', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'host': 'uninett-gsw1.uninett.no', 'room': '100', 'organization': 'uninett.srv'}, stateful=True, open=True, acked=False)
54
- Incident(pk=2, start_time=datetime.datetime(2017, 8, 31, 14, 58, 31, 118794, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='184296', details_url='http://localhost/search/event/184296', description='Link DOWN on Gi0/3 at oldsmobile.lab (Simple is better than complex)', level=5, ticket_url='', tags={'room': '113', 'location': 'Teknobyen Innovasjonssenter', 'organization': 'uninett.testlab', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'linkState', 'alert_type': 'linkDown', 'host': 'oldsmobile.lab.uninett.no', 'interface': 'Gi0/3'}, stateful=True, open=True, acked=False)
54
+ Incident(pk=4, start_time=datetime.datetime(2021, 4, 4, 16, 37, 43, 293726, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202430', details_url='http://localhost/search/event/202430', description='uninett-gsw2 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('room', '100'), ('organization', 'uninett.srv'), ('host', 'uninett-gsw2.uninett.no')]), stateful=True, open=True, acked=False)
55
+ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202429', details_url='http://localhost/search/event/202429', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('host', 'uninett-gsw1.uninett.no'), ('room', '100'), ('organization', 'uninett.srv')]), stateful=True, open=True, acked=False)
56
+ Incident(pk=2, start_time=datetime.datetime(2017, 8, 31, 14, 58, 31, 118794, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='184296', details_url='http://localhost/search/event/184296', description='Link DOWN on Gi0/3 at oldsmobile.lab (Simple is better than complex)', level=5, ticket_url='', tags=MultiValueDict([('room', '113'), ('location', 'Teknobyen Innovasjonssenter'), ('organization', 'uninett.testlab'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'linkState'), ('alert_type', 'linkDown'), ('host', 'oldsmobile.lab.uninett.no'), ('interface', 'Gi0/3')]), stateful=True, open=True, acked=False)
55
57
  ```
56
58
 
57
59
  As you can see, the arguments given to `get_incidents()` are translated
@@ -73,7 +75,7 @@ Example:
73
75
  >>> for incident in c.get_my_incidents(open=True, acked=False):
74
76
  ... print(incident)
75
77
  ...
76
- Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=3, name='foobar, type='nav', user=4, base_url='http://localhost/'), source_incident_id='2716057', details_url='http://localhost/search/event/2716057', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'host': 'uninett-gsw1.uninett.no', 'room': '100', 'organization': 'uninett.srv'}, stateful=True, open=True, acked=False)
78
+ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=3, name='foobar, type='nav', user=4, base_url='http://localhost/'), source_incident_id='2716057', details_url='http://localhost/search/event/2716057', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('host', 'uninett-gsw1.uninett.no'), ('room', '100'), ('organization', 'uninett.srv')]), stateful=True, open=True, acked=False)
77
79
  ```
78
80
 
79
81
  ### Post a new incident
@@ -81,17 +83,17 @@ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzin
81
83
  ```pycon
82
84
  >>> from pyargus.client import Client
83
85
  >>> from pyargus.models import Incident
84
- >>> from datetime import datetime
86
+ >>> from pyargus.time import now as utcnow
85
87
  >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
86
88
  >>> i = Incident(
87
89
  ... description="The earth was demolished to make way for a hyperspace bypass",
88
- ... start_time=datetime.now(),
90
+ ... start_time=utcnow(),
89
91
  ... tags={
90
92
  ... "host": "earth.example.org",
91
93
  ... }
92
94
  ... )
93
95
  >>> c.post_incident(i)
94
- Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=5, ticket_url='', tags={'host': 'earth.example.org'}, stateful=False, open=False, acked=False)
96
+ Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=5, ticket_url='', tags=MultiValueDict([('host', 'earth.example.org')]), stateful=False, open=False, acked=False)
95
97
  ```
96
98
 
97
99
  The `post_incident()` method returns the full `Incident` record, as stored in
@@ -106,12 +108,26 @@ convenience method for this operation:
106
108
 
107
109
  ```pycon
108
110
  >>> from pyargus.client import Client
109
- >>> from datetime import datetime
111
+ >>> from pyargus.time import now as utcnow
110
112
  >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
111
- >>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=datetime.now())
113
+ >>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=utcnow())
112
114
  Event(pk=10, actor='testnav', description='The demolition was cancelled', incident=8, received=datetime.datetime(2021, 4, 22, 11, 47, 11, 978438, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), timestamp=datetime.datetime(2021, 4, 22, 11, 47, 11, 946076, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), type='END')
113
115
  ```
114
116
 
117
+ ### Restart an existing incident
118
+
119
+ Incidents are restarted by posting a *RES* type event to an incident's event
120
+ log, with an optional timestamp. The `Client` class provides the follow
121
+ convenience method for this operation:
122
+
123
+ ```pycon
124
+ >>> from pyargus.client import Client
125
+ >>> from pyargus.time import now as utcnow
126
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
127
+ >>> c.restart_incident(incident=8, description="The demolition was restarted", timestamp=utcnow())
128
+ Event(pk=10, actor='testnav', description='The demolition was restarted', incident=8, received=datetime.datetime(2021, 4, 22, 11, 47, 11, 978438, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), timestamp=datetime.datetime(2021, 4, 22, 11, 47, 11, 946076, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), type='RES')
129
+ ```
130
+
115
131
  ### Modify an existing incident
116
132
 
117
133
  Argus does not allow modification of most incident attributes, but things
@@ -132,10 +148,48 @@ wish you modify, and then adding values to the attributes you wish to modify:
132
148
  ... }
133
149
  ... )
134
150
  >>> c.update_incident(i)
135
- Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=None, ticket_url='', tags={'host': 'earth.example.org', 'location': 'Milky way'}, stateful=False, open=False, acked=False)
151
+ Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=None, ticket_url='', tags=MultiValueDict([('host', 'earth.example.org'), ('location', 'Milky way')]), stateful=False, open=False, acked=False)
136
152
 
137
153
  ```
138
154
 
155
+ ### Working with multi-valued tags
156
+
157
+ Argus allows an incident to carry the same tag key more than once (for example
158
+ two different `host` values). The `tags` attribute is therefore a
159
+ `MultiValueDict` — a `dict` subclass that keeps every value while still behaving
160
+ like an ordinary dictionary for code that expects a single value per key.
161
+
162
+ Construct it from a sequence of `(key, value)` pairs (unlike a plain `dict`,
163
+ repeated keys are kept), or build it up with `add()`:
164
+
165
+ ```pycon
166
+ >>> from pyargus.models import Incident
167
+ >>> from pyargus.multivaluedict import MultiValueDict
168
+ >>> tags = MultiValueDict([("host", "a.example.org"), ("host", "b.example.org")])
169
+ >>> tags.add("location", "Milky way")
170
+ >>> i = Incident(description="Two hosts affected", tags=tags)
171
+ ```
172
+
173
+ Reading a multi-valued key through the ordinary `[]`/`get()` interface returns
174
+ only the *last* value and emits a `DeprecationWarning`, because the other values
175
+ are dropped silently. Use `getlist()` to retrieve them all:
176
+
177
+ ```pycon
178
+ >>> tags.getlist("host") # every value for the key
179
+ ['a.example.org', 'b.example.org']
180
+ >>> tags["host"] # last value only; warns that values are dropped
181
+ 'b.example.org'
182
+ >>> tags["location"] # single-valued keys read normally, no warning
183
+ 'Milky way'
184
+ >>> tags.lists() # all keys with all of their values
185
+ [('host', ['a.example.org', 'b.example.org']), ('location', ['Milky way'])]
186
+ >>> tags.allitems() # every (key, value) pair, including repeats
187
+ [('host', 'a.example.org'), ('host', 'b.example.org'), ('location', 'Milky way')]
188
+ ```
189
+
190
+ Passing a plain `dict` as `tags` still works exactly as before, so existing code
191
+ needs no changes.
192
+
139
193
  ### Stateless incidents
140
194
 
141
195
  Argus supports a concept of "stateless" incidents. Stateless incidents
@@ -143,13 +197,13 @@ represent single points in time, and do not have an end time. To explicitly
143
197
  create stateless incidents, set the `end_time` attribute to the STATELESS
144
198
  sentinel, like so:
145
199
 
146
- ```python
147
- from datetime import datetime
200
+ ```pycon
148
201
  from pyargus.models import Incident, STATELESS
202
+ from pyargus.time import now as utcnow
149
203
 
150
204
  stateless_incident = Incident(
151
205
  description="Something happened",
152
- start_time=datetime.now(),
206
+ start_time=utcnow(),
153
207
  end_time=STATELESS
154
208
  )
155
209
  ```
@@ -168,6 +222,50 @@ c = Client(api_root_url="https://argus.example.org/api/v2", token=tokenobj.token
168
222
  # secrets file so that it is not lost on program exit
169
223
  ```
170
224
 
225
+ ### Send a heartbeat
226
+
227
+ A source system with no incidents to report looks exactly like one that has
228
+ crashed. Every glue service should therefore send a *heartbeat* on a regular
229
+ schedule to prove it is still alive. A heartbeat updates the source system's
230
+ `last_seen` timestamp on the server without posting an incident, so Argus can
231
+ tell a healthy-but-quiet source apart from a dead one.
232
+
233
+ ```python
234
+ c.send_heartbeat()
235
+ ```
236
+
237
+ The method returns `None` on success. On failure it raises an exception from
238
+ `simple_rest_client`, the HTTP client library that pyargus is built on; these
239
+ exceptions are defined in its `simple_rest_client.exceptions` module (for
240
+ example, `AuthError` for a `401` or `403` response).
241
+
242
+ #### Detecting whether the server supports heartbeats
243
+
244
+ The heartbeat endpoint requires an Argus server new enough to provide it.
245
+ Older servers don't fail cleanly on a `POST` — they reject it with a `403` that
246
+ is indistinguishable from an authentication error — so don't infer support from
247
+ the `send_heartbeat()` outcome. Instead, probe up front with
248
+ `supports_heartbeat()`, which issues a `GET` and returns whether the endpoint is
249
+ present:
250
+
251
+ ```python
252
+ if c.supports_heartbeat():
253
+ c.send_heartbeat()
254
+ ```
255
+
256
+ A long-running glue service can check once at startup and decide whether to
257
+ bother sending heartbeats at all:
258
+
259
+ ```python
260
+ c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
261
+ heartbeats_enabled = c.supports_heartbeat()
262
+ while running:
263
+ do_work()
264
+ if heartbeats_enabled:
265
+ c.send_heartbeat()
266
+ sleep(interval)
267
+ ```
268
+
171
269
  ## Async usage
172
270
 
173
271
  An `AsyncClient` is available for use in asyncio-based applications. It mirrors
@@ -177,7 +275,7 @@ to try these examples interactively:
177
275
  ```pycon
178
276
  >>> from pyargus.async_client import AsyncClient
179
277
  >>> from pyargus.models import Incident
180
- >>> from datetime import datetime
278
+ >>> from pyargus.time import now as utcnow
181
279
  >>> c = AsyncClient(api_root_url="https://argus.example.org/api/v2", token="foobar")
182
280
  >>> async for incident in c.get_incidents(open=True, acked=False):
183
281
  ... print(incident)
@@ -185,11 +283,14 @@ to try these examples interactively:
185
283
  Incident(pk=4, ...)
186
284
  >>> i = Incident(
187
285
  ... description="The earth was demolished to make way for a hyperspace bypass",
188
- ... start_time=datetime.now(),
286
+ ... start_time=utcnow(),
189
287
  ... tags={"host": "earth.example.org"},
190
288
  ... )
191
289
  >>> await c.post_incident(i)
192
290
  Incident(pk=8, ...)
291
+ >>> if await c.supports_heartbeat():
292
+ ... await c.send_heartbeat()
293
+ ...
193
294
  ```
194
295
 
195
296
  ## BUGS
@@ -22,6 +22,8 @@ The `Client` class is found in `pyargus.client`, and the various supported data
22
22
  models, such as `Incident`, `Event`, `Acknowledgement` and `SourceSystem`, are
23
23
  implemented in `pyargus.models`.
24
24
 
25
+ **Note:** Always pass timezone-aware `datetime` objects (e.g. `datetime.now(tz=timezone.utc)`) to the client. pyargus serializes datetimes verbatim, so a naive value reaches Argus without a UTC offset and gets recorded at the wrong time.
26
+
25
27
  ### Listing open incidents that have not been acknowledged
26
28
 
27
29
  ```pycon
@@ -30,9 +32,9 @@ implemented in `pyargus.models`.
30
32
  >>> for incident in c.get_incidents(open=True, acked=False):
31
33
  ... print(incident)
32
34
  ...
33
- Incident(pk=4, start_time=datetime.datetime(2021, 4, 4, 16, 37, 43, 293726, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202430', details_url='http://localhost/search/event/202430', description='uninett-gsw2 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'room': '100', 'organization': 'uninett.srv', 'host': 'uninett-gsw2.uninett.no'}, stateful=True, open=True, acked=False)
34
- Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202429', details_url='http://localhost/search/event/202429', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'host': 'uninett-gsw1.uninett.no', 'room': '100', 'organization': 'uninett.srv'}, stateful=True, open=True, acked=False)
35
- Incident(pk=2, start_time=datetime.datetime(2017, 8, 31, 14, 58, 31, 118794, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='184296', details_url='http://localhost/search/event/184296', description='Link DOWN on Gi0/3 at oldsmobile.lab (Simple is better than complex)', level=5, ticket_url='', tags={'room': '113', 'location': 'Teknobyen Innovasjonssenter', 'organization': 'uninett.testlab', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'linkState', 'alert_type': 'linkDown', 'host': 'oldsmobile.lab.uninett.no', 'interface': 'Gi0/3'}, stateful=True, open=True, acked=False)
35
+ Incident(pk=4, start_time=datetime.datetime(2021, 4, 4, 16, 37, 43, 293726, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202430', details_url='http://localhost/search/event/202430', description='uninett-gsw2 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('room', '100'), ('organization', 'uninett.srv'), ('host', 'uninett-gsw2.uninett.no')]), stateful=True, open=True, acked=False)
36
+ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='202429', details_url='http://localhost/search/event/202429', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('host', 'uninett-gsw1.uninett.no'), ('room', '100'), ('organization', 'uninett.srv')]), stateful=True, open=True, acked=False)
37
+ Incident(pk=2, start_time=datetime.datetime(2017, 8, 31, 14, 58, 31, 118794, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='184296', details_url='http://localhost/search/event/184296', description='Link DOWN on Gi0/3 at oldsmobile.lab (Simple is better than complex)', level=5, ticket_url='', tags=MultiValueDict([('room', '113'), ('location', 'Teknobyen Innovasjonssenter'), ('organization', 'uninett.testlab'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'linkState'), ('alert_type', 'linkDown'), ('host', 'oldsmobile.lab.uninett.no'), ('interface', 'Gi0/3')]), stateful=True, open=True, acked=False)
36
38
  ```
37
39
 
38
40
  As you can see, the arguments given to `get_incidents()` are translated
@@ -54,7 +56,7 @@ Example:
54
56
  >>> for incident in c.get_my_incidents(open=True, acked=False):
55
57
  ... print(incident)
56
58
  ...
57
- Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=3, name='foobar, type='nav', user=4, base_url='http://localhost/'), source_incident_id='2716057', details_url='http://localhost/search/event/2716057', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags={'location': 'Teknobyen Innovasjonssenter', 'kundetjeneste': 'Nett_CNaaS', 'kunde': 'example.org', 'event_type': 'bgpState', 'alert_type': 'bgpDown', 'host': 'uninett-gsw1.uninett.no', 'room': '100', 'organization': 'uninett.srv'}, stateful=True, open=True, acked=False)
59
+ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), source=SourceSystem(pk=3, name='foobar, type='nav', user=4, base_url='http://localhost/'), source_incident_id='2716057', details_url='http://localhost/search/event/2716057', description='uninett-gsw1 BGP session with 158.38.3.112 is DOWN', level=5, ticket_url='', tags=MultiValueDict([('location', 'Teknobyen Innovasjonssenter'), ('kundetjeneste', 'Nett_CNaaS'), ('kunde', 'example.org'), ('event_type', 'bgpState'), ('alert_type', 'bgpDown'), ('host', 'uninett-gsw1.uninett.no'), ('room', '100'), ('organization', 'uninett.srv')]), stateful=True, open=True, acked=False)
58
60
  ```
59
61
 
60
62
  ### Post a new incident
@@ -62,17 +64,17 @@ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzin
62
64
  ```pycon
63
65
  >>> from pyargus.client import Client
64
66
  >>> from pyargus.models import Incident
65
- >>> from datetime import datetime
67
+ >>> from pyargus.time import now as utcnow
66
68
  >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
67
69
  >>> i = Incident(
68
70
  ... description="The earth was demolished to make way for a hyperspace bypass",
69
- ... start_time=datetime.now(),
71
+ ... start_time=utcnow(),
70
72
  ... tags={
71
73
  ... "host": "earth.example.org",
72
74
  ... }
73
75
  ... )
74
76
  >>> c.post_incident(i)
75
- Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=5, ticket_url='', tags={'host': 'earth.example.org'}, stateful=False, open=False, acked=False)
77
+ Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=5, ticket_url='', tags=MultiValueDict([('host', 'earth.example.org')]), stateful=False, open=False, acked=False)
76
78
  ```
77
79
 
78
80
  The `post_incident()` method returns the full `Incident` record, as stored in
@@ -87,12 +89,26 @@ convenience method for this operation:
87
89
 
88
90
  ```pycon
89
91
  >>> from pyargus.client import Client
90
- >>> from datetime import datetime
92
+ >>> from pyargus.time import now as utcnow
91
93
  >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
92
- >>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=datetime.now())
94
+ >>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=utcnow())
93
95
  Event(pk=10, actor='testnav', description='The demolition was cancelled', incident=8, received=datetime.datetime(2021, 4, 22, 11, 47, 11, 978438, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), timestamp=datetime.datetime(2021, 4, 22, 11, 47, 11, 946076, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), type='END')
94
96
  ```
95
97
 
98
+ ### Restart an existing incident
99
+
100
+ Incidents are restarted by posting a *RES* type event to an incident's event
101
+ log, with an optional timestamp. The `Client` class provides the follow
102
+ convenience method for this operation:
103
+
104
+ ```pycon
105
+ >>> from pyargus.client import Client
106
+ >>> from pyargus.time import now as utcnow
107
+ >>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
108
+ >>> c.restart_incident(incident=8, description="The demolition was restarted", timestamp=utcnow())
109
+ Event(pk=10, actor='testnav', description='The demolition was restarted', incident=8, received=datetime.datetime(2021, 4, 22, 11, 47, 11, 978438, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), timestamp=datetime.datetime(2021, 4, 22, 11, 47, 11, 946076, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), type='RES')
110
+ ```
111
+
96
112
  ### Modify an existing incident
97
113
 
98
114
  Argus does not allow modification of most incident attributes, but things
@@ -113,10 +129,48 @@ wish you modify, and then adding values to the attributes you wish to modify:
113
129
  ... }
114
130
  ... )
115
131
  >>> c.update_incident(i)
116
- Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=None, ticket_url='', tags={'host': 'earth.example.org', 'location': 'Milky way'}, stateful=False, open=False, acked=False)
132
+ Incident(pk=8, start_time=datetime.datetime(2021, 4, 22, 11, 41, 53, 580947, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200), '+02:00')), end_time=None, source=SourceSystem(pk=2, name='testnav', type='nav', user=3, base_url='http://localhost/'), source_incident_id='', details_url='', description='The earth was demolished to make way for a hyperspace bypass', level=None, ticket_url='', tags=MultiValueDict([('host', 'earth.example.org'), ('location', 'Milky way')]), stateful=False, open=False, acked=False)
117
133
 
118
134
  ```
119
135
 
136
+ ### Working with multi-valued tags
137
+
138
+ Argus allows an incident to carry the same tag key more than once (for example
139
+ two different `host` values). The `tags` attribute is therefore a
140
+ `MultiValueDict` — a `dict` subclass that keeps every value while still behaving
141
+ like an ordinary dictionary for code that expects a single value per key.
142
+
143
+ Construct it from a sequence of `(key, value)` pairs (unlike a plain `dict`,
144
+ repeated keys are kept), or build it up with `add()`:
145
+
146
+ ```pycon
147
+ >>> from pyargus.models import Incident
148
+ >>> from pyargus.multivaluedict import MultiValueDict
149
+ >>> tags = MultiValueDict([("host", "a.example.org"), ("host", "b.example.org")])
150
+ >>> tags.add("location", "Milky way")
151
+ >>> i = Incident(description="Two hosts affected", tags=tags)
152
+ ```
153
+
154
+ Reading a multi-valued key through the ordinary `[]`/`get()` interface returns
155
+ only the *last* value and emits a `DeprecationWarning`, because the other values
156
+ are dropped silently. Use `getlist()` to retrieve them all:
157
+
158
+ ```pycon
159
+ >>> tags.getlist("host") # every value for the key
160
+ ['a.example.org', 'b.example.org']
161
+ >>> tags["host"] # last value only; warns that values are dropped
162
+ 'b.example.org'
163
+ >>> tags["location"] # single-valued keys read normally, no warning
164
+ 'Milky way'
165
+ >>> tags.lists() # all keys with all of their values
166
+ [('host', ['a.example.org', 'b.example.org']), ('location', ['Milky way'])]
167
+ >>> tags.allitems() # every (key, value) pair, including repeats
168
+ [('host', 'a.example.org'), ('host', 'b.example.org'), ('location', 'Milky way')]
169
+ ```
170
+
171
+ Passing a plain `dict` as `tags` still works exactly as before, so existing code
172
+ needs no changes.
173
+
120
174
  ### Stateless incidents
121
175
 
122
176
  Argus supports a concept of "stateless" incidents. Stateless incidents
@@ -124,13 +178,13 @@ represent single points in time, and do not have an end time. To explicitly
124
178
  create stateless incidents, set the `end_time` attribute to the STATELESS
125
179
  sentinel, like so:
126
180
 
127
- ```python
128
- from datetime import datetime
181
+ ```pycon
129
182
  from pyargus.models import Incident, STATELESS
183
+ from pyargus.time import now as utcnow
130
184
 
131
185
  stateless_incident = Incident(
132
186
  description="Something happened",
133
- start_time=datetime.now(),
187
+ start_time=utcnow(),
134
188
  end_time=STATELESS
135
189
  )
136
190
  ```
@@ -149,6 +203,50 @@ c = Client(api_root_url="https://argus.example.org/api/v2", token=tokenobj.token
149
203
  # secrets file so that it is not lost on program exit
150
204
  ```
151
205
 
206
+ ### Send a heartbeat
207
+
208
+ A source system with no incidents to report looks exactly like one that has
209
+ crashed. Every glue service should therefore send a *heartbeat* on a regular
210
+ schedule to prove it is still alive. A heartbeat updates the source system's
211
+ `last_seen` timestamp on the server without posting an incident, so Argus can
212
+ tell a healthy-but-quiet source apart from a dead one.
213
+
214
+ ```python
215
+ c.send_heartbeat()
216
+ ```
217
+
218
+ The method returns `None` on success. On failure it raises an exception from
219
+ `simple_rest_client`, the HTTP client library that pyargus is built on; these
220
+ exceptions are defined in its `simple_rest_client.exceptions` module (for
221
+ example, `AuthError` for a `401` or `403` response).
222
+
223
+ #### Detecting whether the server supports heartbeats
224
+
225
+ The heartbeat endpoint requires an Argus server new enough to provide it.
226
+ Older servers don't fail cleanly on a `POST` — they reject it with a `403` that
227
+ is indistinguishable from an authentication error — so don't infer support from
228
+ the `send_heartbeat()` outcome. Instead, probe up front with
229
+ `supports_heartbeat()`, which issues a `GET` and returns whether the endpoint is
230
+ present:
231
+
232
+ ```python
233
+ if c.supports_heartbeat():
234
+ c.send_heartbeat()
235
+ ```
236
+
237
+ A long-running glue service can check once at startup and decide whether to
238
+ bother sending heartbeats at all:
239
+
240
+ ```python
241
+ c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
242
+ heartbeats_enabled = c.supports_heartbeat()
243
+ while running:
244
+ do_work()
245
+ if heartbeats_enabled:
246
+ c.send_heartbeat()
247
+ sleep(interval)
248
+ ```
249
+
152
250
  ## Async usage
153
251
 
154
252
  An `AsyncClient` is available for use in asyncio-based applications. It mirrors
@@ -158,7 +256,7 @@ to try these examples interactively:
158
256
  ```pycon
159
257
  >>> from pyargus.async_client import AsyncClient
160
258
  >>> from pyargus.models import Incident
161
- >>> from datetime import datetime
259
+ >>> from pyargus.time import now as utcnow
162
260
  >>> c = AsyncClient(api_root_url="https://argus.example.org/api/v2", token="foobar")
163
261
  >>> async for incident in c.get_incidents(open=True, acked=False):
164
262
  ... print(incident)
@@ -166,11 +264,14 @@ to try these examples interactively:
166
264
  Incident(pk=4, ...)
167
265
  >>> i = Incident(
168
266
  ... description="The earth was demolished to make way for a hyperspace bypass",
169
- ... start_time=datetime.now(),
267
+ ... start_time=utcnow(),
170
268
  ... tags={"host": "earth.example.org"},
171
269
  ... )
172
270
  >>> await c.post_incident(i)
173
271
  Incident(pk=8, ...)
272
+ >>> if await c.supports_heartbeat():
273
+ ... await c.send_heartbeat()
274
+ ...
174
275
  ```
175
276
 
176
277
  ## BUGS