BugMonitor Documentation

1. Login to My account on bug-monitor.com
2. On the next screen you will see your subscriptions. Choose any active subscription and click to Manage Subscription
3. On the next screen click to Download plugin installer
4. Login to WordPress admin where you would like to install BugMonitor
5. Go to Plugins > Add new and click to upload plugin
6. Select the previously downloaded ZIP file (bug-monitor.zip) and click to install
7. Open Tools > BugMonitor, go to Settings > System and click Connect under License status. Log in on musthaveplugins.com and connect the site. The status changes to Active.

Bought BugMonitor on bug-monitor.com? On the connect page click Connect with BugMonitor account and log in with your bug-monitor.com credentials.

Overview

The main dashboard displays all detected events in a chronological list. Each event shows the type of issue, affected URL, timestamp, and severity level. Events are color-coded by category for easy identification.

Filtering and sorting events

The filter panel next to the list has three groups: Event Level (Critical, Error, Warning), Event type (Functional issues, JavaScript errors, Network errors, SEO problems, UX problems, UI problems, WebVitals issues, WordPress errors) and Status (Active or Ignored). Double-click an event type to show only that type. Each filter shows how many issues it contains; above 1000 the counter shows “1000+”.

Since version 1.0.2 the Sort by menu above the list can show Newest first, Oldest first, Most severe first or Most frequent first. BugMonitor remembers the filter and sort selection separately for each administrator.

Detailed Information

Clicking on any event opens a detailed view showing the complete error information, including the exact error message, stack trace (for JavaScript errors), affected element, browser information, and user context. This detailed information helps you understand and reproduce the issue.

Occurrence History

Each event detail page shows how many times the issue has occurred, when it was first detected, and the last occurrence. This helps you understand the frequency and impact of the problem.

Details that need a connected subscription

For Functional issues, JavaScript errors, Unresponsive elements, Layout issues and Content obstruction, BugMonitor stores the error details encrypted. Session recordings and screenshots are always stored encrypted. To see them, connect the site to an active subscription under Settings > System > License status. Until then these events show “You need a valid subscription to see details”.

For interaction problems (Unresponsive Link/Button, Possible Form Submission Issue, Form Abandonment Issue, Unresponsive Element and Content Obstruction), BugMonitor records the visitor's session, so you can replay what the user did leading up to the issue. The session replay shows mouse movements, clicks, scrolling, and form interactions. Other event types, such as PHP or JavaScript errors, do not have a recording.

For Too Close Clickable Elements, Layout Issue and Broken Link events, BugMonitor captures a screenshot of what the user saw. If no video or screenshot could be captured, the event offers a Live Preview link that opens the page with the problematic element highlighted. Videos and screenshots can be viewed when the site is connected to an active subscription.

Every event detail view includes a Get AI Help button next to Error Insights. With one click, BugMonitor sends the issue — its type, the error message and other relevant details, and, for PHP errors, a small excerpt of the affected source file — to our AI service and returns a clear, tailored explanation right inside the event.

What you get

The answer is written for two readers at once and is organised in three parts:

• What happened – a plain-language description of the problem and how it affects your site, with no technical jargon.
• How to fix it – what you can do yourself without touching code, such as updating or deactivating the responsible plugin or theme, clearing caches, or reporting it to the responsible developer.
• Technical details – a collapsible section for developers with a precise diagnosis and an advanced fix, often including a code snippet or a specific file change.

Smarter explanations

When an issue is likely a false positive (for example an intentional marketing redirect or a harmless third-party script error), the AI flags it and explains how to verify and safely ignore it. For UI, UX and functional issues it points you to the screenshot, session replay, or live preview to help you find the exact element on the page — described in plain terms rather than technical selectors.

Privacy

AI Help is used only when you click the button. At that moment the event's details (and, for PHP errors, a short excerpt of the affected file located inside your WordPress installation) are sent to the AI service to generate the answer.

Monitoring itself runs on your server, and all events, session recordings and screenshots are stored in your own WordPress database. Apart from AI Help, BugMonitor sends data to its own API (api.bug-monitor.com) in these cases:

