🏭 XC Industrial Log Analyzer

Server Requirements, Installation, Usage, Troubleshooting & FAQ

📌 Overview

XC Industrial Log Analyzer is a WordPress plugin for uploading and pre-analyzing industrial communication logs and related diagnostic exports. It is designed to generate a preliminary technical report from supported log files using deterministic parsers, with an optional AI-generated narrative layer for easier human interpretation.

This release is centered around:

  • Modbus text logs
  • CAN Vector .asc files
  • Generic CSV files
  • Profibus diagnostic text
  • Drive fault logs in text or CSV form
  • ZIP uploads containing one usable text-like log file
  • Profile packs for vendor/model-specific matching and enrichment
  • Asynchronous processing through WordPress cron jobs
  • Optional downloadable HTML report
  • Optional email summary

This is not a standalone server application. It runs inside WordPress and depends on WordPress core behavior for admin UI, AJAX, cron execution, uploads, database access, and email sending.

✅ Server Requirements

1. Core platform requirements

The package requires:

  • WordPress 6.0 or newer
  • PHP 7.4 or newer
  • A working MySQL/MariaDB-backed WordPress installation
  • Standard WordPress admin and plugin installation capability

This plugin creates and uses custom database tables, stores uploaded files in the WordPress uploads area, and relies on WordPress AJAX and scheduled events.

2. Recommended hosting profile

For reliable operation in production, the server should provide:

  • PHP memory limit: recommended 256 MB or higher
  • Max execution time: recommended 60 seconds or higher
  • upload_max_filesize: at least equal to the plugin’s configured upload limit
  • post_max_size: larger than upload_max_filesize
  • Stable background execution of WordPress cron
  • Writable uploads directory
  • Outbound HTTPS access if optional AI narrative is enabled
  • Working mail transport if email summaries are expected

These are not all hardcoded requirements, but they match how the plugin actually processes uploads and background jobs.

3. PHP extensions and capabilities

Required or strongly recommended

  • fileinfo / finfo
    Recommended for reliable MIME detection and safer upload validation.
  • ZipArchive
    Needed if you want the plugin to process ZIP uploads.
  • JSON support
    Required for profile pack handling and result serialization.
  • OpenSSL / HTTPS-capable outbound requests
    Needed only for the optional AI narrative feature.

Useful but environment-dependent

  • Mail delivery stack compatible with wp_mail() if email notifications are used
  • Proper filesystem permissions for WordPress uploads and plugin operations

4. Web server requirements

The plugin stores uploaded files in a private uploads subfolder under WordPress uploads. That folder should not be directly web-accessible.

Apache

The plugin creates protective files automatically for Apache-based environments.

Nginx

On Nginx, you should add a deny rule for the plugin’s private upload folder so uploaded files cannot be fetched directly over the web.

Keep this as a normal defensive web-server rule. Do not expose the private storage path publicly.

5. WordPress operational requirements

The plugin depends on:

  • AJAX endpoint availability
  • Working WordPress cron
  • Custom tables being creatable on activation
  • Ability to enqueue frontend CSS and JS
  • Admin permissions for configuration pages

If WordPress cron is disabled, blocked, or unreliable, jobs may remain in queued state longer than expected.

For production, it is best to use a real server cron to trigger WordPress cron consistently.

🧩 What the Plugin Installs

On activation, the plugin creates:

  • A jobs table for uploaded analyses
  • A profile packs table for enrichment packs
  • A private upload directory
  • Default plugin settings

It also schedules internal background tasks for:

  • Job processing
  • Daily cleanup of old files

🖥️ Supported Input Types

Officially usable in this package

  • .txt
  • .log
  • .csv
  • .asc
  • .zip

Accepted at upload layer but not ideal to rely on

  • .pcap
  • .pcapng

Important note

This package version accepts .pcap and .pcapng at upload validation level, but it does not include a dedicated parser for them in the shipped parser set. For practical use, you should treat these as non-primary formats unless your workflow converts them into one of the supported text/CSV-style formats first.

