TYPO3 Monitoring

This packages provides the TYPO3 CMS Extension EXT:monitoring which extends the CMS with a monitoring system that gives an insight into the health state of custom TYPO3 components through an API endpoint and a CLI command, e.g. for post-deployment checks.

Warning

This package is still in early development and must be considered unfit for production use. Bear with me. We'll get there.

🚀 Features

• Extensible monitoring system with automatic service discovery (using DI) for custom authorization and monitoring checks.
• Built-in MiddlewareStatusProvider for meta-level monitoring of the monitoring system itself
• Supports caching for expensive monitoring operations
• Delivers health reports in three ways:
  • JSON response: Returns structured responses for the overall health status
  • CLI command: Command-line interface for running monitoring checks
  • Backend Module: TYPO3 backend module

🔥 Quick Start

Installation

Install via Composer:

composer require mteu/typo3-monitoring

Configuration

1. Configure the extension in the TYPO3 backend:

   • Go to Admin Tools → Settings → Extension Configuration
   • Select monitoring
   • Set the monitoring endpoint path (default: /monitor/health)
   • Configure authorizer settings for token-based and admin user authentication

2. Or better yet configure the settings programmatically:

   # config/system/settings.php
   
   <?php
   
   return [
       // ..
       'EXTENSIONS' => [
           'monitoring' => [
               'api' => [
                   'endpoint' => '/monitor/health',
               ],
               'authorizer' => [
                   'mteu\Monitoring\Authorization\TokenAuthorizer' => [
                       'enabled' => true,
                       'secret' => 'your-secure-secret',
                       'authHeaderName' => 'X-TYPO3-MONITORING-AUTH',
                       'priority' => 10,
                   ],
                   'mteu\Monitoring\Authorization\AdminUserAuthorizer' => [
                       'enabled' => true,
                       'priority' => -10,
                   ],
               ],
           ],
       ],
       // ..
   ];

3. Access your monitoring endpoint while authenticated as backend user with the role of Admin or System Maintainer:

   https://<your-site>/monitor/health
   

Authentication

This extension ships two authentication methods natively:

Admin User Authentication

Access the endpoint while logged in as a TYPO3 backend administrator.

Token-based Authentication

Add the configured auth header (default: X-TYPO3-MONITORING-AUTH) with an HMAC signature:

curl -s -H "X-TYPO3-MONITORING-AUTH: <auth-token>" \
     https://<your-site>/monitor/health | jq '.'

Token Generation: The HMAC token is generated using TYPO3's HashService with the endpoint path and your configured secret:

$hashService = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Crypto\HashService::class);
$token = $hashService->hmac('/monitor/health', 'your-secure-secret');

📝 Response Format

The monitoring endpoint returns JSON with the following structure:

{
  "isHealthy": true,
  "services": {
    "service_one": "healthy",
    "service_two": "healthy",
    "service_three": "healthy"
  }
}

• isHealthy: Overall health status (boolean)
• services: Object with individual service statuses ("healthy" or "unhealthy")

HTTP status codes:

• 200 All services healthy
• 401 Unauthorized access
• 403 Unsupported protocol
• 503 One or more services unhealthy

🧑‍💻 Development

Creating Custom Providers

Implement the MonitoringProvider interface:

<?php

use mteu\Monitoring\Provider\MonitoringProvider;
use mteu\Monitoring\Result\MonitoringResult;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag(tag: 'monitoring.provider')]
final class MyMonitoringProvider implements MonitoringProvider
{
    public function getName(): string
    {
        return 'MyService';
    }

    public function getDescription(): string
    {
        return 'Monitors my custom service';
    }

    public function isActive(): bool
    {
        // conditional logic or just true
        return true;
    }

    public function execute(): MonitoringResult
    {
        // Your monitoring logic here
        return new MonitoringResult(
            $this->getName(),
            true,
        );
    }
}

Creating Custom Authorizers

Implement the Authorizer interface:

<?php

use mteu\Monitoring\Authorization\Authorizer;
use Psr\Http\Message\ServerRequestInterface;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag(tag: 'monitoring.authorizer')]
final class MyAuthorizer implements Authorizer
{
    public function isAuthorized(ServerRequestInterface $request): bool
    {
        // Your authorization logic here
        return true;
    }

    public static function getPriority(): int
    {
        return 100; // Higher priority = checked first
    }
}

🤝 Contributing

Contributions are very welcome! Please have a look at the Contribution Guide. It lays out the workflow of submitting new features or bugfixes.

📙 Documentation

Please have a look at the extension documentation. It provides a detailed look into the possibilities you have in extending and customizing this extension for your specific TYPO3 components.

🔒 Security

Please refer to our security policy if you discover a security vulnerability in this extension. Be warned, though. I cannot afford bounty. This is private project.

💛 Acknowledgements

This extension is inspired by cpsit/monitoring and its generic approach to offer an extensible provider interface. I've transformed and extended the underlying concept into a TYPO3 specific implementation.

⭐ License

This extension is licensed under the GPL-2.0-or-later license.

💬 Support

For issues and feature requests, please use the GitHub issue tracker.