NAME
HealthCheck::Diagnostic - A base clase for writing health check diagnositics
VERSION
version v1.9.1
SYNOPSIS
package HealthCheck::Diagnostic::Sample;
use parent 'HealthCheck::Diagnostic';
# Required implementation of the check
# or you can override the 'check' method and avoid the
# automatic call to 'summarize'
sub run {
my ( $class_or_self, %params ) = @_;
# will be passed to 'summarize' by 'check'
return { %params, status => 'OK' };
}
You can then either instantiate an instance and run the check.
my $diagnostic = HealthCheck::Diagnostic::Sample->new( id => 'my_id' );
my $result = $diagnostic->check;
Or as a class method.
my $result = HealthCheck::Diagnostic::Sample->check();
Set runtime
to a truthy value in the params for check and the time spent checking will be returned in the results.
my $result = HealthCheck::Diagnostic::Sample->check( runtime => 1 );
DESCRIPTION
A base class for writing Health Checks. Provides some helpers for validation of results returned from the check.
This module does not require that an instance is created to run checks against. If your code requires an instance, you will need to verify that yourself.
Results returned by these checks should correspond to the GSG Health Check Standard.
Implementing a diagnostic should normally be done in run to allow use of the helper features that "check" provides.
REQUIRED METHODS
run
sub run {
my ( $class_or_self, %params ) = @_;
return { %params, status => 'OK' };
}
A subclass must either implement a run
method, which will be called by "check" have its return value passed through "summarize", or override check
and handle all validation itself.
See the "check" method documentation for suggestions on when it might be overridden.
METHODS
new
my $diagnostic
= HealthCheck::Diagnostic::Sample->new( id => 'my_diagnostic' );
ATTRIBUTES
Attributes set on the object created will be copied into the result by "summarize", without overriding anything already set in the result.
- collapse_single_result
-
If truthy, will collapse a single sub-result into the current result, with the child result overwriting the values from the parent.
For example:
{ id => "my_id", label => "My Label", runbook => "https://grantstreetgroup.github.io/HealthCheck.html", results => [ { label => "Sub Label", status => "OK", } ] }
Collapses to:
{ id => "my_id", label => "Sub Label", runbook => "https://grantstreetgroup.github.io/HealthCheck.html", status => "OK", }
-
An arrayref used as the default set of tags for any checks that don't override them.
Any other parameters are included in the "Result" hashref returned.
Some recommended things to include are:
- id
-
The unique id for this check.
- label
-
A human readable name for this check.
- runbook
-
A runbook link to help troubleshooting if the status is not OK.
collapse_single_result
Read only accessor for the /collapse_single_result
attribute.
tags
Read only accessor that returns the list of tags registered with this object.
id
Read only accessor that returns the id registered with this object.
label
Read only accessor that returns the label registered with this object.
runbook
Read only accessor that returns the runbook registered with this object.
check
my %results = %{ $diagnostic->check(%params) }
This method is what is normally called by the HealthCheck runner, but this version expects you to implement a "run" method for the body of your diagnostic. This thin wrapper makes sure %params
is an even-sided list (possibly unpacking a hashref) before passing it to "run", trapping any exceptions, and passing the return value through "summarize" unless a falsy summarize_result
parameter is passed.
This could be used to validate parameters or to modify the the return value in some way.
sub check {
my ( $self, @params ) = @_;
# Require check as an instance method
croak("check cannot be called as a class method") unless ref $self;
# Allow either a hashref or even-sized list of params
my %params = @params == 1 && ( ref $params[0] || '' ) eq 'HASH'
? %{ $params[0] } : @params;
# Validate any required parameters and that they look right.
my $required_param = $params{required} || $self->{required};
return {
status => 'UNKNOWN',
info => 'The "required" parameter is required',
} unless $required_param and ref $required_param == 'HASH';
# Calls $self->run and then passes the result through $self->summarize
my $res = $self->SUPER::check( %params, required => $required_param );
# Modify the result after it has been summarized
delete $res->{required};
# and return it
return $res;
}
summarize
%result = %{ $diagnostic->summarize( \%result ) };
Validates, pre-formats, and returns the result
so that it is easily usable by HealthCheck.
The attributes id
, label
, runbook
, and tags
get copied from the $diagnostic
into the result
if they exist in the former and not in the latter.
The status
and info
are summarized when we have multiple results
in the result
. All of the info
values get appended together. One status
value is selected from the list of status
values.
Used by "check".
Carps a warning if validation fails on several keys, and sets the status
from OK
to UNKNOWN
.
- status
-
Expects it to be one of
OK
,WARNING
,CRITICAL
, orUNKNOWN
.Also carps if it does not exist.
- results
-
Complains if it is not an arrayref.
- id
-
Complains if the id contains anything but lowercase ascii letters, numbers, and underscores.
- timestamp
-
Expected to look like an RFC 3339 timestamp which is a more strict subset of an ISO8601 timestamp.
Modifies the passed in hashref in-place.
DEPENDENCIES
Perl 5.10 or higher.
CONFIGURATION AND ENVIRONMENT
None
SEE ALSO
Writing a HealthCheck::Diagnostic
AUTHOR
Grant Street Group <developers@grantstreet.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2017 - 2024 by Grant Street Group.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)