🔍 Supported Analysis Modes

Auto-detect

Best for general users. The plugin tries to infer the log family from extension and file content.

Manual protocol selection

Users can explicitly choose:

  • Modbus — gateway text
  • CAN — Vector .asc
  • Generic CSV
  • Profibus — diagnostic text
  • Drive fault log — text
  • Drive fault log — CSV

If unsure, Auto-detect is the safest frontend option.

⚙️ Installation Guide

1. Install the plugin

You can install it by either method:

Option A: WordPress admin

  • Go to Plugins
  • Upload the plugin ZIP
  • Install
  • Activate

Option B: Manual deployment

  • Extract the plugin folder
  • Copy it to:

/wp-content/plugins/

  • Activate it in WordPress admin

2. Confirm activation completed correctly

After activation, verify that:

  • The plugin appears in the admin menu as Log Analyzer
  • The custom admin pages load
  • The private upload directory exists
  • No activation/database errors are shown
  • Saving settings works

If activation succeeded only partially, re-check database permissions and filesystem permissions.

3. Configure plugin settings

Go to:

Log Analyzer → Settings

Set at minimum:

  • Max file size
  • Retention period
  • Frontend theme
  • Optional AI settings if you want narrative generation

Recommended first deployment values:

  • Max file size: 10 MB
  • Retention: 14 days
  • Theme: Inherit or Professional
  • AI narrative: Off until the rest of the workflow is validated

4. Create a frontend page

Create a WordPress page and insert:

[xc_industrial_log_analyzer]

Short alias also supported:

[xc_log_analyzer]

Optional theme override

You can override the configured theme directly in the shortcode:

[xc_industrial_log_analyzer theme="dark"]

Supported values:

  • inherit
  • light
  • dark
  • professional

5. Configure profile packs

Go to:

Log Analyzer → Profile Packs

You can:

  • Install bundled demo/example packs
  • Upload custom JSON packs
  • Enable or disable packs
  • Delete packs
  • Test profile detection without creating a job

For production use, bundled demo packs are useful for initial validation, but real deployment quality depends on good internal dictionaries and fingerprints.

6. Optional AI narrative setup

If you want the plugin to generate a technician-friendly narrative:

  • Enable the AI option in plugin settings
  • Provide an API key through the preferred secure method for your environment
  • Confirm outbound HTTPS connectivity
  • Test with a known-good sample log

AI is optional. The core parsing and rule-based findings remain deterministic.

🚀 How It Works

Frontend flow

  1. User opens the page containing the shortcode
  2. User uploads a supported file
  3. User optionally selects a protocol/format
  4. User may optionally enter an email address
  5. User may optionally request AI narrative
  6. A job is created in the database
  7. Processing runs asynchronously
  8. The page polls job status
  9. When complete, the report is shown in the browser
  10. The user can download an HTML report

Admin flow

From the WordPress admin, operators can manage:

  • General settings
  • Theme behavior
  • Profile packs
  • Jobs list
  • Optional AI configuration

The jobs page shows the most recent entries and basic metadata such as status, protocol, filename, and user email.

📊 What the User Sees in a Report

A completed report may include:

  • Health score
  • Detected protocol
  • Event count
  • Error count
  • Key findings
  • Recommended checks
  • Error event preview
  • Optional AI narrative
  • Downloadable HTML report
  • Optional email summary

The report is a pre-analysis, not a final engineering certification.

🧠 Analysis Logic Summary

Deterministic parsing

The core engine parses logs into normalized events and then evaluates them with rule logic.

Rule output

The system derives:

  • Severity-rated findings
  • Confidence values
  • Error clustering
  • Top nodes with issues
  • Fault code summaries
  • Recommendation lists
  • Decode coverage estimate

Optional enrichment

If a profile pack matches the uploaded content, the plugin can enrich the result with vendor/model-aware decoding hints.

Optional AI narrative

