Skip to content

ReportsModule.rst

Latest commit

 

History

History
445 lines (299 loc) · 12.1 KB

ReportsModule.rst

File metadata and controls

445 lines (299 loc) · 12.1 KB

TYPO3 Reports Module

System Status Report

The Temporal Cache extension integrates with TYPO3's built-in Reports module, providing comprehensive system health and configuration monitoring.

Accessing the Report

  1. Log in to the TYPO3 backend as an administrator
  2. Navigate to: Admin Tools > Reports > Status Report
  3. Scroll to the Temporal Cache section

The report displays in the standard TYPO3 Reports interface with color-coded status indicators:

  • Green (OK): Everything working properly, no action required
  • Yellow (WARNING): Minor issues or optimization recommendations
  • Red (ERROR): Critical issues requiring immediate attention

Report Sections

Extension Configuration

What it shows:

  • Current scoping strategy (global, per-page, per-content)
  • Current timing strategy (dynamic, scheduler, hybrid)
  • Harmonization status (enabled/disabled)
  • Reference index usage
  • Configuration recommendations

Status levels:

  • OK: Configuration is valid and optimized
  • WARNING: Configuration is valid but could be optimized
  • ERROR: Invalid configuration detected

Actions:

If you see an error or warning:

  1. Navigate to: Admin Tools > Settings > Extension Configuration
  2. Locate temporal_cache in the list
  3. Review and adjust the settings based on recommendations
  4. Save changes

Database Indexes

What it shows:

  • Verification of required database indexes on starttime/endtime fields
  • Index status for both pages and tt_content tables
  • Performance impact assessment

Status levels:

  • OK: All required indexes are present
  • ERROR: Missing indexes detected (severe performance impact)

Actions:

If indexes are missing:

  1. Navigate to: Admin Tools > Maintenance > Analyze Database Structure
  2. Review the proposed changes
  3. Apply the schema updates to create missing indexes
  4. Return to the Reports module to verify indexes are now present

Performance impact:

Missing indexes cause full table scans on every temporal content lookup, which can slow down frontend page rendering by 10-100× depending on database size.

Temporal Content Statistics

What it shows:

  • Total number of pages and content elements with temporal fields
  • Distribution of starttime, endtime, and combined usage
  • Next upcoming transition time
  • Time until next cache invalidation

Status levels:

  • OK: Temporal content found and being managed
  • WARNING: No temporal content found (extension is active but unused)
  • ERROR: Failed to retrieve statistics

Understanding the data:

  • Total Items: All pages and content elements with starttime or endtime set
  • Pages: Number of temporal pages (affects menu visibility)
  • Content Elements: Number of temporal content elements
  • With Start Date Only: Content that becomes visible at a specific time
  • With End Date Only: Content that becomes hidden at a specific time
  • With Both Dates: Content visible within a specific time window

Harmonization Status

What it shows:

When harmonization is disabled:

  • Information about harmonization benefits
  • Recommendation to enable if you have high transition volume

When harmonization is enabled:

  • Current time slot configuration
  • Tolerance settings
  • Auto-round on save status
  • Actual cache reduction achieved (percentage)

Status levels:

  • OK: Harmonization is properly configured and providing benefits
  • INFO: Harmonization is disabled (informational)
  • WARNING: Harmonization is enabled but providing minimal benefit

Understanding cache reduction:

Harmonization reduces cache churn by rounding transition times to predefined slots. For example:

Without harmonization (3 separate cache invalidations):

  • Content A: 00:05
  • Content B: 00:15
  • Content C: 00:45

With harmonization to 00:00 slot (1 cache invalidation):

  • Content A: 00:00
  • Content B: 00:00
  • Content C: 00:00

When to enable:

  • You have more than 10 transitions per day
  • Cache reduction shows potential benefit >10%
  • You want to reduce cache invalidation frequency

When to disable:

  • You have very few temporal items (<5 transitions per day)
  • Exact timing of content visibility is critical
  • Cache reduction benefit is minimal (<5%)

Upcoming Transitions

What it shows:

  • Total transitions scheduled in next 7 days
  • Daily breakdown of transition events
  • Average transitions per day
  • High volume warnings

Status levels:

  • OK: Normal transition volume
  • WARNING: High transition volume detected (>20 per day average)
  • INFO: No upcoming transitions

Understanding transition impact:

Each transition can trigger cache invalidation depending on your scoping strategy:

  • Global scoping: All page caches invalidated on every transition
  • Per-page scoping: Only affected pages invalidated
  • Per-content scoping: Only pages containing affected content invalidated

High volume recommendations:

If you see a high transition volume warning (>20 per day):

  1. Consider enabling harmonization to group transitions
  2. Evaluate if scheduler-based timing would be more efficient
  3. Review if per-content scoping can reduce invalidation scope

Common Scenarios

Scenario 1: Extension Just Installed

Expected status:

  • Extension Configuration: OK (default settings)
  • Database Indexes: ERROR (indexes not created yet)
  • Temporal Content: WARNING (no content found)
  • Harmonization: INFO (disabled by default)
  • Upcoming Transitions: INFO (none scheduled)

Actions:

  1. Run database schema update to create indexes
  2. Start adding temporal content (pages/content with starttime/endtime)
  3. Return to Reports module to verify system status

