netbox-loki 0.0.1__py3-none-any.whl

netbox_loki/__init__.py

@@ -0,0 +1,116 @@
+"""
+NetBox Loki plugin.
+
+Display recent Loki logs in Device and VirtualMachine detail pages.
+"""
+
+import logging
+
+from netbox.plugins import PluginConfig
+
+__version__ = "1.2.0"
+
+logger = logging.getLogger(__name__)
+
+
+class LokiConfig(PluginConfig):
+    """Plugin configuration for NetBox Loki integration."""
+
+    name = "netbox_loki"
+    verbose_name = "NetBox Loki Logs"
+    description = "Display recent Loki logs in device, VM, and endpoint detail pages"
+    version = __version__
+    author = "-----"
+    author_email = "---@gmail.com"
+    base_url = "loki"
+    min_version = "4.0.0"
+    max_version = "5.99"
+
+    # Required settings - plugin won't load without these
+    required_settings = []
+
+    # Default configuration values
+    default_settings = {
+        "loki_url": "http://localhost:3100",
+        "loki_external_url": "",
+        "loki_tenant": "docker",
+        "loki_username": "",
+        "loki_password": "",
+        "loki_bearer_token": "",
+        "loki_job": "syslog",
+        "device_label": "routerboard",
+        "stream_selector": "",
+        "log_limit": 100,
+        "time_range": 3600,
+        "timeout": 10,
+        "cache_timeout": 60,
+        "verify_tls": True,
+        "use_regex_matching": True,
+        "fallback_to_ip": True,
+    }
+
+    def ready(self):
+        """Register endpoint view if netbox_endpoints is available."""
+        super().ready()
+        from . import widgets  # noqa: F401
+
+        self._register_endpoint_views()
+
+    def _register_endpoint_views(self):
+        """Register Loki Logs tab for Endpoints if plugin is installed."""
+        import sys
+
+        # Quick check if netbox_endpoints is available
+        if "netbox_endpoints" not in sys.modules:
+            try:
+                import importlib.util
+
+                if importlib.util.find_spec("netbox_endpoints") is None:
+                    logger.debug("netbox_endpoints not installed, skipping endpoint view registration")
+                    return
+            except Exception:
+                logger.debug("netbox_endpoints not available, skipping endpoint view registration")
+                return
+
+        try:
+            from django.shortcuts import render
+            from netbox.views import generic
+            from netbox_endpoints.models import Endpoint
+            from utilities.views import ViewTab, register_model_view
+
+            @register_model_view(Endpoint, name="loki_logs", path="logs")
+            class EndpointLokiLogsView(generic.ObjectView):
+                """Display Loki logs for an Endpoint with async loading."""
+
+                queryset = Endpoint.objects.all()
+                template_name = "netbox_loki/endpoint_logs_tab.html"
+
+                tab = ViewTab(
+                    label="Loki",
+                    weight=9004,
+                    permission="netbox_endpoints.view_endpoint",
+                    hide_if_empty=False,
+                )
+
+                def get(self, request, pk):
+                    endpoint = Endpoint.objects.get(pk=pk)
+                    time_range = request.GET.get("range", "")
+                    return render(
+                        request,
+                        self.template_name,
+                        {
+                            "object": endpoint,
+                            "tab": self.tab,
+                            "loading": True,
+                            "time_range_param": time_range,
+                        },
+                    )
+
+            logger.info("Registered Loki Logs tab for Endpoint model")
+        except ImportError:
+            logger.debug("netbox_endpoints not installed, skipping endpoint view registration")
+        except Exception as e:
+            logger.warning(f"Could not register endpoint views: {e}")
+
+
+config = LokiConfig

netbox_loki/forms.py

