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.
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/PKG-INFO +117 -16
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/README.md +116 -15
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/PKG-INFO +117 -16
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/SOURCES.txt +5 -1
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/__init__.py +2 -1
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/api.py +13 -0
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/async_api.py +8 -0
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/async_client.py +69 -6
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/client.py +68 -6
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/pyargus/models.py +15 -8
- argus_api_client-0.8.0/src/pyargus/multivaluedict.py +251 -0
- argus_api_client-0.8.0/src/pyargus/time.py +10 -0
- argus_api_client-0.8.0/tests/test_api.py +28 -0
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/tests/test_async_api.py +6 -0
- argus_api_client-0.8.0/tests/test_async_client.py +110 -0
- argus_api_client-0.8.0/tests/test_client.py +99 -0
- argus_api_client-0.8.0/tests/test_models.py +62 -0
- argus_api_client-0.8.0/tests/test_multivaluedict.py +413 -0
- argus_api_client-0.7.0/tests/test_api.py +0 -14
- argus_api_client-0.7.0/tests/test_async_client.py +0 -35
- argus_api_client-0.7.0/tests/test_client.py +0 -31
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/LICENSE +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/pyproject.toml +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/setup.cfg +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/dependency_links.txt +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.8.0}/src/argus_api_client.egg-info/requires.txt +0 -0
- {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.
|
|
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=
|
|
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=
|
|
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=
|
|
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=
|
|
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
|
|
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=
|
|
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=
|
|
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
|
|
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=
|
|
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=
|
|
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
|
-
```
|
|
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=
|
|
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
|
|
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=
|
|
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=
|
|
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=
|
|
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=
|
|
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=
|
|
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
|
|
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=
|
|
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=
|
|
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
|
|
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=
|
|
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=
|
|
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
|
-
```
|
|
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=
|
|
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
|
|
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=
|
|
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
|