System Health

The System Health dashboard provides administrators with a real-time overview of the Freedam environment. It serves as a central hub for monitoring background processing, server resource utilization, and the status of external service dependencies.

This feature is essential for troubleshooting performance bottlenecks, verifying that automated tasks (like asset ingestion or metadata updates) are completing successfully, and ensuring all required system components are operational.

Page Overview

• Purpose: To provide visibility into the technical state of the application and the progress of long-running background tasks.
• When to use it: Use this page when checking if the system is under heavy load, investigating why an asset hasn't finished processing, or confirming that server resources are within healthy limits.
• What you can do here:
  • View high-level success rates for system operations.
  • Monitor background queue volumes and processing speeds.
  • Audit and manage bulk metadata updates and ingestion batches.
  • Check the status of required services like PHP extensions and system commands.
  • Export operation logs for external reporting.

Who can use it

The System Health dashboard is available to people with the View system health and analytics permission. The page, its metrics, the operations list, the cancel and retry actions and the CSV export all require it, so other users do not see the page in the admin menu.

Page Layout

• Top bar: Displays the "System Health Dashboard" title and description. The description changes with the selected tab. Contains the Refresh button to update metrics and the Export button (when on the Operations tab).
• Navigation Tabs: Three buttons to switch between the Overview, Operations, and Queues views.
• Main area: The primary content zone that changes based on the selected tab, featuring metric cards, filter controls, or data tables.
• Dialogs: Pop-up windows used for confirming operation cancellations or viewing granular details of a specific background task.

Main Features

System Metrics & Resource Monitoring

• What it's for: Tracking server-side health including memory usage, execution limits, and processing speeds.
• Typical use: Checking if the System Health status is GOOD, or if it shows ATTENTION, WARNING or CRITICAL due to recent failures.
• Result: Provides immediate feedback on whether the infrastructure is supporting the current user load.

Operations Management

• What it's for: Tracking the lifecycle of bulk tasks like asset ingestions and metadata changes.
• Typical use: Finding a specific batch by ID or User to see why it is stuck or failed.
• Result: Allows administrators to see exactly how many assets succeeded or failed within a specific job.

Dependency Verification

• What it's for: Ensuring all external tools and services required by Freedam are connected.
• Typical use: Verifying that "Required" services are marked with a green checkmark after a system update.
• Result: Identifies missing PHP extensions or system commands that might be disabling specific features.

Detailed Feature Documentation

Operations Filtering and Export

• Purpose: To locate specific background tasks and download history for auditing.
• Where to find it: Click the Operations tab, then look for the Filters card.
• What you'll see: A list of operations filtered by your criteria, with the ability to download the results as a CSV.

How to use it:

1. Select a status (e.g., "Failed") from the All Statuses dropdown.
2. Select a type (Asset Ingestion or Bulk Operation) from the All Types dropdown.
3. Click the Date from or Date to buttons to select a timeframe from the calendar.
4. Click Apply to update the list, or Clear to remove the filters.
5. Click Export in the top bar to download the filtered list.

Operation Detail View

• Purpose: To inspect the progress, timeline, and specific errors of a single operation.
• Where to find it: In the Operations table, click the View details (eye icon) button next to any entry.
• What you'll see: A dialog showing a progress bar, a timeline (Created vs. Started vs. Completed), and a list of individual asset results.

How to use it:

1. Locate the operation in the list.
2. Click the View details icon.
3. Scroll to Asset Results to see which specific files failed and why. The Stage column shows the step the file reached (for example Metadata Extraction), and the Message column gives the reason. For a file that failed during an upload or an import, the message is one of a fixed set of reasons, shown in your language, for example "This file failed the security scan and was rejected." or "Your storage is full. Upgrade your plan or free up space, then upload or import the file again." Technical error details stay in the server logs.
4. Click Close to return to the main list.

Complete Workflows

Workflow: Troubleshooting a Failed Bulk Update

• Goal: Identify why a metadata update didn't apply to all assets.
• Prerequisites: Administrator permissions.

Steps:

1. Click the Operations tab.
2. Locate the operation with the status PARTIAL or FAILED.
3. Click the View details button (eye icon).
4. Look at the Error Message section for a general system error.
5. Scroll to the Asset Results table and read the Message column for each failed file.
6. If the operation has the type Bulk Operation and the status FAILED, click the Retry button (refresh icon) in the main table to attempt the process again. Asset Ingestion entries cannot be retried from this page: upload or import the files again.

