README

   )\.-.       .'(     /`-.      .-./(    )\.--.          )\.-.      /`-.   )\.---.   )\   )\   .')      .'(   )\  )\  
 ,' ,-,_)  ,') \  )  ,' _  \   ,'     )  (   ._.'       ,' ,-,_)   ,' _  \ (   ,-._( (  ',/ /  ( /       \  ) (  \, /  
(  .   _  (  '-' (  (  '-' (  (  .-, (    `-.`.        (  .   __  (  '-' (  \  '-,    )    (    ))       ) (   ) \ (   
 ) '..' )  ) .-.  )  )   _  )  ) '._\ )  ,_ (  \        ) '._\ _)  ) ,_ .'   ) ,-`   (  \(\ \   )'._.-.  \  ) ( ( \ \  
(  ,   (  (  ,  ) \ (  ,' ) \ (  ,   (  (  '.)  )      (  ,   (   (  ' ) \  (  ``-.   `.) /  ) (       )  ) \  `.)/  ) 
 )/'._.'   )/    )/  )/    )/  )/ ._.'   '._,_.'        )/'._.'    )/   )/   )..-.(       '.(   )/,__.'    )/     '.(

Chaos Gremlin

Chaos Gremlin is a PHP chaos testing tool, it introduces random problems into your application that simulate latency, CPU use, memory use, high disk use etc. This tool is for testing how well your application recovers from unknown events.

USE WITH CAUTION some of these Gremlins will not stop until you manually kill the process. Enable only the Gremlins you want to use and review the settings.

THIS IS INTENDED FOR TESTING YOUR OWN APPLICATIONS OR APPLICATIONS YOU HAVE PERMISSION TO TEST

Install with: composer require dvnc0/chaos-gremlin

Requirements

PHP pcntl extension must be installed.
The log directory must be writable by the PHP process.
The Disk Gremlin directory must be writable by the PHP process.

Default Settings

protected array $settings = [
	'probability' => 30,
	'min_latency_seconds' => 2,
	'max_latency_seconds' => 10,
	'exception_message' => 'Chaos Gremlin Exception',
	'dice_roll_over_under' => 3.5,
	'max_memory_percent' => 90,
	'disk_gremlin_directory' => '',
	'disk_gremlin_number_files' => 100,
	'disk_gremlin_file_size' => 5 * 1024 * 1024,
	'traffic_requests' => 100,
	'traffic_url' => 'http://localhost:8080',
	'log_directory' => '',
	'traffic_gremlin_spawns_gremlins' => false,
];

These are the default settings for Chaos Gremlin and can be changed by using the settings method. We will cover that later in this README.

Setting	Description
probability	The probability a Gremlin will be released into the system
min_latency_seconds	The minimum latency a Latency_Gremlin should add
max_latency_seconds	The maximum latency a Latency_Gremlin should add
exception_message	The message that will be thrown with the Exception_Gremlin
dice_roll_over_under	The number that the dice will roll over or under to release a Gremlin
max_memory_percent	The maximum memory percentage that the Memory_Gremlin will use
disk_gremlin_directory REQUIRED	The directory that the Disk_Gremlin will create files in
disk_gremlin_number_files	The number of files the Disk_Gremlin will create
disk_gremlin_file_size	The size of the files the Disk_Gremlin will create
traffic_requests	The number of requests the Traffic_Gremlin will make
traffic_url	The URL the Traffic_Gremlin will make requests to
log_directory REQUIRED	The directory that the logs will be saved to
traffic_gremlin_spawns_gremlins	If the Traffic_Gremlin should spawn other Gremlins, this can get out of hand quick

Using Chaos Gremlin

To use Chaos Gremlin you will need to create an instance of the Gremlin class, enable any Gremlins you would like to use, and then call the release method. This may release the Gremlins into your application.

<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';

use ChaosGremlin\Chaos_Gremlin;

$Gremlin = Chaos_Gremlin::getInstance();
$Gremlin->enableGremlin('Memory_Gremlin');

$Gremlin->release();

The above code will create an instance of the Gremlin class, enable the Memory_Gremlin, and then release the Gremlins into the application. The Gremlin will then use 90% of the memory available to PHP or 90% of the system memory. This is using the default settings listed above.

Available Gremlins

There are a number of Gremlins available to use in Chaos Gremlin. You can enable any of the following Gremlins by using the enableGremlin method.

Gremlin Name	Description
Latency_Gremlin	Adds a random amount of latency to a request
Exception_Gremlin	Throws an Exception
Memory_Gremlin	Consumes memory until the percent set in the settings array
Disk_Gremlin	Writes files to disk
Traffic_Gremlin	Makes requests to the defined endpoint
Cpu_Gremlin	Consumes CPU
Black_Hole_Gremlin	Writes a random amount of data to /dev/null
Die_Gremlin	Calls PHPs `die` function

Traffic Gremlin

The Traffic Gremlin will make requests to the URL set in the settings array. This can be used to test how your application handles a large number of requests. By default requests from the Traffic Gremlin will not spawn other Gremlins, this can be changed by setting the traffic_gremlin_spawns_gremlins setting to true. Again, be cautious with this setting as it can spawn a large number of Gremlins depending on your settings, including more Traffic Gremlins which could create additional Gremlins etc, etc.

Adding custom settings

<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';

use ChaosGremlin\Chaos_Gremlin;

$Gremlin = Chaos_Gremlin::getInstance();
$Gremlin->settings([
	'probability' => 75,
	'min_latency_seconds' => 5,
	'max_latency_seconds' => 10,
	'max_memory_percent' => 90,
	'disk_gremlin_number_files' => 1000,
	'disk_gremlin_file_size' => 5 * 1024 * 1024,
	'traffic_requests' => 500,
	'traffic_url' => 'http://localhost:9000',
]);
$Gremlin->enableGremlin('Memory_Gremlin');
$Gremlin->enableGremlin('Disk_Gremlin');
$Gremlin->enableGremlin('Traffic_Gremlin');
$Gremlin->enableGremlin('Cpu_Gremlin');
$Gremlin->enableGremlin('Latency_Gremlin');

$Gremlin->release();

Custom Gremlins

You can create your own Gremlins by extending the Gremlin class and implementing the attack method.

abstract public function attack(): void;

The settings array will be passed to the custom Gremlin and the following methods are available to the Gremlin.

Method	Description	Return
rollDice	Rolls a dice to see if the Gremlin should be released	bool
getDiceRoll	Returns a random number between 1-6	int
probabilityCheck	Decides if a Gremlin should be released based on the probability setting	bool
writeToLog	Writes a message to the log file	void
getFork	Forks the process	int

To enable the custom Gremlin use the addGremlin method which takes a string key and an instance of the custom Gremlin.

<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';

use ChaosGremlin\Chaos_Gremlin;
use Custom_Database_Gremlin;

$Gremlin = Chaos_Gremlin::getInstance();
$Gremlin->settings([
	'probability' => 75,
	'min_latency_seconds' => 5,
	'max_latency_seconds' => 10,
	'max_memory_percent' => 90,
	'disk_gremlin_number_files' => 1000,
	'disk_gremlin_file_size' => 5 * 1024 * 1024,
	'traffic_requests' => 500,
	'traffic_url' => 'http://localhost:9000',
]);
$Gremlin->enableGremlin('Memory_Gremlin');
$Gremlin->enableGremlin('Disk_Gremlin');

$Gremlin->addGremlin('Database_Gremlin', new Custom_Database_Gremlin());

$Gremlin->release();

To release the custom Gremlin you will need to call the summonGremlin method using the key you set when enabling the Gremlin. This allows you to decide when to attempt to release a Gremlin allowing you to add Gremlins into specific parts of your application.

<?php
declare(strict_types=1);
require_once 'vendor/autoload.php';

use ChaosGremlin\Chaos_Gremlin;

$Gremlin = Chaos_Gremlin::getInstance();

$Gremlin->summonGremlin('Database_Gremlin');

dvnc0 / chaos-gremlin

Maintainers

Details