README

Enterprise-Grade Observability, Debugging, and Performance Monitoring Suite for CodeIgniter 3.

Inspired by Laravel Telescope, CI Telescope provides complete visibility into your CodeIgniter 3 application behavior. It seamlessly captures incoming HTTP requests, executed SQL queries (with slow query and N+1 duplicate detection), uncaught exceptions, system logs, cache operations, outgoing emails, external API calls, dispatched events, session data, and server environment metrics—all presented in a modern, real-time SPA dashboard.

✨ Key Features

🚀 Zero-Intrusion Integration: Hooks into standard CodeIgniter 3 lifecycle events without altering existing controller or model code.
📊 Modern SPA Dashboard: Dark/Light mode theme built with Tabler/Bootstrap 5, Chart.js live analytics, real-time 5-second polling, and detail inspector modals.
⚡ SQL Profiler & N+1 Detector: Tracks SQL execution time, flags slow queries (>100ms), highlights duplicate queries, and displays backtrace file & line number.
🛡️ Sensitive Data Masking: Automatically scrubs passwords, secrets, bearer tokens, credit card numbers, and authorization headers from telemetry.
💾 Flexible Dual Storage: Supports both MySQL PDO/ActiveRecord and zero-config SQLite PDO (application/cache/telescope.sqlite) fallback storage.
💻 Full CLI Utilities: Easy CLI management via php index.php telescope [install|status|clear|prune|export].
✉️ Email Monitor with HTML Preview: Live iframe modal rendering for captured outgoing application emails.
⚡ Event Dispatcher: Includes a standalone event dispatcher (Events::dispatch()) to add event-driven telemetry to CI3.

📦 Requirements

PHP: 7.4 or 8.x (Fully tested and compatible with PHP 8.4)
CodeIgniter: 3.1.x
Extensions: pdo_sqlite or pdo_mysql, json

⚙️ Installation

1. Install via Composer

Add the package to your composer.json or run:

composer require vickychhetri/ci-telescope

(For local repository development):

"repositories": [
    {
        "type": "path",
        "url": "./packages/ci-telescope"
    }
]

2. Enable CodeIgniter Composer Autoload & Hooks

Ensure Composer autoloading and system hooks are enabled in application/config/config.php:

$config['enable_hooks'] = TRUE;
$config['composer_autoload'] = 'vendor/autoload.php';

3. Run the Automated Installer CLI

Execute the Telescope installer command from your project terminal:

php index.php telescope install

The installer will automatically:

Create the database storage tables (MySQL or SQLite fallback).
Publish application/config/telescope.php.
Register system hooks in application/config/hooks.php.
Register dashboard routes in application/config/routes.php.

🖥️ Accessing the Dashboard

Once installed, open your browser and navigate to:

http://your-domain.com/index.php/telescope

🎯 Interactive Demo

You can test all collectors immediately by running the built-in demo routes:

http://your-domain.com/index.php/demo (Demo Hub)
http://your-domain.com/index.php/demo/query (Trigger SQL & N+1 Queries)
http://your-domain.com/index.php/demo/log (Generate Log Entries)
http://your-domain.com/index.php/demo/email (Preview Outgoing Email)
http://your-domain.com/index.php/demo/api (Log External API Calls)
http://your-domain.com/index.php/demo/event (Dispatch Events)
http://your-domain.com/index.php/demo/cache (Log Cache Operations)
http://your-domain.com/index.php/demo/exception (Simulate Exception)

🛠️ CLI Management Commands

CI Telescope includes a command-line interface for maintenance and administration:

# Display Telescope status, system details, and record counts
php index.php telescope status

# Purge all captured telemetry records
php index.php telescope clear

# Prune telemetry entries older than 24 hours (default: 48)
php index.php telescope prune 24

# Export stored telemetry to a JSON file in application/cache/
php index.php telescope export export_backup.json

# Uninstall Telescope database tables
php index.php telescope uninstall

🔧 Configuration Options

Configuration is located at application/config/telescope.php:

$config['telescope'] = [
    // Enable or disable Telescope monitoring
    'enabled' => TRUE,

    // Dashboard path prefix
    'path' => 'telescope',

    // Toggle specific telemetry collectors
    'store_requests'   => TRUE,
    'store_queries'    => TRUE,
    'store_exceptions' => TRUE,
    'store_logs'       => TRUE,
    'store_emails'     => TRUE,
    'store_sessions'   => TRUE,
    'store_cache'      => TRUE,
    'store_api'        => TRUE,
    'store_events'     => TRUE,
    'store_models'     => TRUE,

    // Performance thresholds
    'slow_query_limit'   => 100,  // Latency in ms to trigger slow-query tag
    'slow_request_limit' => 1000, // Latency in ms to trigger slow-request tag

    // Routes excluded from monitoring to prevent self-referential logging
    'ignore_routes' => [
        'telescope*',
        'assets/*',
    ],

    // Sensitive field names automatically scrubbed from inputs, headers, and payloads
    'hidden_fields' => [
        'password',
        'password_confirmation',
        'secret',
        'token',
        'authorization',
        'credit_card',
        'cvv',
        'api_key',
    ],
];

💻 Manual Logging & Helper API

In addition to automatic hook monitoring, you can record custom telemetry directly from your controllers or libraries:

Log Custom SQL Queries

use CiTelescope\Collectors\QueryCollector;

QueryCollector::logQuery("SELECT * FROM users WHERE active = 1", $durationMs = 12.5);

Log Custom Events

use CiTelescope\Events\Events;

// Register an event listener
Events::listen('order.shipped', function($order) {
    // Custom handling code...
});

// Dispatch event
Events::dispatch('order.shipped', ['order_id' => 991, 'courier' => 'FedEx']);

Log Custom Application Logs

use CiTelescope\Collectors\LogCollector;

LogCollector::log('info', 'Payment callback received for Invoice #INV-1092');

Log Outgoing Emails

use CiTelescope\Collectors\EmailCollector;

EmailCollector::logEmail([
    'from' => 'sales@example.com',
    'to' => ['client@example.com'],
    'subject' => 'Your Invoice #INV-1092',
    'body_html' => '<h1>Invoice Confirmation</h1>',
    'status' => 'sent'
]);

Log External API Calls

use CiTelescope\Collectors\ApiCollector;

ApiCollector::logApiCall(
    'https://api.stripe.com/v1/charges',
    'POST',
    ['amount' => 2000, 'currency' => 'usd'],
    ['id' => 'ch_12345', 'status' => 'succeeded'],
    ['Authorization' => 'Bearer secret_key'],
    145.2,
    200
);

🧪 Running Package Tests

Run the PHPUnit test suite using:

./vendor/bin/phpunit -c packages/ci-telescope/phpunit.xml

📄 License

This package is open-source software licensed under the MIT license.

vickychhetri / ci-telescope

Maintainers

Package info

Statistics

Security