• Notifications – e-mail, push and webhook notifications are delivered through the API, so it receives what the notification contains: event titles, descriptions, levels and counts (for an instant fatal error notification, the page URL, the error message and the file and line). Your notification e-mail addresses, push devices and webhook URLs are stored there too.
• Uptime monitoring – when you switch it on, the API is told to start checking your site's availability from outside.
• Encrypted event details – when you open an event whose details are stored encrypted, those details are sent to the API to be decrypted, and from then on they are stored readable on your site. For session recordings and screenshots only their encryption keys are sent, not the recording or the image itself.

Solve Event

Clicking 'Solved' for an event indicates that you have resolved the issue, and it likely won't happen again. However, if it does recur, the event will be reported again.

Ignore Event

Clicking 'Ignore' for an event signifies that you consider it a false positive or choose not to address it. In this case, even if the event recurs, it won't be reported again. To see ignored events, select Ignored under Status in the filter panel. Click Remove from ignored events to report the event again.

Ignore Category

If you find a category of issues (e.g., SEO or UI issues) unhelpful, click Ignore <category> issues. This removes all previously reported events in that category and switches off every monitoring option of that category in Settings, so these issues are no longer detected. The removed events do not appear under Status: Ignored. To report them again, switch the options back on in Settings.

Ignore Type

If you find a specific type of issue (e.g., Image alt tag issues or Hard to read text issues) unhelpful, click Ignore <type> issues. This removes all previously reported events of that type and switches off its monitoring option in Settings. To report it again, switch the option back on.

Unresponsive buttons/links

Activating this option allows BugMonitor to report any buttons or links that are unresponsive when clicked by a user.

Form submission issues

BugMonitor will identify and report issues related to form submissions on your site, such as JavaScript errors or incorrect captcha settings, preventing successful submission.

Broken links

Beyond just logging 404 errors, this feature helps pinpoint the location of broken links on your site, enabling you to fix them more efficiently.

Form abandonment

BugMonitor tracks when users start filling out a form but leave without completing it. This data helps you identify problematic forms and understand where users are dropping off, allowing you to optimize your forms for better conversion rates.

Since version 1.0.2 this also covers forms the browser refuses to send. If a visitor clicks submit but a required or incorrectly filled field stops the form, and the visitor leaves without submitting, BugMonitor reports a form abandonment and names the field that held them up. These clicks are not reported as form submission issues or unresponsive buttons.

On the WooCommerce checkout page, form submission and form abandonment issues also show the cart total as Possible revenue loss.

JavaScript errors often occur silently. When this option is enabled, BugMonitor will report any JavaScript errors that occur during a site visit.

HTTP errors

BugMonitor can report various HTTP errors such as 404, 403, and 500, which occur on your site, including those involving third-party resources.

Mixed content

If your site uses HTTPS but contains resources loaded over HTTP, browsers may block them. Enabling this option allows BugMonitor to report these mixed content issues.

CSP errors

This feature enables BugMonitor to report instances where resources have been blocked due to the Content Security Policy (CSP) violations.

Unsecure connection

If you enable this feature, BugMonitor will notify if the site was loaded through an unsecure connection without SSL encryption. Beyond security issues, this can cause slowdowns and harm SEO.

Title

Having a proper title is crucial for both SEO and user experience. In WordPress, titles are often dynamically generated, which can result in titles being too short, too long, or even missing.

Meta description

A proper meta description is vital for SEO. In WordPress, these descriptions are usually dynamically generated, which may lead to them being too short, too long, or entirely absent.

Image issues

For optimal SEO and site usability, proper alt attributes are essential for every image. However, alt tags are often missing or inappropriate, especially for dynamically added images.

Hard to read text

BugMonitor identifies instances of hard-to-read text, such as poor font size or color contrast. This feature is crucial for recognizing and addressing text clarity issues, thereby improving site accessibility.

Too close clickable elements

This feature reports clickable elements that are too close to each other, which can potentially cause user navigation errors. Highlighting these issues helps in enhancing the user experience, particularly on touch devices.

Layout issues

BugMonitor detects and reports layout problems like misalignments or overlapping elements. Identifying these issues is key to maintaining a professional and user-friendly website appearance.

Content obstruction

This feature identifies when page content is obscured or blocked by overlaying elements such as popups, sticky headers, or other UI components. Content obstruction can frustrate users and prevent them from accessing important information on your site.