The AI layer does not replace parsing. It only transforms the deterministic findings into a more readable English summary.

📁 ZIP Handling Behavior

ZIP uploads are supported, but the plugin does not unpack arbitrary archive contents for full browsing.

Instead, it tries to extract one usable text-like entry from the archive for analysis.

Operationally, this means:

  • ZIP is best used for single-log bundles
  • Large mixed archives are not ideal
  • The plugin prefers one main usable log file, not a complete multi-file forensic workflow

If your users frequently upload archives, instruct them to ZIP only the single most relevant export.

🧰 Practical Server Tuning Recommendations

Recommended PHP settings

memory_limit = 256M
max_execution_time = 60
upload_max_filesize = 20M
post_max_size = 24M
max_file_uploads = 10

These values are operational recommendations, not strict package constants.

Recommended WordPress setup

  • Persistent cron triggering
  • Clean permalink/admin AJAX behavior
  • Reliable uploads directory permissions
  • Stable outbound HTTPS if AI is enabled
  • Mail delivery configured if user emails are expected

🛠️ Troubleshooting

1. Upload succeeds, but the job stays queued

Likely causes

  • WordPress cron is not running correctly
  • Cron triggering is disabled or delayed
  • The server blocks scheduled execution
  • The site has low traffic and relies only on visitor-driven cron

What to check

  • Verify WordPress cron is operational
  • Prefer a real server cron trigger for reliability
  • Confirm no fatal PHP errors occur during scheduled execution
  • Check that the jobs table is writable and the job status can update

2. Upload fails immediately

Likely causes

  • File exceeds plugin limit
  • PHP upload limit is lower than plugin limit
  • Unsupported extension
  • Extension and detected file type do not match
  • MIME validation rejects the file
  • File content is rejected during safety validation

What to check

  • Compare plugin upload limit with PHP limits
  • Test with a smaller known-good sample file
  • Make sure the file extension matches the real content
  • Avoid renamed or repackaged files that do not match their real type

3. ZIP upload fails

Likely causes

  • ZIP contains no usable text-like log entry
  • ZIP is too large after extraction
  • Archive structure is not suitable
  • ZIP support is missing at PHP level
  • The archive contains multiple files but no clearly usable primary log

What to do

  • Repackage only the single relevant log file
  • Avoid large bundle archives
  • Confirm PHP ZipArchive support exists
  • Prefer direct .txt, .log, .csv, or .asc uploads when possible

4. Report finishes, but AI narrative is missing

Likely causes

  • AI feature disabled in settings
  • No API key configured
  • User did not opt in on the form
  • Outbound HTTPS is blocked
  • Remote request timed out or failed

What to check

  • Ensure AI is enabled
  • Confirm API key exists in the active configuration path
  • Confirm the user ticked the narrative option
  • Test outbound HTTPS from the server
  • Review general WordPress/PHP error logs

5. Report appears, but email was never received

Likely causes

  • Invalid email entry
  • Mail transport not configured
  • Hosting blocks mail delivery
  • Message delivered to spam/quarantine
  • Deliverability issues on the domain

What to check

  • Test wp_mail() separately
  • Use SMTP or a reliable mail relay
  • Review spam filtering and sender reputation
  • Confirm the user entered a real email address

6. No profile pack match is found

Likely causes

  • No packs installed
  • Packs are installed but disabled
  • Fingerprints are too weak or too generic
  • Uploaded file does not contain identifiable vendor/model hints in the inspected section

What to do

  • Confirm packs are installed and enabled
  • Test with the built-in detection tool
  • Improve fingerprint quality in your custom JSON pack
  • Use logs that include model/family/export metadata near the start of the file

7. The report looks incomplete

Possible reasons

  • Preview tables are intentionally limited
  • The uploaded file format is only partially structured
  • The selected parser is not the best fit
  • Auto-detect fell back to a less suitable parser
  • Generic CSV mapping did not find ideal column names

