Download the PHP package worlddirect/healthcheck without Composer

TYPO3 Extension: Healthcheck

A comprehensive health monitoring extension for TYPO3 CMS that provides automated system checks and monitoring capabilities.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
  • Extension Configuration
  • Access Token
  • TypoScript Configuration
• Probes
  • Core Probes
  • Extension-Specific Probes
  • Creating Custom Probes
• Output Formats
  • HTML Output
  • JSON Output
  • Creating Custom Outputs
• Accessing the Healthcheck
• Pausing Probes
• HTTP Status Codes
• Troubleshooting
• Tests
• Support
• License
• Credits

Features

• Proactive Monitoring: Automatically detects issues before they impact your users
• System Overview: Provides a quick snapshot of your TYPO3 system's health status
• Integration Ready: Works seamlessly with monitoring tools like PRTG, Nagios, Zabbix, and other monitoring solutions
• Extensible Architecture: Easily extend with custom probes specific to your needs
• Visual Feedback: Beautiful HTML interface showing all check results at a glance
• API Access: JSON output for programmatic access and automated monitoring
• Flexible Probes: Built-in checks for databases, caches, scheduler, Solr, email delivery, and more
• Pause Controls: Temporarily disable probes during maintenance without affecting monitoring
• Security First: IP and host-based access restrictions, plus an optional secret token with brute-force protection for installations that are not shielded by an internal-only ingress

Requirements

• TYPO3 11.0 - 13.9
• PHP 8.1 or higher

Installation

Via Composer (recommended)

Activation

After installation, activate the extension in the TYPO3 Extension Manager or via CLI:

Configuration

Extension Configuration

Configure the extension through the TYPO3 Extension Manager or by editing your site's configuration.

Security Settings

Access Token (optional)

If your installation is not protected by an internal-only ingress, you can additionally require a secret to be passed as GET parameter. The protection is opt-in: it is only active when accessToken is not empty. Once a token is configured it is mandatory for /{pathSegment}, /{pathSegment}-pause/ and /{pathSegment}-play/. Requests without a valid token receive an empty 404 Not Found, which hides the existence of the endpoint from scanners.

Usage:

The trailing slash is optional, https://example.com/healthcheck?token=<secret> and https://example.com/healthcheck/json?token=<secret> work as well.

Generate a token:

Keep the secret out of Git by setting it from an environment variable in config/system/additional.php (TYPO3 v12+) respectively AdditionalConfiguration.php:

Warning: GET parameters end up in webserver access logs, proxy logs and possibly Referer headers. Consider excluding the healthcheck path from access logging or masking the query string.

Note: The rate limiting uses the cache healthcheck_tokenattempts, backed by the database so that the counter is shared across all containers/pods. Run the database analyzer in the Install Tool after enabling the feature so the table cache_healthcheck_tokenattempts gets created (cf_healthcheck_tokenattempts before TYPO3 v14), or on the CLI:

If the cache is unavailable the rate limiting is silently skipped, but the token itself is still enforced.

Note: The counter is keyed by the client IP address. Behind a reverse proxy make sure $GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'] and reverseProxyHeaderMultiValue are configured, otherwise all requests share one counter and a single attacker could lock out your monitoring. Set accessTokenMaxAttempts = 0 if you cannot resolve real client IPs.

Verifying the rate limiting

1. Call /healthcheck?token=<wrong> as often as configured in accessTokenMaxAttempts. Every request answers with an empty 404.
2. Call /healthcheck?token=<secret> with the correct token — it now also answers with an empty 404, because the client is locked out.
3. Clear the lockout with vendor/bin/typo3 cache:flush --group system (or Flush system caches in the backend), or wait for accessTokenLockoutPeriod seconds.

Use a private/incognito window, otherwise the browser may serve the cached 404 instead of sending a new request.

Display Settings

Probe-Specific Settings

TypoScript Configuration

Additional settings can be configured via TypoScript:

Probes

Probes are the heart of the healthcheck system. Each probe checks a specific aspect of your TYPO3 installation and reports whether it's functioning correctly.

Core Probes

These probes are always available and check fundamental TYPO3 system components.

Database Connection