• Expected result: The detail dialog shows the stage each file reached (for example File Storage) and the reason for the failure.

Workflow: Monitoring Queue Health

• Goal: Check if background tasks are backing up.
• Prerequisites: Access to the System Health dashboard.

Steps:

1. Click the Queues tab.
2. Review the Queue Job Categories grid.
3. Look for categories with a blue pending count or a red failed count.
4. Check the System Queue Metrics on the Overview tab to see the Avg Ops/Sec.

• Expected result: If "Pending Jobs" is high and "Avg Ops/Sec" is low, the system is currently experiencing a processing delay.

What is being checked behind the scenes

The External Dependencies panel on the Overview tab lists real-time checks against the tools Freedam relies on. They are grouped by the area of the product they affect:

• Core Media Processing: video and audio handling (FFMPEG and FFprobe), image processing and thumbnailing (ImageMagick and the PHP Imagick extension), and, optionally, the ExifTool metadata reader and the C2PA Tool that verifies Content Credentials in uploaded files.
• Document Processing: Gotenberg, the service that converts Office documents to previewable PDFs, plus Ghostscript for PDF rendering and, optionally, pdfinfo for PDF metadata.
• AI & Machine Learning: the Embedder service that powers semantic search and near-duplicate detection, and the InsightFace service that detects faces in your photos. Both are optional.

The virus scanner and the queue workers are not listed in this panel. A file that could not be scanned is reported in the operation details with the message "The security scan could not run, so the file was not added. Upload or import it again." Queue activity is on the Queues tab.

Each item is labelled Required or Optional. Required items are essential for everyday operation; optional items only disable the specific feature they power (for example, face recognition or semantic search) while the rest of the platform keeps working.

How the queue categories are organised

The Queues tab groups jobs into human-readable categories so you can see where any backlog or failure is coming from. Typical categories include:

• Ingestion Pipeline - everything involved in accepting a new upload and creating an asset.
• Metadata Processing - technical details like EXIF data, PDF text extraction, and perceptual hashes for duplicate detection.
• AI Enrichment - AI-powered tagging, captions, and chat title generation.
• Preview Generation - thumbnails, focus-point detection, and on-the-fly conversions.
• Search & Indexing - keeping the search engine current as assets, collections, vocabularies, and metadata change.
• Bulk Operations, Workflows, Pages, Emails, Analytics, Utilities and Other - the remaining automated work the platform does on your behalf.

Only categories with pending or failed jobs are shown. A category without failures shows No issues.

Good to know

• Success rate and throughput numbers focus on the last seven days of completed work; if nothing ran in that window the page automatically widens the lookback to thirty days so the figures remain meaningful.
• Cancel is only available for a Bulk Operation that is pending or processing, and Retry only for a Bulk Operation that failed. A retry creates a new entry in the list. Asset Ingestion entries can be inspected but not cancelled or retried here.
• The CSV Export mirrors whatever filters you've applied to the Operations list, so you can share or archive a specific slice without exporting everything.

Tips and Best Practices

• Regular Refreshes: The dashboard does not auto-update every second. Use the Refresh button in the top bar to get the latest metrics during active ingestions.
• Check Dependencies First: If features like AI analysis or preview generation aren't working, check the External Dependencies section on the Overview tab first to ensure the required services are operational.
• Date Range Validation: Ensure your "Date from" is earlier than your "Date to"; the system will highlight the fields in red if the range is invalid.

Troubleshooting

Issue: Operation stuck in "Processing"

• Symptoms: The progress percentage hasn't changed for a long period.
• Cause: A background worker may have timed out or the server reached its memory limit.
• Fix: Check System Resources for memory usage. If it is a Bulk Operation, you can click the Cancel button (X icon) and then Retry.
• Prevention: Avoid running extremely large batches during peak server usage times.

Issue: "Critical dependency missing" warning

• Symptoms: The External Dependencies section shows "1 critical dependency missing" (or a higher count).
• Cause: A required system command or PHP extension is not installed on the server.
• Fix: Note the name of the dependency (e.g., a specific "Service" or "Command") and contact your system administrator to install the missing component.
• Prevention: Review the Dependencies list after any server migration or environment update.