Scenario 2: Production Site with Temporal Content

Expected status:

  • Extension Configuration: OK
  • Database Indexes: OK
  • Temporal Content: OK (showing statistics)
  • Harmonization: OK or INFO (depending on configuration)
  • Upcoming Transitions: OK (showing schedule)

Actions:

  • Monitor the report periodically (weekly recommended)
  • Review harmonization recommendations if transition volume is high
  • Check for configuration optimization suggestions

Scenario 3: Performance Issues Detected

Symptoms in report:

  • Database Indexes: ERROR (missing indexes)
  • Upcoming Transitions: WARNING (high volume)
  • Harmonization: INFO (disabled)

Resolution steps:

  1. Immediate: Create missing database indexes
  2. Short-term: Enable harmonization to reduce cache churn
  3. Long-term: Consider per-content scoping if using global scoping

Scenario 4: No Temporal Content Found

Status:

  • Temporal Content: WARNING
  • Upcoming Transitions: INFO

Possible causes:

  1. No pages or content elements have starttime/endtime set
  2. Content exists but is in a different workspace
  3. Content is in a different language

Actions:

  1. Verify temporal content exists in the backend
  2. Check if you're viewing the correct workspace (report shows live workspace by default)
  3. If no temporal content exists, consider if the extension is needed

Automation and Monitoring

CLI Command Alternative

For automation and monitoring systems, use the CLI verify command:

# Quick verification (exit code 0 = OK, 1 = issues)
vendor/bin/typo3 temporalcache:verify

# Verbose output for logs
vendor/bin/typo3 temporalcache:verify --verbose

The CLI command performs the same checks as the Reports module and is suitable for integration with monitoring tools, CI/CD pipelines, or scheduled health checks.

Integration with Monitoring Systems

The verify command can be integrated with monitoring tools:

Nagios/Icinga:

#!/bin/bash
# /usr/local/nagios/libexec/check_typo3_temporal_cache.sh

cd /var/www/html/typo3
vendor/bin/typo3 temporalcache:verify >/dev/null 2>&1

if [ $? -eq 0 ]; then
    echo "OK - Temporal Cache system healthy"
    exit 0
else
    echo "CRITICAL - Temporal Cache system issues detected"
    exit 2
fi

Cron-based monitoring:

# Check daily and email on failure
0 8 * * * cd /var/www/html/typo3 && vendor/bin/typo3 temporalcache:verify || mail -s "TYPO3 Temporal Cache Issues" admin@example.com < /dev/null

Troubleshooting

Report Not Visible

Symptom: Temporal Cache section does not appear in Reports module

Causes:

  1. Extension not installed or activated
  2. Cache not cleared after installation
  3. Missing service registration

Solutions:

  1. Verify extension is installed: Admin Tools > Extensions
  2. Clear all caches: Admin Tools > Maintenance > Flush Cache
  3. Check if Services.yaml is properly loaded (check system log)

Database Index Check Fails

Symptom: Cannot verify indexes, error message displayed

Causes:

  1. Database connection issues
  2. Insufficient database permissions
  3. Missing database tables

Solutions:

  1. Check database connection in Install Tool
  2. Verify database user has SELECT privileges on schema tables
  3. Run database schema update to ensure tables exist

Statistics Show Zero Items

Symptom: Report shows 0 temporal items but content exists

Causes:

  1. Content is in a workspace (report shows live workspace)
  2. Content has been deleted but not purged
  3. starttime/endtime fields are set to 0 (not set)

Solutions:

  1. Use the CLI list command to verify content: vendor/bin/typo3 temporalcache:list
  2. Check workspace settings in the backend
  3. Verify starttime/endtime fields have actual timestamps (not 0)

Best Practices

Regular Monitoring

  • Weekly: Review the Reports module status
  • Monthly: Analyze transition patterns and harmonization impact
  • Quarterly: Review configuration and optimize based on usage patterns

Before Major Events

Before high-traffic periods or major content updates:

  1. Verify all database indexes are present
  2. Review upcoming transitions schedule
  3. Confirm harmonization settings are optimal
  4. Test cache invalidation is working correctly

After Configuration Changes

After modifying extension settings:

  1. Check Reports module to verify configuration is valid
  2. Review recommendations for new configuration
  3. Test with sample temporal content
  4. Monitor frontend performance

Database Maintenance

After database updates or migrations:

  1. Verify database indexes still exist
  2. Run verify command to ensure schema is complete
  3. Check for any database-related errors in Reports module

Performance Optimization

Based on Reports Module Data

High transition volume (>20/day):

  • Enable harmonization
  • Consider scheduler-based timing strategy
  • Use per-content scoping instead of global

Low transition volume (<5/day):

  • Harmonization may not provide significant benefit
  • Dynamic timing strategy is efficient
  • Global scoping is acceptable for small sites

Large number of temporal items (>1000):

  • Use per-content scoping for minimal cache invalidation
  • Enable reference index usage
  • Consider scheduler-based timing to avoid per-request calculations

Mixed workload:

  • Use hybrid timing strategy (dynamic for pages, scheduler for content)
  • Enable harmonization with appropriate time slots
  • Monitor cache reduction percentage

Related Documentation