DOCSEARCHbyAlgolia
Submit Docs

Liip Monitor Bundle Documentation

repository·2.x·Indexed 19 days ago

https://github.com/liip/liipmonitorbundle

A framework for running application-specific health checks in Symfony applications. It enables verification of application logic, PHP extensions, and connectivity to services like Redis or Memcache. Features include a REST API, CLI commands for execution and listing, custom check and reporter registration via Symfony services, and integration with Nagios using provided Perl and Python scripts.

Tokens
6.2K
Snippets
19
Records
22
Agent score
67%

What's inside Liip Monitor Bundle

  1. Group health checks by environment

    2.x

    You can organize checks into groups (e.g., default, cron, app_server) to run only relevant checks in specific environments.

    1. Define groups for built-in checks

    In your config.yml:

    liip_monitor:
    default_group: default
    checks:
        groups:
            default:
                php_extensions: [apc, xdebug]
            cron:
                php_extensions: [redis]

    2. Define groups for custom tagged services

    Add the group attribute to the service tag:

    services:
    monitor.check.php_extensions:
        class: Acme\HelloBundle\Check\PhpExtensionsCheck
        tags:
            - { name: liip_monitor.check, alias: php_extensions, group: cron }
            - { name: liip_monitor.check, alias: php_extensions, group: app_server }

    Note: If using autoconfigure, you must set autoconfigure: false to manually assign groups via tags.

    3. Execute specific groups via CLI

    Use the --group option:

    bin/console monitor:health --group=app_server

    Use --all to run all checks across all groups.

  2. How health checks work in Liip Monitor Bundle

    2.x

    The bundle runs a series of application-related health checks. Each check is a class implementing CheckInterface::check, which must return a CheckResult object.

    To be discovered by the health check runner, checks must be defined as Symfony services and tagged with liip_monitor.check.

    Key concepts:

    • Discovery: The runner finds checks via the liip_monitor.check tag.
    • Identification: You can use an optional alias in the tag to define a short ID for the check. If no alias is provided, the full service ID is used.
    • Execution: Checks can be run via Symfony CLI commands or a REST API returning JSON.
    • Grouping: Checks can be organized into groups (e.g., default, cron, app_server) to allow running specific subsets of checks based on the environment.

  3. Connect Nagios checks to a Host

    2.x

    After defining the check_symfony_health command, you must attach it to a service and a host within Nagios.

    1. Define a Service: Create a service that uses the check_symfony_health command.
    2. Define a Host: Create a host and assign it to a hostgroup (e.g., Symfony2) so the service can be applied to it.
    define service{
     hostgroup_name         Symfony2
     service_description    Symfony2 health check
     check_command          check_symfony_health
     use                    generic-service
}

define host{
    use              web-host
    host_name        www.myhost.com
    address          8.8.8.4
    hostgroups       Symfony2
}

  4. Integrate with Nagios using the Perl script

    2.x

    The bundle provides a Perl-based Nagios check located in the Resources/scripts directory. This script requires the following CPAN modules: Getopt::Std, WWW::Mechanize, and JSON.

    Command Configuration

    Define a command in your Nagios configuration. You can target the host via the -H flag or a specific URL via the -A flag (note: -A and -H cannot be used together).

    Basic usage (Hostname):

    define command{
    command_name    check_symfony_health
    command_line    $USER1$/check_symfony2.pl -H $HOSTNAME$
}

    Specific URL usage:

    define command{
    command_name    check_symfony_health
    command_line    $USER1$/check_symfony2.pl -A https://mysite.org/monitor/health/run
}

    Authentication and Thresholds

    • Authentication: Use -u <username> and -p <password> together.
    • Thresholds: Use -w <warning_level> and -c <critical_level>.

    Example with Authentication and Thresholds:

    define command{
    command_name    check_symfony_health
    command_line    $USER1$/check_symfony2.pl -H $HOSTNAME$ -u username -p password -w 1 -c 2
}

  5. Migrate routing configuration to YAML for Symfony 8

    2.x

    In version 2.25.0, support for XML routing was introduced for Symfony 8 compatibility, but the routing.xml file is slated for removal in the next major version. If you are using Symfony 8, you must update your routing configuration to reference the YAML version of the bundle's routing file instead of the XML version. This change only applies if you are explicitly referencing the bundle's routing resource in your configuration.

    # Before