Class: DatabaseProbe
Title: Database Connection
Always Active: Yes

Checks if the TYPO3 application can connect to all configured databases.

What it checks:

• All database connections defined in your configuration
• Basic query execution capability
• Connection availability

Fails when:

• Any database connection cannot be established
• Query execution fails on any connection

Cache System

Class: CacheProbe
Title: Cache System
Always Active: Yes (except in Development context)

Verifies that all configured caches are writable and functioning correctly.

What it checks:

• All configured cache backends
• Write and read operations for each cache
• Cache backend availability

Fails when:

• Any cache cannot be written to
• Any cache backend is misconfigured
• Cache operations fail

Note: This probe is automatically disabled in Development context as development systems often have caching disabled.

Extension-Specific Probes

These probes require specific TYPO3 extensions to be installed and activated.

Scheduler Tasks

Class: SchedulerProbe
Title: Scheduler Tasks
Requires: EXT:scheduler

Monitors TYPO3 scheduler tasks for failures and delays.

What it checks:

• Failed scheduler tasks
• Tasks that are significantly delayed (configurable via schedulerMaxMinutesLate)
• Task execution status

Fails when:

• Any scheduler task has a failure status
• Tasks are running later than the configured maximum delay

Configuration: Set schedulerMaxMinutesLate in extension configuration to adjust delay tolerance (default: 10 minutes).

Solr Core Connectivity

Class: SolrCoreProbe
Title: Solr Core Connectivity
Requires: EXT:solr

Tests connectivity to all configured Solr cores across all site languages.

What it checks:

• Connection to each configured Solr core
• Solr server availability
• Core accessibility for each language

Fails when:

• Cannot connect to any configured Solr server
• Any Solr core is unreachable
• Solr ping request fails

Configuration: Reads Solr configuration from site configuration (host, port, path, core, scheme).

Solr Index Errors

Class: SolrIndexErrorProbe
Title: Solr Index Errors
Requires: EXT:solr

Monitors the Solr indexing queue for errors that prevent content from being indexed.

What it checks:

• Number of items in the Solr index queue with errors
• Error count against configured threshold

Fails when:

• Number of index errors exceeds solrMaxErrorCount

Configuration: Set solrMaxErrorCount in extension configuration to adjust error tolerance (default: 50 errors).

External Import

Class: ExternalImportProbe
Title: External Import
Requires: EXT:external_import

Checks the status of the latest External Import extension log entry to detect import failures.

What it checks:

• Latest import log entry status
• Import success/failure state

Fails when:

• Latest import log entry has a non-zero (error) status

Mailjet Email Delivery

Class: MailjetDeliveryProbe
Title: Mailjet Delivery Success Rate
Requires: EXT:mailjet

Monitors email delivery success rate from the Mailjet extension, analyzing emails sent in the last 24 hours.

What it checks:

• Total number of emails sent in the last 24 hours
• Number of failed email deliveries
• Failure rate percentage

Behavior:

• No emails: Reports success if no emails were sent
• Low volume (< 10 emails): Reports error only if ALL emails failed
• Normal volume (≥ 10 emails): Calculates failure rate percentage
  • ≥ 20% failure rate: Critical error
  • ≥ 5% failure rate: Warning error
  • < 5% failure rate: Success

Fails when:

• All emails in low-volume scenarios failed
• Failure rate ≥ 5% in normal-volume scenarios
• Cannot access the email log database table

Database: Queries tx_mailjet_domain_model_emaillog table for delivery statistics.

Thresholds:

• Time window: 24 hours (86,400 seconds)
• Minimum sample size: 10 emails
• Warning threshold: 5% failure rate
• Critical threshold: 20% failure rate

SAML Metadata Expiration

Class: SamlMetadataExpirationProbe
Title: SAML Metadata Expiration Probe
Requires: SimpleSAMLphp with metarefresh module

Checks SimpleSAMLphp SAML metadata expiration to ensure federation metadata remains valid.

What it checks:

• Metadata expiration timestamp from SimpleSAMLphp metarefresh configuration
• Time remaining until metadata expires
• Whether metadata has already expired

Fails when:

• Metadata has expired (expiration timestamp is in the past)
• Metadata will expire within the tolerance window