Unresponsive elements

BugMonitor flags elements that appear clickable but do not respond when interacted with. This feature helps in identifying and addressing UI elements that might confuse or frustrate users, ensuring a more intuitive and responsive website experience.

Slow response

This feature monitors and reports on slow Time to First Byte (TTFB) or sluggish AJAX responses in the visitor's browser. Since version 1.0.2 it also measures AJAX and REST requests on the server: when a request takes longer than 3 seconds, the report shows the AJAX action or REST route and which plugin or theme the slow handler belongs to. WordPress core requests that are slow by design, such as dashboard widgets, Site Health checks, updates and installs, are skipped.

Bounce rate

BugMonitor tracks and reports the bounce rate, which indicates the percentage of visitors who leave the site after viewing only one page. This metric is crucial for understanding user engagement and identifying potential issues with site content or usability.

LCP

BugMonitor tracks the Largest Contentful Paint, a key WebVital that measures loading performance. It helps in identifying the time taken for the largest content element to load, which is crucial for assessing user experience during site visits.

FCP

This feature monitors the First Contentful Paint, which measures the time from navigation to when any part of the page's content is rendered on the screen. It's an important metric for understanding perceived load speed from the user's perspective.

CLS

BugMonitor evaluates the Cumulative Layout Shift, a vital metric that quantifies the amount of unexpected layout shift of visual page content. Monitoring CLS is essential for ensuring a stable and visually consistent browsing experience for users.

Unoptimized images

Added in version 1.0.2 (on by default). BugMonitor reports images that are downloaded in a needlessly large file size, and images that are loaded in a much higher resolution than they are displayed in. They appear in the report as Unoptimized Image.

Uptime monitoring

BugMonitor tracks your website's availability, alerting you to downtime instances, ensuring prompt awareness and response.

PHP errors

Sometimes WordPress plugins or themes can cause PHP errors. Ideally, we would notice them immediately after updating the theme or plugins, but BugMonitor can report them even if they occur silently, such as during form submissions or AJAX requests.

PHP warnings

This option allows you to monitor PHP warnings. These are non-fatal errors that don't prevent page loading but can cause issues in functionality. Since they're not as noticeable as fatal errors, detecting them can be more challenging.

Deactivate Broken Plugins

Broken plugins can prevent access to the admin area. If you enable this option, BugMonitor will automatically disable any plugins that cause a fatal error in the admin area.

Redirect loop

This feature automatically identifies and records instances of redirect loops, helping maintain website stability and enhancing user experience by promptly flagging potential navigation issues.

Malicious redirect

This feature automatically identifies and records malicious redirects, which is crucial when your site has been hacked and traffic is being redirected to third-party URLs.

Email sending errors

BugMonitor detects when WordPress fails to send emails. This is critical for monitoring contact forms, password reset emails, order confirmations, and other email-dependent functionality. Failed emails can significantly impact user experience and business operations.

Critical errors (five-minute alerts)

Critical events are not sent one by one. A background task runs every five minutes and collects newly detected critical events, such as PHP fatal errors, form submission problems or redirect issues. If there are any, BugMonitor sends them in one e-mail (and to your push and webhook endpoints), so you hear about site-breaking problems within minutes.

Instant fatal error notification

Since version 1.0.2 you can also get an e-mail the moment a fatal PHP error occurs. A fatal error can take the site down completely, and then the scheduled e-mails may never be sent. Enable Instant fatal error notification under Settings > Notifications (off by default). BugMonitor sends at most one e-mail per hour for the same error. If Deactivate Broken Plugins turns off a plugin, you also get an e-mail immediately.

Daily summary

Errors and warnings are bundled into a daily summary e-mail. It is only sent when new issues were reported since the last one.

Notification health checks

BugMonitor periodically validates your configured notification endpoints. If an email address bounces or a webhook becomes invalid, you will see a dashboard notice so you can fix the endpoint before critical alerts are missed.

Control how long events are stored in your database under Settings > System > Event Retention Period. You can choose 7 days, 30 days (default), 90 days, 1 year or Indefinitely. Older events are purged automatically once a day to keep your database clean and performant.