@@ -0,0 +1,174 @@
+"""
+Forms for NetBox Loki plugin settings.
+"""
+
+from django import forms
+
+
+class LokiSettingsForm(forms.Form):
+    """Form for displaying Loki plugin settings."""
+
+    loki_url = forms.URLField(
+        label="Loki URL",
+        help_text="Base URL for the Loki HTTP API, for example: http://loki:3100",
+        required=True,
+        widget=forms.URLInput(
+            attrs={
+                "class": "form-control",
+                "placeholder": "http://loki:3100",
+            }
+        ),
+    )
+
+    loki_external_url = forms.URLField(
+        label="External URL",
+        help_text="Optional browser URL for opening Loki or Grafana from the NetBox UI.",
+        required=False,
+        widget=forms.URLInput(
+            attrs={
+                "class": "form-control",
+                "placeholder": "https://grafana.example.com/explore",
+            }
+        ),
+    )
+
+    loki_tenant = forms.CharField(
+        label="Tenant Header",
+        help_text="Optional value for the X-Scope-OrgID header when Loki multi-tenancy is enabled.",
+        required=False,
+        initial="docker",
+        widget=forms.TextInput(
+            attrs={
+                "class": "form-control",
+                "placeholder": "docker",
+            }
+        ),
+    )
+
+    loki_username = forms.CharField(
+        label="Username",
+        help_text="Optional basic-auth username used by a reverse proxy or managed Loki.",
+        required=False,
+        widget=forms.TextInput(attrs={"class": "form-control"}),
+    )
+
+    loki_password = forms.CharField(
+        label="Password",
+        help_text="Optional basic-auth password.",
+        required=False,
+        widget=forms.PasswordInput(attrs={"class": "form-control"}, render_value=True),
+    )
+
+    loki_bearer_token = forms.CharField(
+        label="Bearer Token",
+        help_text="Optional bearer token if your Loki endpoint is protected by token auth.",
+        required=False,
+        widget=forms.PasswordInput(attrs={"class": "form-control"}, render_value=True),
+    )
+
+    loki_job = forms.CharField(
+        label="Job Label Value",
+        help_text="Optional value for the standard Loki label `job`, for example: `syslog`.",
+        required=False,
+        initial="syslog",
+        widget=forms.TextInput(
+            attrs={
+                "class": "form-control",
+                "placeholder": "syslog",
+            }
+        ),
+    )
+
+    device_label = forms.CharField(
+        label="Device Label",
+        help_text="Loki label that stores the device or VM name, for example: `routerboard`, `host`, or `hostname`.",
+        required=True,
+        initial="routerboard",
+        widget=forms.TextInput(
+            attrs={
+                "class": "form-control",
+                "placeholder": "routerboard",
+            }
+        ),
+    )
+
+    stream_selector = forms.CharField(
+        label="Extra Stream Selector",
+        help_text='Optional extra Loki label selector fragment without braces, for example: `site="kyiv",env="prod"`.',
+        required=False,
+        widget=forms.TextInput(
+            attrs={
+                "class": "form-control",
+                "placeholder": 'site="kyiv",env="prod"',
+            }
+        ),
+    )
+
+    log_limit = forms.IntegerField(
+        label="Log Limit",
+        help_text="Maximum number of log lines to display per request.",
+        required=False,
+        initial=100,
+        min_value=10,
+        max_value=500,
+        widget=forms.NumberInput(attrs={"class": "form-control"}),
+    )
+
+    time_range = forms.ChoiceField(
+        label="Default Time Range",
+        help_text="Default time range for log queries.",
+        choices=[
+            (300, "5 minutes"),
+            (900, "15 minutes"),
+            (3600, "1 hour"),
+            (14400, "4 hours"),
+            (86400, "24 hours"),
+            (604800, "7 days"),
+        ],
+        initial=3600,
+        widget=forms.Select(attrs={"class": "form-control"}),
+    )
+
+    timeout = forms.IntegerField(
+        label="API Timeout",
+        help_text="Timeout for Loki API requests in seconds.",
+        required=False,
+        initial=10,
+        min_value=5,
+        max_value=60,
+        widget=forms.NumberInput(attrs={"class": "form-control"}),
+    )
+
+    cache_timeout = forms.IntegerField(
+        label="Cache Timeout",
+        help_text="How long to cache API responses in seconds.",
+        required=False,
+        initial=60,
+        min_value=0,
+        max_value=300,
+        widget=forms.NumberInput(attrs={"class": "form-control"}),
+    )
+
+    verify_tls = forms.BooleanField(
+        label="Verify TLS Certificates",
+        help_text="Disable only if your Loki endpoint uses a self-signed certificate.",
+        required=False,
+        initial=True,
+        widget=forms.CheckboxInput(attrs={"class": "form-check-input"}),
+    )
+
+    use_regex_matching = forms.BooleanField(
+        label="Allow Shortname/FQDN Matching",
+        help_text="Match `router1` against both `router1` and `router1.example.com` in Loki labels.",
+        required=False,
+        initial=True,
+        widget=forms.CheckboxInput(attrs={"class": "form-check-input"}),
+    )
+
+    fallback_to_ip = forms.BooleanField(
+        label="Fallback To Primary IP",
+        help_text="If hostname lookup returns no logs, try the primary IP from NetBox.",
+        required=False,
+        initial=True,
+        widget=forms.CheckboxInput(attrs={"class": "form-check-input"}),
+    )

