Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the event and alert type hierarchy #2297

Merged
merged 6 commits into from
Sep 9, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: dummy clean bigclean
.PHONY: dummy clean bigclean doc .FORCE

dummy:
@echo "'make' is no longer used for deployment. See 'doc/intro/install.rst'"
Expand All @@ -14,3 +14,10 @@ testclean: clean
-rm *.stats
-rm python/nav/web/static/js/package-lock.json
-rm -rf .tox

doc: doc/reference/alerttypes.rst

doc/reference/alerttypes.rst: .FORCE
python3 doc/exts/alerttypes.py > $@

.FORCE:
47 changes: 47 additions & 0 deletions doc/exts/alerttypes.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
#!/usr/bin/env python3
#
# Copyright (C) 2021 Uninett AS
#
# This file is part of Network Administration Visualized (NAV).
#
# NAV is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License version 3 as published by
# the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
# more details. You should have received a copy of the GNU General Public
# License along with NAV. If not, see <http://www.gnu.org/licenses/>.
#
"""This is not really a Sphinx extension, but a tool to autogenerate the reference
documentation for NAV's event- and alert type hierarchy.

It should only be necessary to re-run this in the event of changes to the supported
event/alert types, or in the templates used to generate this doc.
"""
import os

from jinja2 import FileSystemLoader, Environment # Jinja is a sub-dependency of Sphinx

from nav.bootstrap import bootstrap_django

bootstrap_django(__name__)


from nav.models.event import EventType, AlertType


def main():
env = Environment(loader=FileSystemLoader(os.path.dirname(__file__)))
template = env.get_template('alerttypes.rst.j2')

types = [
(eventtype, AlertType.objects.filter(event_type=eventtype))
for eventtype in EventType.objects.all()
]
print(template.render(types=types))


if __name__ == '__main__':
main()
41 changes: 41 additions & 0 deletions doc/exts/alerttypes.rst.j2
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
Event- and alert type hierarchy
===============================

NAV events and alerts are organized into a type hierarchy. While NAV's backend
monitoring processes usually generate events, the :program:`Event Engine` is
responsible for deciding what to do with those events. In most cases, events
are translated into a corresponding alert by the :program:`Event Engine`.

Most alerts are *stateful*, i.e. they can be viewed as an incident that has a
start time and an end time. If the end time is set to an infinite value, the
alert is considered unresolved (also known as *open*).

Some alert types indicate the beginning of a new alert state, while some alert
types indicate the closure of an existing alert state. E.g. for ``boxState``
alerts, a ``boxDown`` alert indicates that a new stateful incident has occured:
A device is no longer responsive. On the other hand, a ``boxUp`` alert will
cause an existing ``boxState``-type alert to be resolved.


All legal event- and alert-types are registered in the NAV database (and can
thus be extended, even by the user, if need be). The following are the event-
and alert types that come pre-defined with NAV:


{% for event, alerts in types %}
*{{ event.id }}* events
{{ '-' * event.id|length }}---------
{{ event.description }}

.. list-table:: Alerts associated with {{ event.id }} events
:widths: 25 75
:header-rows: 1

* - Alert type name
- Description
{% for alert in alerts %} * - ``{{ alert.name }}``
- {{ alert.description }}
{% endfor %}


{% endfor %}
19 changes: 19 additions & 0 deletions doc/hacking/release-procedure.rst
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,25 @@ Getting the code
git clone -b 4.8.x [email protected]:UNINETT/nav.git
cd nav

Ensure generated docs are up to date
------------------------------------

Some documentation source files need to be built using a running PostgreSQL
database. If any changes have been made to the default event- and
alert-hierarchies provided by NAV, these documentation source files need to be
updated and checked into Git.

If you have a full dev environment running (such as the environment defined by
:file:`docker-compose.yml`), use the following to generate new docs and verify
whether they have changed::

make doc
git status

If you see files under the :file:`doc` directory were changed, these changes
need to be checked into Git to ensure the documentation is up to date for the
new release.


Updating changelog and release notes
------------------------------------
Expand Down
Loading