README

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 in testing. Be cautious when using EXT:monitoring in production.

🦊 TYPO3 Support

🚀 Features

• Extensible monitoring system with automatic service discovery (using DI) for custom authorization and monitoring checks.
• Supports caching for expensive monitoring operations
• Delivers health reports in three ways:
  • Structured JSON responses for the overall health status
  • Command-line interface for running monitoring checks
  • Backend Module

🔥 Quick Start

Installation

Install via Composer:

composer require mteu/typo3-monitoring

Configuration

# config/system/settings.php

<?php

return [
    // ..
    'EXTENSIONS' => [
        'monitoring' => [
            'api' => [
                'endpoint' => '/monitor/health',
                'enforceHttps' => false,
            ],
            '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,
                ],
            ],
        ],
    ],
    // ..
];

Endpoint

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

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

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 (only when api.enforceHttps is enabled)
• 503 One or more services unhealthy

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 (which acts more like a salt).

use TYPO3\CMS\Core\Crypto\HashService;

final readonly class TokenGenerator
{
    public function __construct(
        private HashService $hashService,
    ) {}

    public function generate(string $endpoint, string $secret): string
    {
        return $this->hashService->hmac($endpoint, $secret);
    }
}

// $token = $tokenGenerator->generate('/monitor/health', 'your-secure-secret');

🧑‍💻 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 the Security Policy if you discover a security vulnerability in this extension. Be warned, though. I cannot afford bounty. This is a 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.