netbox_loki/loki_client.py

@@ -0,0 +1,377 @@
+"""
+Loki API client.
+
+The module name stays the same to preserve import compatibility with the
+existing plugin package layout.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import requests
+from django.conf import settings
+from django.core.cache import cache
+
+logger = logging.getLogger(__name__)
+
+
+def _read_netbox_setting(config: dict[str, Any], plugin_key: str, setting_names: tuple[str, ...], default: Any) -> Any:
+    """Read a plugin setting from PLUGINS_CONFIG first, then from top-level Django settings."""
+    if plugin_key in config:
+        return config[plugin_key]
+
+    for setting_name in setting_names:
+        if hasattr(settings, setting_name):
+            return getattr(settings, setting_name)
+
+    return default
+
+
+class LokiClient:
+    """Client for querying Grafana Loki."""
+
+    def __init__(self) -> None:
+        self.config = settings.PLUGINS_CONFIG.get("netbox_loki", {})
+        self.base_url = _read_netbox_setting(
+            self.config,
+            "loki_url",
+            ("NETBOX_LOKI_LOKI_URL", "LOKI_URL"),
+            "http://localhost:3100",
+        ).rstrip("/")
+        self.timeout = _read_netbox_setting(self.config, "timeout", ("NETBOX_LOKI_TIMEOUT",), 10)
+        self.cache_timeout = _read_netbox_setting(self.config, "cache_timeout", ("NETBOX_LOKI_CACHE_TIMEOUT",), 60)
+        self.verify_tls = _read_netbox_setting(self.config, "verify_tls", ("NETBOX_LOKI_VERIFY_TLS",), True)
+
+    def _get_headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "X-Requested-By": "NetBox-Loki-Plugin",
+        }
+        tenant = str(
+            _read_netbox_setting(
+                self.config,
+                "loki_tenant",
+                ("NETBOX_LOKI_TENANT", "LOKI_TENANT", "LOKI_X_SCOPE_ORGID"),
+                "docker",
+            )
+        ).strip()
+        bearer = str(
+            _read_netbox_setting(
+                self.config,
+                "loki_bearer_token",
+                ("NETBOX_LOKI_BEARER_TOKEN", "LOKI_BEARER_TOKEN"),
+                "",
+            )
+        ).strip()
+        if tenant:
+            headers["X-Scope-OrgID"] = tenant
+        if bearer:
+            headers["Authorization"] = f"Bearer {bearer}"
+        return headers
+
+    def _get_auth(self) -> tuple[str, str] | None:
+        username = str(
+            _read_netbox_setting(
+                self.config,
+                "loki_username",
+                ("NETBOX_LOKI_USERNAME", "LOKI_USERNAME"),
+                "",
+            )
+        ).strip()
+        password = _read_netbox_setting(
+            self.config,
+            "loki_password",
+            ("NETBOX_LOKI_PASSWORD", "LOKI_PASSWORD"),
+            "",
+        )
+        if username:
+            return (username, password)
+        return None
+
+    def _request(
+        self,
+        *,
+        endpoint: str,
+        params: dict[str, Any],
+    ) -> dict[str, Any]:
+        response = requests.get(
+            f"{self.base_url}{endpoint}",
+            params=params,
+            headers=self._get_headers(),
+            auth=self._get_auth(),
+            timeout=self.timeout,
+            verify=self.verify_tls,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    @staticmethod
+    def _ns_timestamp(value: datetime) -> str:
+        return str(int(value.timestamp() * 1_000_000_000))
+
+    @staticmethod
+    def _format_timestamp(raw_value: str) -> str:
+        try:
+            as_int = int(raw_value)
+            return datetime.fromtimestamp(as_int / 1_000_000_000, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+        except (TypeError, ValueError, OSError):
+            return raw_value
+
+    def _default_selector_parts(self) -> list[str]:
+        parts: list[str] = []
+
+        job = self.config.get("loki_job", "").strip()
+        if job:
+            parts.append(f'job="{self._escape_label_value(job)}"')
+
+        extra_selector = self.config.get("stream_selector", "").strip()
+        if extra_selector:
+            parts.append(extra_selector)
+
+        return parts
+
+    @staticmethod
+    def _escape_label_value(value: str) -> str:
+        return value.replace("\\", "\\\\").replace('"', '\\"')
+
+    def _build_value_matcher(self, value: str) -> tuple[str, str]:
+        if self.config.get("use_regex_matching", True):
+            if "." in value:
+                return "=~", self._escape_label_value(f"^{re.escape(value)}$")
+            return "=~", self._escape_label_value(f"^{re.escape(value)}(?:\\..+)?$")
+        return "=", self._escape_label_value(value)
+
+    def _build_selector(self, *, label_name: str | None = None, value: str | None = None) -> str:
+        selector_parts = self._default_selector_parts()
+        effective_label = label_name or self.config.get("device_label", "routerboard")
+
+        if value:
+            operator, matcher = self._build_value_matcher(value)
+            selector_parts.append(f'{effective_label}{operator}"{matcher}"')
+
+        return "{" + ",".join(selector_parts) + "}"
+
+    def search_logs(
+        self,
+        value: str | None = None,
+        *,
+        time_range: int | None = None,
+        limit: int | None = None,
+        label_name: str | None = None,
+    ) -> dict[str, Any]:
+        time_range = int(time_range or self.config.get("time_range", 3600))
+        limit = int(limit or self.config.get("log_limit", 100))
+        selector = self._build_selector(label_name=label_name, value=value)
+
+        cache_key = f"loki_logs::{selector}::{time_range}::{limit}"
+        cached = cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        end = datetime.now(timezone.utc)
+        start = end - timedelta(seconds=time_range)
+        query = selector
+
+        try:
+            payload = self._request(
+                endpoint="/loki/api/v1/query_range",
+                params={
+                    "query": query,
+                    "start": self._ns_timestamp(start),
+                    "end": self._ns_timestamp(end),
+                    "limit": limit,
+                    "direction": "backward",
+                },
+            )
+            result = self._parse_log_response(payload, query=query, time_range=time_range)
+            cache.set(cache_key, result, self.cache_timeout)
+            return result
+        except requests.RequestException as exc:
+            logger.warning("Loki request failed for query %s: %s", query, exc)
+            return {"error": str(exc), "messages": [], "query": query, "time_range": time_range}
+
+    def _parse_log_response(self, payload: dict[str, Any], *, query: str, time_range: int) -> dict[str, Any]:
+        messages: list[dict[str, Any]] = []
+        data = payload.get("data", {})
+
+        for stream in data.get("result", []):
+            labels = stream.get("stream", {})
+            for timestamp, line in stream.get("values", []):
+                messages.append(
+                    {
+                        "message": {
+                            "timestamp": timestamp,
+                            "timestamp_display": self._format_timestamp(timestamp),
+                            "message": line,
+                            "source": self._derive_source(labels),
+                            "job": labels.get("job", ""),
+                            "severity": self._derive_severity(labels, line),
+                            "labels": labels,
+                        }
+                    }
+                )
+
+        messages.sort(key=lambda item: item["message"]["timestamp"], reverse=True)
+
+        return {
+            "messages": messages,
+            "total_results": len(messages),
+            "query": query,
+            "time_range": time_range,
+        }
+
+    def _derive_source(self, labels: dict[str, str]) -> str:
+        configured_label = self.config.get("device_label", "routerboard")
+        for key in (configured_label, "host", "hostname", "instance", "source"):
+            value = labels.get(key)
+            if value:
+                return value
+        return ""
+
+    @staticmethod
+    def _derive_severity(labels: dict[str, str], line: str) -> str:
+        label_severity = labels.get("severity") or labels.get("level")
+        if label_severity:
+            return str(label_severity)
+
+        match = re.search(r":(?P<severity>[A-Za-z][A-Za-z0-9_-]{1,31}):", line)
+        if match:
+            raw = match.group("severity")
+            return raw[:1].upper() + raw[1:]
+
+        return ""
+
+    @staticmethod
+    def _primary_ip_value(primary_ip: Any) -> str | None:
+        if not primary_ip:
+            return None
+        address = getattr(primary_ip, "address", None)
+        if not address:
+            return None
+        return str(address).split("/")[0]
+
+    def _search_with_fallback(
+        self,
+        *,
+        name: str,
+        time_range: int | None,
+        fallback_ip: str | None = None,
+        label_name: str | None = None,
+    ) -> dict[str, Any]:
+        result = self.search_logs(name, time_range=time_range, label_name=label_name)
+        result["search_type"] = "name"
+
+        if result.get("messages") or not self.config.get("fallback_to_ip", True) or not fallback_ip:
+            return result
+
+        fallback = self.search_logs(fallback_ip, time_range=time_range, label_name=label_name)
+        fallback["search_type"] = "ip"
+        return fallback
+
+    def get_logs_for_device(self, device: Any, *, time_range: int | None = None) -> dict[str, Any]:
+        hostname = device.virtual_chassis.name if getattr(device, "virtual_chassis", None) else device.name
+        fallback_ip = self._primary_ip_value(getattr(device, "primary_ip", None))
+        result = self._search_with_fallback(
+            name=hostname,
+            time_range=time_range,
+            fallback_ip=fallback_ip,
+        )
+        result["device_name"] = device.name
+        return result
+
+    def get_logs_for_vm(self, vm: Any, *, time_range: int | None = None) -> dict[str, Any]:
+        fallback_ip = self._primary_ip_value(getattr(vm, "primary_ip", None))
+        result = self._search_with_fallback(
+            name=vm.name,
+            time_range=time_range,
+            fallback_ip=fallback_ip,
+        )
+        result["vm_name"] = vm.name
+        return result
+
+    def get_logs_for_endpoint(self, endpoint: Any, *, time_range: int | None = None) -> dict[str, Any]:
+        search_value = endpoint.name or str(endpoint.mac_address)
+        fallback_ip = self._primary_ip_value(getattr(endpoint, "primary_ip", None))
+        result = self._search_with_fallback(
+            name=search_value,
+            time_range=time_range,
+            fallback_ip=fallback_ip,
+        )
+        result["endpoint_name"] = search_value
+        return result
+
+    def _instant_scalar_query(self, query: str) -> int:
+        payload = self._request(
+            endpoint="/loki/api/v1/query",
+            params={
+                "query": query,
+                "time": self._ns_timestamp(datetime.now(timezone.utc)),
+            },
+        )
+        result = payload.get("data", {}).get("result", [])
+        if not result:
+            return 0
+
+        value = result[0].get("value", [None, "0"])
+        try:
+            return int(float(value[1]))
+        except (TypeError, ValueError, IndexError):
+            return 0
+
+    @staticmethod
+    def _duration_expr(time_range: int) -> str:
+        if time_range % 86400 == 0:
+            return f"{time_range // 86400}d"
+        if time_range % 3600 == 0:
+            return f"{time_range // 3600}h"
+        if time_range % 60 == 0:
+            return f"{time_range // 60}m"
+        return f"{time_range}s"
+
+    def get_log_summary(self, time_range: int = 3600, cache_timeout: int = 120) -> dict[str, Any]:
+        cache_key = f"loki_log_summary::{time_range}"
+        cached = cache.get(cache_key)
+        if cached is not None:
+            cached["cached"] = True
+            return cached
+
+        selector = self._build_selector()
+        range_expr = self._duration_expr(time_range)
+
+        try:
+            total = self._instant_scalar_query(f"sum(count_over_time({selector}[{range_expr}]))")
+            errors = self._instant_scalar_query(
+                f'sum(count_over_time({selector} |~ "(?i)error|err|critical|fatal"[{range_expr}]))'
+            )
+            warnings = self._instant_scalar_query(
+                f'sum(count_over_time({selector} |~ "(?i)warn|warning"[{range_expr}]))'
+            )
+        except requests.RequestException as exc:
+            logger.warning("Loki summary query failed: %s", exc)
+            return {"error": str(exc)}
+
+        summary = {
+            "total": total,
+            "errors": errors,
+            "warnings": warnings,
+            "cached": False,
+        }
+        cache.set(cache_key, summary, cache_timeout)
+        return summary
+
+
+LokiClient = LokiClient
+
+_client: LokiClient | None = None
+
+
+def get_client() -> LokiClient:
+    """Get or create the Loki client singleton."""
+    global _client
+    if _client is None:
+        _client = LokiClient()
+    return _client

netbox_loki/migrations/0001_initial.py

@@ -0,0 +1,20 @@
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="GraylogPermission",
+            fields=[],
+            options={
+                "managed": False,
+                "default_permissions": (),
+                "permissions": (("configure_graylog", "Can configure Graylog plugin settings"),),
+            },
+        ),
+    ]

netbox_loki/migrations/0002_rename_model.py

@@ -0,0 +1,15 @@
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("netbox_graylog", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.RenameModel(
+            old_name="GraylogPermission",
+            new_name="Graylog",
+        ),
+    ]