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",
    }

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.

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, or UNKNOWN.

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)

cpanm HealthCheck

perl -MCPAN -e shell
install HealthCheck