Click Reset under Settings > System > Reset Logs to clear all reported events, session recordings and screenshots at once. Ignored events are cleared too, so they may appear in reports again.

Enable e-mail notifications

The master switch for all notifications (on by default). Turn it off to stop all notifications.

Instant fatal error notification

Off by default (added in version 1.0.2). Sends an e-mail the moment a fatal PHP error occurs, instead of waiting for the next summary. At most one e-mail per hour per error. See Instant fatal error notification.

E-mail notifications

The list of e-mail addresses that receive notifications. On first setup BugMonitor adds the WordPress admin e-mail address automatically. Use Add new e-mail address to add more recipients.

Push notifications

To get push notifications on your phone, scan the QR code under Add new device. Connected devices are listed here and can be removed at any time.

Notification webhooks

Send notifications to any service that accepts a webhook. Enter the URL and choose the request type (POST or GET). You can use these variables in the URL: [CATEGORY], [CATEGORY_LABEL], [LEVEL], [LEVEL_LABEL], [EVENT_COUNT], [MESSAGE] and [DETAILS_URL].

Example: https://my-service.com/webhook/?cat=[CATEGORY]&cat_label=[CATEGORY_LABEL]&level=[LEVEL]&level_label=[LEVEL_LABEL]&count=[EVENT_COUNT]&message=[MESSAGE]&link=[DETAILS_URL]

BugMonitor adds a toolbar to your WordPress admin bar showing the current event count. You can disable this toolbar if you prefer a cleaner admin interface. The toolbar provides quick access to recent events without opening the full dashboard.

Each detection can be enabled or disabled individually on the Settings tabs (Functional issues, JavaScript, Network, SEO problems, UI problems, UX problems, Web Vital issues, WordPress). Changes are saved immediately. All detections are on by default except Uptime monitoring, PHP warnings and Deactivate Broken Plugins. Uptime monitoring can be enabled only when the site is connected to an active subscription.

bug_monitor/disable_frontend

Controls whether BugMonitor's frontend monitoring script should be loaded. This is useful for disabling monitoring on specific pages or for specific user roles.

Parameters:

• $disabled (boolean) - Whether to disable frontend monitoring (default: false)

Example:

// Disable BugMonitor for page builders
add_filter('bug_monitor/disable_frontend', function($disabled) {
    // Disable for Elementor editor
    if (isset($_GET['elementor-preview'])) {
        return true;
    }
    // Disable for logged-in administrators
    if (current_user_can('manage_options')) {
        return true;
    }
    return $disabled;
});

bug_monitor/save-settings

Filters the default settings before they are saved. Allows you to programmatically set default monitoring options.

Parameters:

• $settings (array) - Array of default settings

Example:

// Customize default settings
add_filter('bug_monitor/save-settings', function($settings) {
    // Disable PHP warnings by default
    $settings['php/warning'] = '';
    // Enable uptime monitoring by default
    $settings['server/uptime'] = 'on';
    return $settings;
});

bug_monitor/get_option

Filters option values when they are retrieved. Useful for dynamically changing settings based on context.

Parameters:

• $value (mixed) - The option value
• $key (string) - The option key

Example:

// Dynamically modify options
add_filter('bug_monitor/get_option', function($value, $key) {
    // Disable specific monitoring on staging
    if (defined('WP_ENVIRONMENT_TYPE') && WP_ENVIRONMENT_TYPE === 'staging') {
        if ($key === 'server/uptime') {
            return '';
        }
    }
    return $value;
}, 10, 2);

bug_monitor/set_option

Filters option values when they are set for the current request (temporary, not saved to database).

Parameters:

• $value (mixed) - The option value being set
• $key (string) - The option key

bug_monitor/update_option

Filters option values before they are saved to the database. This is called when an option is permanently updated.

Parameters:

• $value (mixed) - The option value being saved
• $key (string) - The option key

Example:

// Validate option values before saving
add_filter('bug_monitor/update_option', function($value, $key) {
    // Ensure event retention is at least 7 days
    if ($key === 'system/event_retention' && intval($value) < 7) {
        return '7';
    }
    return $value;
}, 10, 2);

bug_monitor/event_tick

Controls the time window for grouping similar events. Events occurring within the same tick are grouped together to avoid duplicate reporting.

