HealthCheck - A health check for your code
version v1.9.1
use HealthCheck;
# a check can return a hashref containing anything at all,
# however some values are special.
# See the HealthCheck Standard for details.
sub my_check {
return {
anything => "at all",
id => "my_check",
status => 'WARNING',
};
}
my $checker = HealthCheck->new(
id => 'main_checker',
label => 'Main Health Check',
runbook => 'https://grantstreetgroup.github.io/HealthCheck.html',
tags => [qw( fast cheap )],
checks => [
sub { return { id => 'coderef', status => 'OK' } },
'my_check', # Name of a method on caller
],
);
my $other_checker = HealthCheck->new(
id => 'my_health_check',
label => "My Health Check",
runbook => 'https://grantstreetgroup.github.io/HealthCheck.html',
tags => [qw( cheap easy )],
other => "Other details to pass to the check call",
)->register(
'My::Checker', # Name of a loaded class that ->can("check")
My::Checker->new, # Object that ->can("check")
);
# It's possible to add ids, labels, and tags to your checks
# and they will be copied to the Result.
$other_checker->register( My::Checker->new(
id => 'my_checker',
label => 'My Checker',
runbook => 'https://grantstreetgroup.github.io/HealthCheck.html',
tags => [qw( cheap copied_to_the_result )],
) );
# You can add HealthCheck instances as checks
# You could add a check to itself to create an infinite loop of checks.
$checker->register( $other_checker );
# A hashref of the check config
# This whole hashref is passed as an argument
# to My::Checker->another_check
$checker->register( {
invocant => 'My::Checker', # to call the "check" on
check => 'another_check', # name of the check method
runbook => 'https://grantstreetgroup.github.io/HealthCheck.html',
tags => [qw( fast easy )],
more_params => 'anything',
} );
my @tags = $checker->tags; # returns fast, cheap
my %result = %{ $checker->check( tags => ['cheap'] ) };
# OR run the opposite checks
%result = %{ $checker->check( tags => ['!cheap'] ) };
# A checker class or object just needs to have either
# a check method, which is used by default,
# or another method as specified in a hash config.
package My::Checker;
# Optionally subclass HealthCheck::Diagnostic
use parent 'HealthCheck::Diagnostic';
# and provide a 'run' method, the Diagnostic base class will
# pass your results through the 'summarize' helper that
# will add warnings about invalid values as well as
# summarizing multiple results.
sub run {
return {
id => ( ref $_[0] ? "object_method" : "class_method" ),
status => "WARNING",
};
}
# Any checks *must* return a valid "Health Check Result" hashref.
# You can add your own check that doesn't call 'summarize'
# or, overload the 'check' helper in the parent class.
sub another_check {
my ($self, %params) = @_;
return {
id => 'another_check',
label => 'A Super custom check',
runbook => 'https://grantstreetgroup.github.io/HealthCheck.html',
status => ( $params{more_params} eq 'fine' ? "OK" : "CRITICAL" ),
};
}
%result will be from the subset of checks run due to the tags.
$checker->check(tags => ['cheap']);
id => "main_checker",
label => "Main Health Check",
runbook => 'https://grantstreetgroup.github.io/HealthCheck.html',
tags => [ "fast", "cheap" ],
status => "WARNING",
results => [
{ id => "coderef",
status => "OK",
tags => [ "fast", "cheap" ] # inherited
},
{ anything => "at all",
id => "my_check",
status => "WARNING",
tags => [ "fast", "cheap" ] # inherited
},
{ id => "my_health_check",
label => "My Health Check",
tags => [ "cheap", "easy" ],
status => "WARNING",
results => [
{ id => "class_method",
tags => [ "cheap", "easy" ],
status => "WARNING",
},
{ id => "object_method",
tags => [ "cheap", "easy" ],
status => "WARNING",
},
{ id => "object_method_1",
label => "My Checker",
tags => [ "cheap", "copied_to_the_result" ],
status => "WARNING",
}
],
}
],
There is also runtime support,
which can be enabled by adding a truthy runtime param to the check.
$checker->check( tags => [ 'easy', '!fast' ], runtime => 1 );
id => "my_health_check",
label => "My Health Check",
runtime => "0.000",
runbook => 'https://grantstreetgroup.github.io/HealthCheck.html',
tags => [ "cheap", "easy" ],
status => "WARNING",
results => [
{ id => "class_method",
runtime => "0.000",
tags => [ "cheap", "easy" ],
status => "WARNING",
},
{ id => "object_method",
runtime => "0.000",
tags => [ "cheap", "easy" ],
status => "WARNING",
}
],
Allows you to create callbacks that check the health of your application and return a status result.
There are several things this is trying to enable:
- A fast HTTP endpoint that can be used to verify that a web app can serve traffic. To this end, it may be useful to use the runtime support option, available in HealthChecks::Diagnostic.
- A more complete check that verifies all the things work after a deployment.
- The ability for a script, such as a cronjob, to verify that it's dependencies are available before starting work.
- Different sorts of monitoring checks that are defined in your codebase.
Results returned by these checks should correspond to the GSG Health Check Standard.
You may want to use HealthCheck::Diagnostic to simplify writing your check slightly.
my $checker = HealthCheck->new( id => 'my_checker' );
-
checks
An arrayref that is passed to "register" to initialize checks.
-
tags
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.
$checker->register({
invocant => $class_or_object,
check => $method_on_invocant_or_coderef,
more => "any other params are passed to the check",
});
Takes a list or arrayref of check definitions to be added to the object.
Each registered check must return a valid GSG Health Check response, either as a hashref or an even-sized list. See the GSG Health Check Standard (linked in "DESCRIPTION") for the fields that checks should return.
Rather than having to always pass in the full hashref definition, several common cases are detected and used to fill out the check.
-
coderef
If passed a coderef, this will be called as the
checkwithout aninvocant. -
object
If a blessed object is passed in and it has a
checkmethod, use that for thecheck, otherwise throw an exception. -
string
If a string is passed in, check if it is the name of a loaded class that has a
checkmethod, and if so use it as theinvocantwith the method as thecheck. Otherwise if our caller has a method with this name, the caller becomes theinvocantand this becomes thecheck, otherwise throws an exception. -
full hashref of params
The full hashref can consist of a
checkkey that the above heuristics are applied, or include aninvocantkey that is used as either anobjectorclass name. With theinvocantspecified, the now optionalcheckkey defaults to "check" and is used as the method to call oninvocant.All attributes other than
invocantandcheckare passed to the check.
my %results = %{ $checker->check(%params) }
Calls all of the registered checks and returns a hashref of the results of
processing the checks passed through "summarize" in HealthCheck::Diagnostic.
Passes the "full hashref of params" as an even-sized list to the check,
without the invocant or check keys.
This hashref is shallow merged with and duplicate keys overridden by
the %params passed in.
If there is both an invocant and check in the params,
it the check is called as a method on the invocant,
otherwise check is used as a callback coderef.
If only a single check is registered,
the results from that check are merged with, and will override
the "ATTRIBUTES" set on the object instead of being put in
a results arrayref.
Throws an exception if no checks have been registered.
Main implementation of the checker is here.
Passes summarize_result => 0 to each registered check
unless overridden to avoid running summarize multiple times.
See "check" in HealthCheck::Diagnostic.
Read-only accessor that returns the list of 'top-level' tags registered with this object. Sub-check tags are not included - only those which will result in checks being run when passed to "check" on the given object.
These methods may be useful for subclassing, but are not intended for general use.
my $bool = $checker->should_run( \%check, tags => ['apple', '!banana'] );
Takes a check definition hash and paramters and returns true if the check should be run. Used by "check" to determine which checks to run.
Supported parameters:
-
tags
Tags can be either "positive" or "negative". A negative tag is indicated by a leading
!. A check is run if its tags match any of the passed in positive tags and none of the negative ones. If no tags are passed in, all checks will be run.If the
invocantcan('tags')and there are no tags in the "full hashref of params" then the return value of that method is used.If a check has no tags defined, will use the default tags defined when the object was created.
Perl 5.10 or higher.
None
The GSG Health Check Standard.
Grant Street Group developers@grantstreet.com
This software is Copyright (c) 2017 - 2024 by Grant Street Group.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)