django-netjsongraph 0.3.4

FETCH strategy

Topology data will be fetched from a URL.

When some links are not detected anymore they will be flagged as “down” straightaway.

RECEIVE strategy

Topology data is sent directly from one or more nodes of the network.

The collector waits to receive data in the payload of a POST HTTP request; when such a request is received, a key parameter it’s first checked against the Topology key.

If the request is authorized the collector proceeds to update the topology.

If the data is sent from one node only, it’s highly advised to set the expiration_time of the Topology instance to 0 (seconds), this way the system works just like in the FETCH strategy, with the only difference that the data is sent by one node instead of fetched by the collector.

If the data is sent from multiple nodes, you SHOULD set the expiration_time of the Topology instance to a value slightly higher than the interval used by nodes to send the topology, this way links will be flagged as “down” only if they haven’t been detected for a while. This mechanism allows to visualize the topology even if the network has been split in several parts, the disadvantage is that it will take a bit more time to detect links that go offline.

NETJSONGRAPH_PARSERS

Additional custom netdiff parsers.

NETJSONGRAPH_SIGNALS

String representing python module to import on initialization.

Useful for loading django signals or to define custom behaviour.

NETJSONGRAPH_TIMEOUT

Timeout when fetching topology URLs.

NETJSONGRAPH_LINK_EXPIRATION

If a link is down for more days than this number, it will be deleted by the update_topology management command.

Setting this to False will disable this feature.

NETJSONGRAPH_VISUALIZER_CSS

Path of the visualizer css file. Allows customization of css according to user’s preferences.

Example: overriding the <script> tag

Here’s a step by step guide on how to change the javascript options passed to netjsongraph.js, remember to replace <project_path> with the absolute filesytem path of your project.

Step 1: create a directory in <project_path>/templates/netjsongraph

Step 2: open your settings.py and edit the TEMPLATES['DIRS'] setting so that it looks like the following example:

# settings.py
TEMPLATES = [
    {
        'DIRS': [os.path.join(BASE_DIR, 'templates')],
        # ... all other lines have been omitted for brevity ...
    }
]

Step 3: create a new file named netjsongraph-script.html in the new <project_path>/templates/netjsongraph/ directory, eg:

<!-- <project_path>/templates/netjsongraph/netjsongraph-script.html -->
<script>
    var graph = d3.netJsonGraph("{% url 'network_graph' topology.pk %}", {
        linkClassProperty: "status",
        defaultStyle: false,
        labelDy: "-1.4em",
        circleRadius: 8,
        charge: -100,
        gravity: 0.3,
        linkDistance: 100,
        linkStrength: 0.2,
        # more customisations here ...
    });
</script>

Extending models

This example provides an example of how to extend the base models of django-netjsongraph.

# models.py of your custom ``network`` app
from django.db import models

from django_netjsongraph.base.link import AbstractLink
from django_netjsongraph.base.node import AbstractNode
from django_netjsongraph.base.topology import AbstractTopology

# the model ``organizations.Organization`` is omitted for brevity
# if you are curious to see a real implementation, check out django-organizations
# https://github.com/bennylope/django-organizations

class OrganizationMixin(models.Model):
    organization = models.ForeignKey('organization.Organization')

    class Meta:
        abstract = True


class Topology(OrganizationMixin, AbstractTopology):
    def clean(self):
        # your own validation logic here
        pass

    class Meta(AbstractTopology.Meta):
        abstract = False


class Node(AbstractNode):
    topology = models.ForeignKey('Topology')

    class Meta:
        abstract = False


class Link(AbstractLink):
    topology = models.ForeignKey('Topology')
    source = models.ForeignKey('Node',
                               related_name='source_link_set')
    target = models.ForeignKey('Node',
                               related_name='source_target_set')

    class Meta:
        abstract = False

Extending the admin

Following the above example, you can avoid duplicating the admin code by importing the base admin classes and registering your models with.

# admin.py of your app
from django.contrib import admin
from django_netjsongraph.base.admin import (AbstractLinkAdmin,
                                            AbstractNodeAdmin,
                                            AbstractTopologyAdmin)
# these are you custom models
from .models import Link, Node, Topology


class TopologyAdmin(AbstractTopologyAdmin):
    model = Topology


class NodeAdmin(AbstractNodeAdmin):
    model = Node


class LinkAdmin(AbstractLinkAdmin):
    model = Link


admin.site.register(Link, LinkAdmin)
admin.site.register(Node, NodeAdmin)
admin.site.register(Topology, TopologyAdmin)

Extending API views

If your use case doesn’t vary much from the base, you may also want to try to reuse the API views:

# your app.api.views
from ..models import Topology
from django_netjsongraph.api.generics import (BaseNetworkCollectionView,
                                              BaseNetworkGraphView,
                                              BaseReceiveTopologyView)


class NetworkCollectionView(BaseNetworkCollectionView):
    queryset = Topology.objects.filter(published=True)


class NetworkGraphView(BaseNetworkGraphView):
    queryset = Topology.objects.filter(published=True)


class ReceiveTopologyView(BaseReceiveTopologyView):
    model = Topology


network_collection = NetworkCollectionView.as_view()
network_graph = NetworkGraphView.as_view()
receive_topology = ReceiveTopologyView.as_view()

API URLs

If you are not making drastic changes to the api views, you can avoid duplicating the URL logic by using the get_api_urls function. Put this in your api urls.py:

# your app.api.urls
from django_netjsongraph.utils import get_api_urls
from . import views

urlpatterns = get_api_urls(views)

Extending Visualizer Views

If your use case doesn’t vary much from the base, you may also want to try to reuse the Visualizer views:

# your app.visualizer.views
from ..models import Topology
from .generics import BaseTopologyDetailView, BaseTopologyListView


class TopologyListView(BaseTopologyListView):
    topology_model = Topology


class TopologyDetailView(BaseTopologyDetailView):
    topology_model = Topology


topology_list = TopologyListView.as_view()
topology_detail = TopologyDetailView.as_view()

Visualizer URLs

If you are not making any drastic changes to visualizer views, you can avoid duplicating the URL logic by using get_visualizer_urls function. Put this in your visualizer urls.py

# your app.visualizer.urls
from django_netjsongraph.utils import get_visualizer_urls
from . import views

urlpatterns = get_visualizer_urls(views)

Extending AppConfig

You may want to reuse the AppConfig class of django-netjsongraph too:

from django_netjsongraph.apps import DjangoNetjsongraphConfig

class MyOwnConfig(DjangoNetjsongraphConfig):
    name = 'yourapp'
    label = 'yourapp'