Parameters:

• $tick (integer) - Time window in seconds (default varies by event type)
• $type (string) - Event type
• $details (string) - Event details
• $url (string) - Affected URL

Example:

// Adjust event grouping window
add_filter('bug_monitor/event_tick', function($tick, $type, $details, $url) {
    // Group WebVitals events over 1 hour instead of 5 minutes
    if (strpos($type, 'webvitals/') === 0) {
        return 3600;
    }
    return $tick;
}, 10, 4);

bug_monitor/event_id

Filters the generated event ID used for grouping similar events. This allows you to customize how events are grouped together.

Parameters:

• $event_id (string) - The generated event ID hash
• $type (string) - Event type
• $details (string) - Event details
• $url (string) - Affected URL
• $tick (integer) - Time tick used in the hash

bug_monitor/session_tick

Controls how long a user session is tracked before starting a new session. Default is 12 hours (43200 seconds).

Parameters:

• $tick (integer) - Session duration in seconds (default: 43200)

Example:

// Extend session tracking to 24 hours
add_filter('bug_monitor/session_tick', function($tick) {
    return 86400; // 24 hours
});

bug_monitor/rate_limit_screenshot_tick

Controls the rate limiting for screenshot captures. Screenshots taken within the same tick for the same issue are deduplicated. Default is 12 hours (43200 seconds).

Parameters:

• $tick (integer) - Rate limit duration in seconds (default: 43200)

Example:

// Capture screenshots more frequently (every 1 hour)
add_filter('bug_monitor/rate_limit_screenshot_tick', function($tick) {
    return 3600; // 1 hour
});

bug_monitor/frontend/init_priority

Controls the priority at which BugMonitor's frontend script is loaded in wp_head. Default is -PHP_INT_MAX to load as early as possible.

Parameters:

• $priority (integer) - Hook priority

bug_monitor_api_request_args

Filters the arguments passed to API requests. Useful for modifying timeout, headers, or other request parameters.

Parameters:

• $args (array) - wp_remote_post arguments

Example:

// Increase API timeout
add_filter('bug_monitor_api_request_args', function($args) {
    $args['timeout'] = 120; // 2 minutes
    return $args;
});

bug_monitor/slow_request_threshold

Sets the duration after which a server-side AJAX or REST request is reported as a Slow Response (since 1.0.2).

Parameters:

• $threshold (integer) - Threshold in milliseconds (default: 3000)

Example:

// Report only requests slower than 5 seconds
add_filter('bug_monitor/slow_request_threshold', function($threshold) {
    return 5000;
});

bug_monitor/slow_request_skip_actions

The admin-ajax actions that are slow by design and are never reported as Slow Response (since 1.0.2).

Parameters:

• $actions (array) - Action names (default: WordPress core actions such as dashboard-widgets, Site Health checks, updates and installs)

bug_monitor/slow_request_skip_routes

REST route prefixes that are never reported as Slow Response (since 1.0.2).

Parameters:

• $routes (array) - Route prefixes (default: array('/wp-site-health/'))

bug_monitor/fatal_notification_interval

Minimum time between two Instant fatal error notifications for the same error (since 1.0.2).

Parameters:

• $interval (integer) - Interval in seconds (default: 3600)

bug_monitor/check_option_{$key}

Filters the result of an option check for the given option key (for example bug_monitor/check_option_php/warning).

Parameters:

• $result (boolean) - Result of the check
• $value (mixed) - The value the option was compared with
• $compare (string) - Comparison operator

bug_monitor/option_updated

Triggered when a BugMonitor option is updated.

Parameters:

• $value (mixed) - The new option value
• $key (string) - The option key

Example:

// Log option changes
add_action('bug_monitor/option_updated', function($value, $key) {
    error_log("BugMonitor option '{$key}' updated to: " . print_r($value, true));
}, 10, 2);

BugMonitor exposes REST API endpoints for receiving event data from the frontend. These endpoints are used internally by the monitoring script but can also be used for custom integrations.

Endpoint: /wp-json/bug-monitor/v1/report/{action}

Available Actions:

• event - Report a new event
• single_event - Report a single occurrence event
• session - Update session data
• screenshot - Upload a screenshot
• mutations - Report DOM mutations