Configuration:

• Environment variable: SIMPLESAMLPHP_CONFIG_DIR must point to SimpleSAMLphp config directory
• Config files: Looks for config-metarefresh.php or module_metarefresh.php
• Metadata file: Reads from saml20-idp-remote.php in the metarefresh output directory
• Tolerance: 30 minutes before expiration (configurable via constant)

Requirements:

• SimpleSAMLphp must be installed and configured
• SIMPLESAMLPHP_CONFIG_DIR environment variable must be set
• Metarefresh module must be active with valid configuration
• Output directory must use absolute paths

Note: This probe automatically activates only if SimpleSAMLphp metarefresh configuration is detected with a valid expiration timestamp.

Creating Custom Probes

You can easily create your own probes to check specific aspects of your TYPO3 installation.

Step 1: Implement the ProbeInterface

Create a new PHP class that implements the ProbeInterface:

Step 2: Register Your Probe

Register your custom probe in Configuration/Services.yaml:

Required Methods

Your probe must implement these three methods:

1. useProbe(): bool - Returns whether this probe should be executed. Use this to check dependencies like required extensions.

2. getTitle(): string - Returns a human-readable title for display in the HTML output.

3. run(): void - Contains the actual probe logic. Always call parent::start() at the beginning and parent::stop() at the end.

Important Guidelines

• Always call parent::start() and parent::stop() to properly track execution time
• Always add at least one message (success or error) to set the probe status
• Use $this->result->addSuccessMessage() for successful checks
• Use $this->result->addErrorMessage() for failures
• You can add multiple messages for detailed reporting
• Extend ProbeBase to inherit common functionality
• Use $this->langService to access translation services
• Access configuration via $this->getExtensionConfiguration()

Output Formats

The healthcheck can return results in different formats depending on your needs.

HTML Output

Access: /healthcheck/html or /healthcheck/
Content-Type: text/html

A beautiful, responsive HTML interface built with Bootstrap 5 that provides:

• Overall Status Indicator: Clear visual indication (success/error) of system health
• Probe Details: Expandable accordion panels showing each probe's results
• Color-Coded Status: Green for success, red for errors
• Execution Time: Shows how long each probe took to execute
• Pause/Play Controls: Ability to temporarily disable probes
• System Information: Optional display of build info, IP address, and timestamp
• Responsive Design: Works on desktop, tablet, and mobile devices

Perfect for:

• Manual system health checks
• Dashboard displays
• Quick visual overview
• Troubleshooting

JSON Output

Access: /healthcheck/json
Content-Type: application/json

Returns a structured JSON representation of all probe results.

Example Response:

Perfect for:

• Automated monitoring systems
• Programmatic access
• Integration with other tools
• Logging and analytics

Example Response:

Creating Custom Outputs

You can create custom output formats for specialized needs.

Step 1: Implement the OutputInterface

Step 2: Register Your Output

Register in Configuration/Services.yaml:

Step 3: Access Your Output

Access via: /healthcheck/custom (using the lowercase class name without "Output" suffix)

Accessing the Healthcheck

The healthcheck is accessed through a special URL structure that uses TYPO3 middleware.

URL Structure

Components:

1. pathSegment: The base path configured in extension settings (default: healthcheck)
2. output: The output format to use (optional, defaults to html)

Examples

Security Configuration

Before accessing the healthcheck, ensure proper configuration:

1. trustedHostsPattern: Set to .* for all hosts or a specific pattern like ^(localhost|monitoring\.example\.com)$
2. allowedIps: Configure if you want to restrict by IP address (default: * allows all)
3. accessToken: Optional secret required as GET parameter, see Access Token

Important: Without proper configuration, access will be denied with error messages indicating the issue.

Pausing Probes

During maintenance or when dealing with known issues, temporarily pause individual probes to prevent false alerts.

How Pausing Works

When a probe is paused:

• ✅ It still appears in the healthcheck output
• ✅ Its status is clearly marked as "PAUSED"
• ✅ It doesn't affect the overall healthcheck status
• ✅ Other probes continue to run normally
• ✅ No false alerts are sent to monitoring systems

Pause Controls

HTML Interface

