rest: add .../avail endpoint for hosts / services

sni · Sep 5, 2023 · d6a7431 · d6a7431
1 parent 682e4e7
commit d6a7431
Show file tree

Hide file tree

Showing 8 changed files with 157 additions and 12 deletions.
diff --git a/Changes b/Changes
@@ -7,6 +7,8 @@ next:
           - fix requesting unknown columns (#1301)
           - Reports:
             - fix missing subject in report mails
+          - Rest
+            - add .../avail endpoint for hosts / services
 
 3.08.3   Fri Jul 21 13:06:06 CEST 2023
           - improve landing page performance

diff --git a/docs/documentation/rest.asciidoc b/docs/documentation/rest.asciidoc
@@ -1043,6 +1043,34 @@ alias for /hosts?name=<name>
 lists alerts for given host.
 alias for /logs?type[~]=^(HOST|SERVICE) ALERT&host_name=<name>
 
+=== GET /hosts/<name>/availability
+
+list availability for this host.
+
+Optional arguments:
+
+  * timeperiod        - last24hours | lastmonth | thismonth | ...
+  * start             - unix timestamp
+  * end               - unix timestamp
+  * withdowntimes     - 0/1 wheter downtimes should count as outages
+  * includesoftstates - 0/1 wheter soft states should be used as well
+
+[options="header"]
+|===========================================
+|Attribute                         | Description
+|scheduled_time_down               | total seconds in state down (during downtimes)
+|scheduled_time_indeterminate      | total seconds unknown (during downtimes)
+|scheduled_time_unreachable        | total seconds in state unreachable (during downtimes)
+|scheduled_time_up                 | total seconds in state up (during downtimes)
+|time_down                         | total seconds in state down
+|time_indeterminate_nodata         | total seconds without any data
+|time_indeterminate_notrunning     | total seconds during core not running
+|time_indeterminate_outside_timeperiod | total seconds outside the given timeperiod
+|time_unreachable                  | total seconds in state unreachable
+|time_up                           | total seconds in state up
+|===========================================
+
+
 === POST /hosts/<name>/cmd/...
 
 external commands are documented in detail on a separate commands page.
@@ -1410,6 +1438,37 @@ there is an alias /services.
 lists services for given host and name.
 alias for /services?host_name=<host_name>&description=<service>
 
+=== GET /services/<host>/<service>/availability
+
+list of outages for this service.
+
+Optional arguments:
+
+  * type              - both | hosts | services
+  * timeperiod        - last24hours | lastmonth | thismonth | ...
+  * start             - unix timestamp
+  * end               - unix timestamp
+  * withdowntimes     - 0/1 wheter downtimes should count as outages
+  * includesoftstates - 0/1 wheter soft states should be used as well
+
+[options="header"]
+|===========================================
+|Attribute                         | Description
+|scheduled_time_critical           | total seconds in state critical (during downtimes)
+|scheduled_time_indeterminate      | total seconds unknown (during downtimes)
+|scheduled_time_ok                 | total seconds in state ok (during downtimes)
+|scheduled_time_unknown            | total seconds in state unknown (during downtimes)
+|scheduled_time_warning            | total seconds in state warning (during downtimes)
+|time_critical                     | total seconds in state critical
+|time_indeterminate_nodata         | total seconds without any data
+|time_indeterminate_notrunning     | total seconds during core not running
+|time_indeterminate_outside_timeperiod | total seconds outside the given timeperiod
+|time_ok                           | total seconds in state ok
+|time_unknown                      | total seconds in state unknown
+|time_warning                      | total seconds in state warning
+|===========================================
+
+
 === POST /services/<host>/<service>/cmd/...
 
 external commands are documented in detail on a separate commands page.

diff --git a/docs/manpages/nagexp.3 b/docs/manpages/nagexp.3
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "nagexp 3"
-.TH nagexp 3 "2023-03-21" "perl v5.32.1" "User Contributed Perl Documentation"
+.TH nagexp 3 "2023-09-05" "perl v5.36.0" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l

diff --git a/docs/manpages/nagimp.3 b/docs/manpages/nagimp.3
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "nagimp 3"
-.TH nagimp 3 "2023-03-21" "perl v5.32.1" "User Contributed Perl Documentation"
+.TH nagimp 3 "2023-09-05" "perl v5.36.0" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l

diff --git a/docs/manpages/naglint.3 b/docs/manpages/naglint.3
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "naglint 3"
-.TH naglint 3 "2023-03-21" "perl v5.32.1" "User Contributed Perl Documentation"
+.TH naglint 3 "2023-09-05" "perl v5.36.0" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l

diff --git a/docs/manpages/thruk.3 b/docs/manpages/thruk.3
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "thruk 3"
-.TH thruk 3 "2023-07-12" "perl v5.32.1" "User Contributed Perl Documentation"
+.TH thruk 3 "2023-09-05" "perl v5.36.0" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l

diff --git a/lib/Thruk/Controller/Rest/V1/outages.pm b/lib/Thruk/Controller/Rest/V1/outages.pm
@@ -73,6 +73,29 @@ sub _rest_get_host_outages {
     return($outages);
 }
 
+##########################################################
+# REST PATH: GET /hosts/<name>/availability
+# list availability for this host.
+#
+# Optional arguments:
+#
+#   * timeperiod        - last24hours | lastmonth | thismonth | ...
+#   * start             - unix timestamp
+#   * end               - unix timestamp
+#   * withdowntimes     - 0/1 wheter downtimes should count as outages
+#   * includesoftstates - 0/1 wheter soft states should be used as well
+Thruk::Controller::rest_v1::register_rest_path_v1('GET', qr%^/hosts?/([^/]+)/availability$%mx, \&_rest_get_host_availability);
+sub _rest_get_host_availability {
+    my($c, undef, $host) = @_;
+    $c->req->parameters->{'type'} = "hosts";
+    $c->req->parameters->{'host'} = $host;
+    my $avail = _rest_availability($c);
+    delete $c->req->parameters->{'host'};
+    _rest_outages_clean_param($c);
+    return($avail->{'avail'}->{'hosts'}->{$host});
+}
+
+
 ##########################################################
 # REST PATH: GET /hostgroups/<name>/outages
 # list of outages for this hostgroup.
@@ -147,6 +170,31 @@ sub _rest_get_service_outages {
     return($outages);
 }
 
+##########################################################
+# REST PATH: GET /services/<host>/<service>/availability
+# list of outages for this service.
+#
+# Optional arguments:
+#
+#   * type              - both | hosts | services
+#   * timeperiod        - last24hours | lastmonth | thismonth | ...
+#   * start             - unix timestamp
+#   * end               - unix timestamp
+#   * withdowntimes     - 0/1 wheter downtimes should count as outages
+#   * includesoftstates - 0/1 wheter soft states should be used as well
+Thruk::Controller::rest_v1::register_rest_path_v1('GET', qr%^/services?/([^/]+)/([^/]+)/availability$%mx, \&_rest_get_service_availability);
+sub _rest_get_service_availability {
+    my($c, undef, $host, $service) = @_;
+    $c->req->parameters->{'type'} = "services";
+    $c->req->parameters->{'host'}    = $host;
+    $c->req->parameters->{'service'} = $service;
+    my $avail = _rest_availability($c);
+    delete $c->req->parameters->{'host'};
+    delete $c->req->parameters->{'service'};
+    _rest_outages_clean_param($c);
+    return($avail->{'avail'}->{'services'}->{$host}->{$service});
+}
+
 ##########################################################
 # REST PATH: GET /servicegroups/<name>/outages
 # list of outages for this servicegroup.
@@ -170,10 +218,10 @@ sub _rest_get_servicegroup_outages {
 }
 
 ##########################################################
-sub _rest_outages {
+sub _rest_availability_prep {
     my($c) = @_;
     if($c->req->parameters->{'timeperiod'} && ($c->req->parameters->{'start'} || $c->req->parameters->{'end'})) {
-        return({
+        return(undef, undef, {
                 'message'     => 'use either timeperiod or start/end, not both.',
                 'code'        => 400,
                 'failed'      => Cpanel::JSON::XS::true,
@@ -182,13 +230,45 @@ sub _rest_outages {
 
     my($hostfilter, $servicefilter) = Thruk::Utils::Status::do_filter($c, undef, undef, 1);
     if($c->stash->{'has_error'}) {
-        return({
+        return(undef, undef, {
                 'message'     => 'error in filter',
                 'code'        => 400,
                 'failed'      => Cpanel::JSON::XS::true,
         });
     }
 
+    return($hostfilter, $servicefilter);
+}
+
+##########################################################
+sub _rest_availability {
+    my($c) = @_;
+
+    my($hostfilter, $servicefilter, $err) = _rest_availability_prep($c);
+    return $err if $err;
+
+    if($c->req->parameters->{'type'} eq "services") {
+        $c->req->parameters->{'s_filter'} = $servicefilter;
+    } else {
+        $c->req->parameters->{'h_filter'} = $hostfilter;
+    }
+
+    $c->req->parameters->{'t1'} = $c->req->parameters->{'start'};
+    $c->req->parameters->{'t2'} = $c->req->parameters->{'end'};
+
+    require Thruk::Utils::Avail;
+    my $avail = Thruk::Utils::Avail::calculate_availability($c);
+
+    return($avail);
+}
+
+##########################################################
+sub _rest_outages {
+    my($c) = @_;
+
+    my($hostfilter, $servicefilter, $err) = _rest_availability_prep($c);
+    return $err if $err;
+
     if(!$c->req->parameters->{'type'}) {
         $c->req->parameters->{'type'} = "both";
     }

diff --git a/t/300-controller_rest_v1.t b/t/300-controller_rest_v1.t
@@ -7,7 +7,7 @@ use Thruk::Utils::IO ();
 
 BEGIN {
     plan skip_all => 'backends required' if(!-s 'thruk_local.conf' and !defined $ENV{'PLACK_TEST_EXTERNALSERVER_URI'});
-    plan tests => 532;
+    plan tests => 564;
 }
 
 BEGIN {
@@ -48,6 +48,8 @@ my $list_pages = [
     '/servicegroups',
     '/services',
     '/services/outages',
+    '/services/'.$host.'/'.$service,
+    '/services/'.$host.'/'.$service.'/outages',
     '/timeperiods',
     '/lmd/sites',
     '/thruk/bp',
@@ -67,9 +69,11 @@ my $hash_pages = [
     '/checks/stats',
     '/hosts/stats',
     '/hosts/totals',
+    '/hosts/'.$host.'/availability',
     '/processinfo/stats',
     '/services/stats',
     '/services/totals',
+    '/services/'.$host.'/'.$service.'/availability',
     '/thruk',
     '/thruk/config',
     '/thruk/stats',