argus-api-client 0.7.0__tar.gz → 0.9.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.9.0}/PKG-INFO +206 -21
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/README.md +199 -17
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/pyproject.toml +19 -4
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/PKG-INFO +206 -21
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/SOURCES.txt +5 -1
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/__init__.py +2 -1
- argus_api_client-0.9.0/src/pyargus/api.py +117 -0
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/async_api.py +28 -5
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/async_client.py +136 -15
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/client.py +133 -15
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/pyargus/models.py +42 -12
- argus_api_client-0.9.0/src/pyargus/multivaluedict.py +251 -0
- argus_api_client-0.9.0/src/pyargus/time.py +10 -0
- argus_api_client-0.9.0/tests/test_api.py +28 -0
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/tests/test_async_api.py +6 -0
- argus_api_client-0.9.0/tests/test_async_client.py +235 -0
- argus_api_client-0.9.0/tests/test_client.py +208 -0
- argus_api_client-0.9.0/tests/test_models.py +119 -0
- argus_api_client-0.9.0/tests/test_multivaluedict.py +413 -0
- argus_api_client-0.7.0/src/pyargus/api.py +0 -61
- 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.9.0}/LICENSE +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/setup.cfg +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/dependency_links.txt +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/requires.txt +0 -0
- {argus_api_client-0.7.0 → argus_api_client-0.9.0}/src/argus_api_client.egg-info/top_level.txt +0 -0
|
@@ -1,16 +1,19 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: argus-api-client
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.9.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
|
|
7
|
+
Project-URL: GitHub, https://github.com/Uninett/pyargus
|
|
8
|
+
Project-URL: Changelog, https://github.com/Uninett/pyargus/blob/master/CHANGELOG.md
|
|
9
|
+
Project-URL: Argus, https://network.geant.org/argus/
|
|
7
10
|
Classifier: Programming Language :: Python :: 3
|
|
8
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
9
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
10
11
|
Classifier: Programming Language :: Python :: 3.11
|
|
11
12
|
Classifier: Programming Language :: Python :: 3.12
|
|
12
13
|
Classifier: Programming Language :: Python :: 3.13
|
|
13
|
-
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
16
|
+
Requires-Python: >=3.11
|
|
14
17
|
Description-Content-Type: text/markdown
|
|
15
18
|
License-File: LICENSE
|
|
16
19
|
Requires-Dist: simple_rest_client
|
|
@@ -41,6 +44,8 @@ The `Client` class is found in `pyargus.client`, and the various supported data
|
|
|
41
44
|
models, such as `Incident`, `Event`, `Acknowledgement` and `SourceSystem`, are
|
|
42
45
|
implemented in `pyargus.models`.
|
|
43
46
|
|
|
47
|
+
**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.
|
|
48
|
+
|
|
44
49
|
### Listing open incidents that have not been acknowledged
|
|
45
50
|
|
|
46
51
|
```pycon
|
|
@@ -49,9 +54,9 @@ implemented in `pyargus.models`.
|
|
|
49
54
|
>>> for incident in c.get_incidents(open=True, acked=False):
|
|
50
55
|
... print(incident)
|
|
51
56
|
...
|
|
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=
|
|
57
|
+
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)
|
|
58
|
+
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)
|
|
59
|
+
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
60
|
```
|
|
56
61
|
|
|
57
62
|
As you can see, the arguments given to `get_incidents()` are translated
|
|
@@ -73,7 +78,7 @@ Example:
|
|
|
73
78
|
>>> for incident in c.get_my_incidents(open=True, acked=False):
|
|
74
79
|
... print(incident)
|
|
75
80
|
...
|
|
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=
|
|
81
|
+
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
82
|
```
|
|
78
83
|
|
|
79
84
|
### Post a new incident
|
|
@@ -81,17 +86,17 @@ Incident(pk=3, start_time=datetime.datetime(2021, 4, 4, 16, 32, 53, 128780, tzin
|
|
|
81
86
|
```pycon
|
|
82
87
|
>>> from pyargus.client import Client
|
|
83
88
|
>>> from pyargus.models import Incident
|
|
84
|
-
>>> from
|
|
89
|
+
>>> from pyargus.time import now as utcnow
|
|
85
90
|
>>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
|
|
86
91
|
>>> i = Incident(
|
|
87
92
|
... description="The earth was demolished to make way for a hyperspace bypass",
|
|
88
|
-
... start_time=
|
|
93
|
+
... start_time=utcnow(),
|
|
89
94
|
... tags={
|
|
90
95
|
... "host": "earth.example.org",
|
|
91
96
|
... }
|
|
92
97
|
... )
|
|
93
98
|
>>> 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=
|
|
99
|
+
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
100
|
```
|
|
96
101
|
|
|
97
102
|
The `post_incident()` method returns the full `Incident` record, as stored in
|
|
@@ -106,12 +111,26 @@ convenience method for this operation:
|
|
|
106
111
|
|
|
107
112
|
```pycon
|
|
108
113
|
>>> from pyargus.client import Client
|
|
109
|
-
>>> from
|
|
114
|
+
>>> from pyargus.time import now as utcnow
|
|
110
115
|
>>> 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=
|
|
116
|
+
>>> c.resolve_incident(incident=8, description="The demolition was cancelled", timestamp=utcnow())
|
|
112
117
|
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
118
|
```
|
|
114
119
|
|
|
120
|
+
### Restart an existing incident
|
|
121
|
+
|
|
122
|
+
Incidents are restarted by posting a *RES* type event to an incident's event
|
|
123
|
+
log, with an optional timestamp. The `Client` class provides the follow
|
|
124
|
+
convenience method for this operation:
|
|
125
|
+
|
|
126
|
+
```pycon
|
|
127
|
+
>>> from pyargus.client import Client
|
|
128
|
+
>>> from pyargus.time import now as utcnow
|
|
129
|
+
>>> c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
|
|
130
|
+
>>> c.restart_incident(incident=8, description="The demolition was restarted", timestamp=utcnow())
|
|
131
|
+
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')
|
|
132
|
+
```
|
|
133
|
+
|
|
115
134
|
### Modify an existing incident
|
|
116
135
|
|
|
117
136
|
Argus does not allow modification of most incident attributes, but things
|
|
@@ -132,10 +151,48 @@ wish you modify, and then adding values to the attributes you wish to modify:
|
|
|
132
151
|
... }
|
|
133
152
|
... )
|
|
134
153
|
>>> 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=
|
|
154
|
+
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)
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Working with multi-valued tags
|
|
136
159
|
|
|
160
|
+
Argus allows an incident to carry the same tag key more than once (for example
|
|
161
|
+
two different `host` values). The `tags` attribute is therefore a
|
|
162
|
+
`MultiValueDict` — a `dict` subclass that keeps every value while still behaving
|
|
163
|
+
like an ordinary dictionary for code that expects a single value per key.
|
|
164
|
+
|
|
165
|
+
Construct it from a sequence of `(key, value)` pairs (unlike a plain `dict`,
|
|
166
|
+
repeated keys are kept), or build it up with `add()`:
|
|
167
|
+
|
|
168
|
+
```pycon
|
|
169
|
+
>>> from pyargus.models import Incident
|
|
170
|
+
>>> from pyargus.multivaluedict import MultiValueDict
|
|
171
|
+
>>> tags = MultiValueDict([("host", "a.example.org"), ("host", "b.example.org")])
|
|
172
|
+
>>> tags.add("location", "Milky way")
|
|
173
|
+
>>> i = Incident(description="Two hosts affected", tags=tags)
|
|
137
174
|
```
|
|
138
175
|
|
|
176
|
+
Reading a multi-valued key through the ordinary `[]`/`get()` interface returns
|
|
177
|
+
only the *last* value and emits a `DeprecationWarning`, because the other values
|
|
178
|
+
are dropped silently. Use `getlist()` to retrieve them all:
|
|
179
|
+
|
|
180
|
+
```pycon
|
|
181
|
+
>>> tags.getlist("host") # every value for the key
|
|
182
|
+
['a.example.org', 'b.example.org']
|
|
183
|
+
>>> tags["host"] # last value only; warns that values are dropped
|
|
184
|
+
'b.example.org'
|
|
185
|
+
>>> tags["location"] # single-valued keys read normally, no warning
|
|
186
|
+
'Milky way'
|
|
187
|
+
>>> tags.lists() # all keys with all of their values
|
|
188
|
+
[('host', ['a.example.org', 'b.example.org']), ('location', ['Milky way'])]
|
|
189
|
+
>>> tags.allitems() # every (key, value) pair, including repeats
|
|
190
|
+
[('host', 'a.example.org'), ('host', 'b.example.org'), ('location', 'Milky way')]
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Passing a plain `dict` as `tags` still works exactly as before, so existing code
|
|
194
|
+
needs no changes.
|
|
195
|
+
|
|
139
196
|
### Stateless incidents
|
|
140
197
|
|
|
141
198
|
Argus supports a concept of "stateless" incidents. Stateless incidents
|
|
@@ -143,13 +200,13 @@ represent single points in time, and do not have an end time. To explicitly
|
|
|
143
200
|
create stateless incidents, set the `end_time` attribute to the STATELESS
|
|
144
201
|
sentinel, like so:
|
|
145
202
|
|
|
146
|
-
```
|
|
147
|
-
from datetime import datetime
|
|
203
|
+
```pycon
|
|
148
204
|
from pyargus.models import Incident, STATELESS
|
|
205
|
+
from pyargus.time import now as utcnow
|
|
149
206
|
|
|
150
207
|
stateless_incident = Incident(
|
|
151
208
|
description="Something happened",
|
|
152
|
-
start_time=
|
|
209
|
+
start_time=utcnow(),
|
|
153
210
|
end_time=STATELESS
|
|
154
211
|
)
|
|
155
212
|
```
|
|
@@ -161,11 +218,136 @@ If your argus server is running version 1.29.0 or newer you can request to get
|
|
|
161
218
|
a new token (with a new expiration date) via API version 2. The token you are
|
|
162
219
|
using to access the server with must still be valid.
|
|
163
220
|
|
|
221
|
+
There are two methods:
|
|
222
|
+
|
|
223
|
+
#### Use an existing, still valid token
|
|
224
|
+
|
|
225
|
+
You need to already have a token and client.
|
|
226
|
+
|
|
164
227
|
```python
|
|
165
228
|
tokenobj = c.refresh_token()
|
|
229
|
+
# stash away token...
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`c` will be using the freshly fetched token after this.
|
|
233
|
+
|
|
234
|
+
#### Use a username/password
|
|
235
|
+
|
|
236
|
+
To get the token and expiry for stashing away:
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
from pyargus.client import login
|
|
240
|
+
|
|
241
|
+
tokenobj = login(
|
|
242
|
+
api_root_url="https://argus.example.org/api/v2",
|
|
243
|
+
username=username,
|
|
244
|
+
password=password,
|
|
245
|
+
)
|
|
246
|
+
# stash away token, then...
|
|
166
247
|
c = Client(api_root_url="https://argus.example.org/api/v2", token=tokenobj.token)
|
|
167
|
-
|
|
168
|
-
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
To get a client directly, without opportunity to save the token:
|
|
251
|
+
|
|
252
|
+
```python
|
|
253
|
+
from pyargus.client import Client
|
|
254
|
+
|
|
255
|
+
c = Client.login(
|
|
256
|
+
api_root_url="https://argus.example.org/api/v2",
|
|
257
|
+
username=username,
|
|
258
|
+
password=password,
|
|
259
|
+
)
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Note that `login` is a class method here.
|
|
263
|
+
|
|
264
|
+
### Set a new token in an existing client
|
|
265
|
+
|
|
266
|
+
```python
|
|
267
|
+
from pyargus.client import Client
|
|
268
|
+
# get a client that works with public endpoints
|
|
269
|
+
c = Client(api_root_url="https://argus.example.org/api/v2")
|
|
270
|
+
|
|
271
|
+
# get a token as a string from somewhere;
|
|
272
|
+
# * environment variable
|
|
273
|
+
# * secrets file
|
|
274
|
+
# * config file
|
|
275
|
+
# * command line argument
|
|
276
|
+
token = get_token_my_way()
|
|
277
|
+
|
|
278
|
+
# set it, replacing an existing one
|
|
279
|
+
c.set_token(token)
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
`c` will be using the given token after this.
|
|
283
|
+
|
|
284
|
+
### Send a heartbeat
|
|
285
|
+
|
|
286
|
+
A source system with no incidents to report looks exactly like one that has
|
|
287
|
+
crashed. Every glue service should therefore send a *heartbeat* on a regular
|
|
288
|
+
schedule to prove it is still alive. A heartbeat updates the source system's
|
|
289
|
+
`last_seen` timestamp on the server without posting an incident, so Argus can
|
|
290
|
+
tell a healthy-but-quiet source apart from a dead one.
|
|
291
|
+
|
|
292
|
+
```python
|
|
293
|
+
c.send_heartbeat()
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
The method returns `None` on success. On failure it raises an exception from
|
|
297
|
+
`simple_rest_client`, the HTTP client library that pyargus is built on; these
|
|
298
|
+
exceptions are defined in its `simple_rest_client.exceptions` module (for
|
|
299
|
+
example, `AuthError` for a `401` or `403` response).
|
|
300
|
+
|
|
301
|
+
#### Detecting whether the server supports heartbeats
|
|
302
|
+
|
|
303
|
+
The heartbeat endpoint requires an Argus server new enough to provide it.
|
|
304
|
+
Older servers don't fail cleanly on a `POST` — they reject it with a `403` that
|
|
305
|
+
is indistinguishable from an authentication error — so don't infer support from
|
|
306
|
+
the `send_heartbeat()` outcome. Instead, probe up front with
|
|
307
|
+
`supports_heartbeat()`, which issues a `GET` and returns whether the endpoint is
|
|
308
|
+
present:
|
|
309
|
+
|
|
310
|
+
```python
|
|
311
|
+
if c.supports_heartbeat():
|
|
312
|
+
c.send_heartbeat()
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
A long-running glue service can check once at startup and decide whether to
|
|
316
|
+
bother sending heartbeats at all:
|
|
317
|
+
|
|
318
|
+
```python
|
|
319
|
+
c = Client(api_root_url="https://argus.example.org/api/v2", token="foobar")
|
|
320
|
+
heartbeats_enabled = c.supports_heartbeat()
|
|
321
|
+
while running:
|
|
322
|
+
do_work()
|
|
323
|
+
if heartbeats_enabled:
|
|
324
|
+
c.send_heartbeat()
|
|
325
|
+
sleep(interval)
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
### Getting metadata about the server
|
|
329
|
+
|
|
330
|
+
This endpoint is public so it can be fetched without a token.
|
|
331
|
+
|
|
332
|
+
```python
|
|
333
|
+
from pprint import pprint
|
|
334
|
+
|
|
335
|
+
from pyargus.client import Client
|
|
336
|
+
|
|
337
|
+
c = Client(api_root_url="https://argus.example.org/api/v2")
|
|
338
|
+
metadata = c.get_server_metadata()
|
|
339
|
+
pprint(vars(metadata))
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
… which yields a structure looking like this (actual versions may differ):
|
|
343
|
+
|
|
344
|
+
```python
|
|
345
|
+
{'available_api_versions': {'v3', 'v2'},
|
|
346
|
+
'jsonapi_schema': {'stable': '/api/schema/',
|
|
347
|
+
'v2': '/api/v2/schema/',
|
|
348
|
+
'v3': '/api/v3/schema/'},
|
|
349
|
+
'server_version': '2.10.2',
|
|
350
|
+
'stable_api_version': 'v2'}
|
|
169
351
|
```
|
|
170
352
|
|
|
171
353
|
## Async usage
|
|
@@ -177,7 +359,7 @@ to try these examples interactively:
|
|
|
177
359
|
```pycon
|
|
178
360
|
>>> from pyargus.async_client import AsyncClient
|
|
179
361
|
>>> from pyargus.models import Incident
|
|
180
|
-
>>> from
|
|
362
|
+
>>> from pyargus.time import now as utcnow
|
|
181
363
|
>>> c = AsyncClient(api_root_url="https://argus.example.org/api/v2", token="foobar")
|
|
182
364
|
>>> async for incident in c.get_incidents(open=True, acked=False):
|
|
183
365
|
... print(incident)
|
|
@@ -185,11 +367,14 @@ to try these examples interactively:
|
|
|
185
367
|
Incident(pk=4, ...)
|
|
186
368
|
>>> i = Incident(
|
|
187
369
|
... description="The earth was demolished to make way for a hyperspace bypass",
|
|
188
|
-
... start_time=
|
|
370
|
+
... start_time=utcnow(),
|
|
189
371
|
... tags={"host": "earth.example.org"},
|
|
190
372
|
... )
|
|
191
373
|
>>> await c.post_incident(i)
|
|
192
374
|
Incident(pk=8, ...)
|
|
375
|
+
>>> if await c.supports_heartbeat():
|
|
376
|
+
... await c.send_heartbeat()
|
|
377
|
+
...
|
|
193
378
|
```
|
|
194
379
|
|
|
195
380
|
## BUGS
|