Usage

Installation

Palzin CodeIgniter can be easily installed via Composer, leveraging CodeIgniter4's autoloading feature. Simply run the following command:

composer require palzin-apm/palzin-codeigniter

Alternatively, you can manually install the library by downloading the source files and adding the directory to the app/Config/Autoload.php file.

Setup

In order to start using the integration library, you will need to create a config class for it.

> ./spark make:config Palzin

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class Palzin extends BaseConfig
{
    /**
     * Set the value to true if you want all your controller methods to be automatically inspected.
     * Set the value to false if you prefer to define your own inspection points, which offers greater flexibility.
     *
     * @var bool
     */
    public $AutoInspect  = true;

    /**
     * To enable sending unhandled exceptions to the Palzin dashboard, 
     * set this option to true. By default, it is set to false for backward compatibility.
     * 
     * @var bool
     */
    public $LogUnhandledExceptions = false;
    
    /**
     * Palzin Monitor (APM) ingestion key, you can find this on your palzin dashboard
     *
     * @var string
     */
    public $PalzinMonitorAPMIngestionKey = 'YOUR_INGESTION_KEY';
    
    /**
     * @var bool
     */
    public $Enable = true;
    
    /**
     * Remote endpoint to send data.
     *
     * @var string
     */
    public $URL = 'https://demo.palzin.app';
    
    /**
     * @var string
     */
    public $Transport = 'async';
    
    /**
     * Transport options.
     *
     * @var array
     */
    public $Options = [];
    
    /**
     * Max numbers of items to collect in a single session.
     *
     * @var int
     */
    public $MaxItems = 100;
}

Usage

To use the Palzin Monitor library integration use the palzin service.

$palzinInstance = service('palzin');

With AutoInspect set to true, you don't need to do anything else, your application will start being inspected automatically, this is made possible by the use of CI4 events functionality in the post_controller_constructor the code will start a segment, providing the controller as the title and the method name as the label. Then in the post_system it will end the segment, which means from the start of the incoming request till result delivery, your code paths will be 'tracked' and the results submitted to palzin.app. And that's it.

You may however need finer grained control over your code points and maybe need to access other more powerful Palzin Monitor (APM) functionality, and this is where the service comes in. Here we present just a few useful methods, check the Palzin Monitor (APM) documentation for more methods and features.

You can add a segment from anywhere in your code (assuming this is in your controller method getUsers):

/* gets JSON payload of $limit users */
public function getUsers(int $limit)
{
  return $palzinInstance->addSegment(function() {
    $userModel = new UserModel();
    $users = $userModel->findAll($limit);
    $this->response->setStatusCode(200, 'OK')->setJSON($users, true)->send();
  }, 'getUsers', 'Get Users');
}

You can report an exception from anywhere in your code as well (assuming this is your model method, where you validate stuff).

/* validate the user has the proper age set */
public function isActiveAttribute(): bool
{
  try {
    if($this->monitor->active === true) {
      throw new \Exception('Status is active so it means danger.');
    }
  } catch (\Exception $e) {
    $palzinInstance->reportException($e);
    /* Your exception handling code... */
  }
}

Using the Helper

To use the helper, you need to load it first using the helper() method. You can do this in your code by calling the helper() method and passing the helper name as an argument. Another option is to configure your BaseController to always load the helper.

helper('palzin');

/* get an instance of palzin */
$palzinInstance = palzin();

/* add a segment through the helper */
palzin(function () {
  /* run your code here... */
  $asyncData = $this->checkWebsite('https://doesthissiteworkforyou.test');
  return $this->checkWebsiteSyncJob($asyncData);
}, 'data-load', 'Website Check Flow');

/* add a segment through the instance */
$palzinInstance->addSegment(function ($segment) use ($config) {
            usleep(10 * 1000);

            $segment->addContext('example payload', ['key' => $config->get('palzin.key')]);
        }, 'test', 'Check Palzin Monitor (APM) Ingestion key');

/* set an exception */
$palzinInstance->reportException(new \Exception('First Exception detected using Palzin Monitor (APM)'));

Note: Due to the shorthand nature of the helper function it can only add a segment or return a service instance.