Each probe has pause/play buttons:

• Pause Button (▶️): Click to pause a failing probe
• Play Button (⏸️): Click to resume a paused probe

Visual indicators show probe status:

• Paused probes: "⏸️ PAUSED" indicator
• Active probes: "▶️ ACTIVE" indicator

API Endpoints

Pause/play probes programmatically. When an accessToken is configured it has to be appended to these URLs as well (e.g. &token=<secret>).

Pause a probe:

Resume a probe:

Response:

Use Cases

• Scheduled Maintenance: Pause relevant probes before maintenance windows
• Known Issues: Temporarily silence alerts for issues being worked on
• External Dependencies: Pause probes when external services are down
• Gradual Rollout: Pause probes during deployments to avoid false positives

Technical Details: Paused probes are stored in tx_healthcheck_domain_model_probe_pause table with probe class name and timestamp.

HTTP Status Codes

The healthcheck uses HTTP status codes to indicate system health, making it easy for monitoring tools to detect issues.

Monitoring Integration Examples

PRTG

Use HTTP sensor checking for status code 200

Nagios

Uptime Robot

Configure HTTP(s) monitoring with keyword checking

Custom Script

Troubleshooting

Access Denied (403 Forbidden)

Problem: Cannot access healthcheck endpoint

Solutions:

• Check trustedHostsPattern is configured (set to .* for all hosts)
• Verify your IP is in allowedIps (set to * to allow all)
• Review extension configuration in Extension Manager

Empty 404 Not Found

Problem: The healthcheck endpoint returns an empty 404 although the path segment is correct

Solutions:

• An accessToken is configured: append the token as GET parameter (?token=<secret>)
• The parameter name may have been changed via accessTokenParam
• Your IP may be locked out after too many failed attempts: wait for accessTokenLockoutPeriod seconds or flush the system caches (vendor/bin/typo3 cache:flush --group system)

Rate Limiting Has No Effect

Problem: A client is never locked out, no matter how many wrong tokens are sent

Solutions:

• The cache table is missing: run the database analyzer, see Access Token. Without the table the rate limiting is skipped silently
• accessTokenMaxAttempts is set to 0, which disables the feature
• All requests share one counter or none at all because the real client IP cannot be resolved behind a reverse proxy, see the note in Access Token

Probe Always Failing

Problem: A specific probe consistently fails

Solutions:

• Check probe-specific requirements (e.g., required extensions installed)
• Review probe configuration settings (e.g., schedulerMaxMinutesLate)
• Enable debug mode (enableDebug = 1) for detailed error messages
• Temporarily pause the probe during troubleshooting

JSON Output Not Working

Problem: JSON endpoint returns 404

Solutions:

• Verify URL format: /healthcheck/json/ (with trailing slash)
• Check that custom output class is properly registered in Services.yaml
• Clear TYPO3 caches

Probes Not Running

Problem: No probes appear in output

Solutions:

• Verify probe services are registered in Configuration/Services.yaml
• Check if probes have useProbe() returning false due to missing dependencies
• Clear all TYPO3 caches
• Check PHP error logs for exceptions

Tests

The extension ships with a PHPUnit test suite (unit + functional tests via typo3/testing-framework). See documentation/tests.md for a full description of what is tested and how to run the tests.

Support

• Issues: GitHub Issues
• Source Code: GitHub Repository
• Author: Klaus Hörmann-Engl [email protected]
• Company: World-Direct eBusiness solutions GmbH

License

This extension is licensed under GPL-2.0-only. See LICENSE file for details.

Credits

Developed and maintained by Klaus Hörmann-Engl at World-Direct eBusiness solutions GmbH.

Inspiration

• Axel Seemann (aseemann) - healthcheck.php Gist
• Georg Ringer - t3monitoring_client extension

Icons and Images

• Success Icon: Tick icons by kliwir art - Flaticon
• Error Icon: Error icons by Ilham Fitrotul Hayat - Flaticon
• Health Report Icon: Medical record icons by Freepik - Flaticon
• Pause Icon: Pause icons by Kiranshastry - Flaticon
• Play Icon: Play icons by Freepik - Flaticon

Happy Monitoring! 🏥✨