_monitor:
    resource: "@LiipMonitorBundle/Resources/config/routing.xml"

# After
_monitor:
    resource: "@LiipMonitorBundle/Resources/config/routing.yaml"

  6. Install Liip Monitor Bundle

    2.x

    Install the bundle using Composer and register it in your Symfony application.

    1. Install via Composer:
    composer require liip/monitor-bundle
    1. Register the bundle in AppKernel.php:
    new Liip\MonitorBundle\LiipMonitorBundle(),
    1. (Optional) If using the REST API, add the routing configuration to routing.yml:
    _monitor:
    resource: "@LiipMonitorBundle/Resources/config/routing.yaml"
    prefix: /monitor/health
    1. (Optional) Enable the controller in your configuration:
    liip_monitor:
    enable_controller: true
    1. Install assets into your web root:
    ./app/console assets:install web --symlink --relative

  7. Enable the Health Check REST API

    2.x

    To access the health check results via a REST API, you must register the bundle's routes in your Symfony application's routing configuration (e.g., config/routes.yaml). Once enabled, the API documentation and endpoints will be available at the path configured in your project (typically /monitor/health/).

    # Example routing configuration
# config/routes.yaml
liip_monitor:
    resource: '@LiipMonitorBundle/Resources/config/routing.yml'
    prefix: /monitor

  8. Register a custom health check service

    2.x

    To add a custom health check, implement CheckInterface and register the class as a Symfony service tagged with liip_monitor.check.

    If your application uses autoconfigure, classes implementing Laminas\Diagnostics\Check\CheckInterface will be tagged automatically. If you need to manually specify a group or disable autoconfigure, use the following pattern:

    services:
    monitor.check.php_extensions:
        class: Acme\HelloBundle\Check\PhpExtensionsCheck
        arguments:
            - [ xhprof, apc, memcache ]
        tags:
            - { name: liip_monitor.check, alias: php_extensions }

    Note: The alias is optional and defines the ID used when running checks individually.

  9. Add a custom reporter

    2.x

    You can extend the output of health checks by creating custom reporters. To register one, define a service and tag it with liip_monitor.additional_reporter.

    my_reporter:
    class: My\Reporter
    tags:
        - { name: liip_monitor.additional_reporter, alias: my_reporter }

    Usage:

    • CLI: Use the --reporter flag: ./app/console monitor:health --reporter=my_reporter
    • REST API: Use the reporters[] query parameter: /monitor/health?reporters[]=my_reporter

  10. Update imports when upgrading from 2.11 to 2.12

    2.x

    When upgrading from version 2.11 to 2.12, the underlying diagnostics library changed from zendframework/zenddiagnostics to laminas/laminas-diagnostics.

    If you are using the bundle with default settings, no action is required. However, if you have implemented custom checks or custom reporters, you must update your PHP namespaces from ZendDiagnostics\* to Laminas\Diagnostics\* to avoid breaking changes.

    - use ZendDiagnostics\*;
+ use Laminas\Diagnostics\*;

  11. Integrate with Nagios using the Python script

    2.x

    The bundle provides a Python-based Nagios check located in the Resources/scripts directory. This script depends on the nagiosplugin library (version < 1.0.0).

    Command Configuration

    Define a command in your Nagios configuration. To use HTTP basic authentication, use the -a flag with the format username:password.

    Basic usage:

    define command{
    command_name    check_symfony_health
    command_line    $USER1$/check_symfony2.py -w 0 -c 0 -u https://$HOSTNAME$
}

    Usage with HTTP Basic Authentication:

    define command{
    command_name    check_symfony_health
    command_line    $USER1$/check_symfony2.py -w 0 -c 0 -u https://$HOSTNAME$ -a username:password
}

  12. Enable built-in health checks

    2.x

    To enable the bundle's built-in health checks, list them under the checks key in your liip_monitor configuration.

    Example for enabling php_extensions with specific extensions:

    liip_monitor:
    checks:
        php_extensions: [apc, xdebug]