What to do

  • Retry with explicit protocol selection
  • Use cleaner export formats when possible
  • Ensure CSV headers are meaningful
  • Prefer vendor-native exports over screenshots or ad-hoc text dumps

8. The page loads, but styling or interactivity is wrong

Likely causes

  • Theme or cache conflict
  • Frontend assets not loading
  • Script minification or optimization plugin interference
  • CDN caching old assets

What to check

  • Disable aggressive JS/CSS optimization temporarily
  • Clear all caches
  • Confirm the shortcode is on a singular page/post context
  • Test with theme override such as theme="light" or theme="dark"

9. The analyzer shows “service unavailable”

Likely causes

  • The plugin is not fully in operational state
  • A critical prerequisite is missing
  • An admin-side condition is blocking frontend processing

What to check

  • Review admin notices
  • Re-check plugin configuration
  • Confirm activation completed cleanly
  • Confirm scheduled processing and core settings are healthy

10. PCAP or PCAPNG uploads do not produce meaningful results

Explanation

This package version accepts those extensions at upload validation level, but the shipped parser set does not provide a dedicated PCAP/PCAPNG parser.

Recommended approach

Convert packet captures into a supported text or CSV-based export before uploading.

🧪 Production Readiness Checklist

Before go-live

  • WordPress updated and healthy
  • PHP version compatible
  • Database tables created
  • Upload directory writable
  • Private upload path protected
  • WP-Cron reliable
  • Frontend page published
  • Known-good sample logs tested
  • Email sending tested if needed
  • Optional AI tested with one controlled case
  • Profile packs installed and validated

📚 FAQ

❓Is this a standalone application?

No. It is a WordPress plugin and must run inside a working WordPress installation.

❓Does it process files synchronously in the browser request?

No. It creates a job and processes it asynchronously through WordPress scheduled execution.

❓Can I place the shortcode on any page?

Yes. That is the intended frontend deployment method.

❓Can users download the final result?

Yes. The frontend includes a Download Report action that generates an HTML report.

❓Does it store uploaded files?

Yes, temporarily, in a private uploads area. Retention is configurable.

❓Does deactivation remove the data?

No. Deactivation stops scheduled events, but full cleanup behavior is tied to uninstall/delete behavior.

❓Can it analyze ZIP files?

Yes, but best for ZIPs that contain a single relevant text-like log.

❓Can it enrich reports for specific vendors?

Yes. That is what profile packs are for.

❓Does AI replace deterministic analysis?

No. AI is optional and used only as a narrative/explanation layer.

❓Is the UI multilingual?

This package is currently English-oriented in interface text and generated narrative behavior.

❓Does it support CAN, Modbus, Profibus, and drive faults out of the box?

Yes, for the parser families shipped in this package. The best results come from clean exports that match the expected input patterns.

❓Should I rely on PCAP support in this release?

No. Treat PCAP/PCAPNG as upload-accepted but not fully parser-backed in this version.

📝 Best Practices

For administrators

  • Keep upload limits realistic
  • Use reliable cron triggering
  • Protect the private upload directory
  • Start with deterministic mode first
  • Add AI only after the core workflow is stable
  • Validate profile packs carefully before production use

For end users

  • Upload clean raw exports, not screenshots
  • Prefer plain text, CSV, or .asc
  • Use ZIP only when necessary
  • Leave protocol on Auto-detect unless you know the format
  • Enter an email only if you really need the summary sent

✅ Final Recommendation

For deployment, treat XC Industrial Log Analyzer as a WordPress-integrated diagnostic pre-analysis tool, not as a heavy standalone log-processing platform. Its strongest production use case is:

  • controlled upload sizes,
  • supported structured exports,
  • reliable WordPress cron,
  • optional vendor enrichment via profile packs,
  • and optional AI narrative for readability.

Its weakest area in this release is that some accepted file types, especially PCAP/PCAPNG, should not be marketed as first-class parsing formats without a dedicated parser layer.