Page tree
Skip to end of metadata
Go to start of metadata

Plugin overview

Moskito PHP plugin gains possibility to monitor your PHP applications. Plugin consist of two parts:

  1. PHP Agent - composer library for php. Set of tools for collecting php application statistics. (GitHub repository)
  2. Moskito PHP Plugin - plugin for moskito to register data that comes from php-agent

Setting up plugin

PHP Agent and Moskito PHP Plugin wires together using RabbitMQ. So it required to have running RabbitMQ instance to make it work.

The easiest way to set up MoSKito PHP Agent is to use docker image with RabbitMQ and MoSKiTo-Inspect ready to use.

1. Enabling agent in your php project

PHP Agent can be enabled through composer.

Add repository to your composer.json file:

composer.json
"repositories" : [
	...
    {
        "type": "vcs",
        "url": "https://github.com/anotheria/moskito-php-agent"
    }
	...
],

And package to require (or require-dev) section:

"anotheria/moskito-php-agent" : "dev-master"

Then run composer update to obtain package. All agent functionality be available by using composer autoloader.

PHP Agent requires configuration named moskito-php-config.json that must be located in root of your project (same where composer.json)

Here is sample configuration (Latests version may be found in php agent github repository):

moskito-php-config.json
{
  "rabbitmq-host" : "localhost",
  "rabbitmq-port" : 5672,
  "rabbitmq-login" : "moskito",
  "rabbitmq-password" : "moskito",
  "rabbitmq-queue-name" : "moskito-php",
  "features" : {
    "enable-execution-producer" : true
  }
}

Configuration defines RabbitMQ connection properties:

  • rabbitmq–host - host of RabbitMQ instance to use;
  • rabbitmq-port - port of RabbitMQ instance to use;
  • rabbitmq-login - login for RabbitMQ connection;
  • rabbitmq-password - password of RabbitMQ connection;
  • rabbitmq-queue-name - name of queue that be used to transfer data to Moskito PHP plugin. Must be configured same as in PHP plugin for Moskito;

Also configuration contains features section, where some of builtin features may be enabled:

  • enable-execution-producer - enables execution statistics producer that will monitor execution time and memory consumption for all php requests.

2. Enabling PHP Plugin in Moskito

Docker setup

Moskito-inspect, that configured to use PHP Agent, with RabbitMQ instance is available as docker image.

docker pull anomo/moskito-php-demo
docker run -p 8088:8088 -p 5672:5672 -t -i anomo/moskito-php-demo

By running this command moskito-inspect be available by 8088 port and will listen to moskito-php RabbitMQ queue. RabbitMQ be available on 5672 port and have user with login moskito and password moskito.

Manual  setup

Moskito-Inspect standalone already goes with MoSKito PHP plugin and it minimal configuration, but it still require to enable plugin connectors.  If you want to use an embedded version you need to set up plugin manually.

Enabling plugin in MoSKito

Insert following dependency to your pom file (moskito-core is also required):

moskito-php dependency
<dependency> 
    <groupId>net.anotheria</groupId>
    <artifactId>moskito-php</artifactId>
    <version>${moskito.version}</version>
</dependency>

Then enable plugin in your moskito.json configuration:

moskito.json plugin
 "@pluginsConfig": {
    "@plugins": [
     ...
      {
        "name": "MoskitoPHPPlugin",
        "configurationName": "moskito-php",
        "className": "net.anotheria.extensions.php.MoskitoPHPPlugin"
      },
	  ...
    ]
  }

Next add configuration json file for plugin and name it as it mentioned in plugin configuration property configurationName. Assuming example above file name should be moskito-php.json. Also that is the plugin config name in moskito-inspect standalone version.

Configuring PHP Plugin

Plugin configuration defines connectors, witch serves as data sources, and mappers that registers producers incoming data.

Here is minimal configuration to run PHP plugin:

moskito-php.json
{
  "@mappers" : [],
  "@connectors" : [
    {
      "connectorClass" : "net.anotheria.extensions.php.connectors.impl.RabbitMQConnector",
	  "enabled" : false
    }
  ]
}
Mappers:

Mapper configuration units is placed in @mappers section. Each mapper config consist of two fields:

mapper-config
{
  "mapperClass" : "net.anotheria.extensions.php.mappers.impl.ExecutionStatsMapper",
  "mapperId" : "ExecutionStatsMapper"
},
  • mapperClass - mapper class canonical name;
  • mapperId - identifier of mapper through witch it can be available in php agent;
Default mappers

Sample minimal configuration do not contain any mappers because PHP plugin have several builtin mappers that not require configuration to enshure that plugin instance can interact with PHP Agent properly without complicated setups. This mappers can be overwritten by explicitly defining mappers with same id in plugin configuration

PHP plugin has following builtin mappers with id:

  • ExecutionStatsMapper - maps php execution stats. Required to map execution stats builtin producer in php agent.

  • ServiceStatsMapper - mapper for service oriented stats producer that can record some code snippet execution time.
  • CounterStatsMapper - mapper for counter stats that simply accumulate some value.
Connectors:

Connector configuration has two required fields connectorClass that defines connector class cannonical name and enabled - is connector should listen to it data source. Also connector configuration can include some connector properties names of  witch begins with ".connector" prefix.

 {
      "connectorClass" : "net.anotheria.extensions.php.connectors.impl.RabbitMQConnector",
      "enabled" : true,
      "connector.host" : "localhost",
      "connector.port" : 5672,
      "connector.username" : "moskito",
      "connector.password" : "moskito",
      "connector.queue-name" : "moskito-php"
 }



This is an example of RabbitMQ connector configuration for PHP plugin with all it available properties and it default values. Unlike for mappers, plugin do not load any builtin connectors and RabbitMQ connector must be explicitly included in config. 

Connectors lifecycle

As it mentioned before, connector configuration has enabled property. This property indicates is connector should do listening of new incoming data in case property is true. If property is false connector should do nothing.

This property may be changed due runtime by editing plugin configuration file. In this case connector will be opened/closed dynamically. 

You may also set JVM property -DforceEnablePHPConnectors to true to force enable all connectors on startup despite plugin json configuration.

RabbitMQ connector

Following properties of RabbitMQ connector may be configured:

  • connector.host - host of RabbitMQ instance to connect;

  • connector.port - port of RabbitMQ instance to connect;
  • connector.username - login for RabbitMQ connection;
  • connector.password - password for RabbitMQ connection;
  • connector.queue-name - name of queue to use for obtaining data. Must be same as in php agent config;

It is not required to define connector property (connector class always must be specified) if there is not need to overwrite it default value (example RabbitMQ config contains all it default values).

Using Moskito PHP

Next section describe how to use Moskito PHP Agent. Lets assume you have php project with included PHP Agent (see our demo project on github) and instance of Moskito with configured php plugin.

PHP Agent already have some producers that ready to use.

Execution statistics producer

With included enable-execution-producer feature PHP agent will send statistics of script execution on each php application call. It been available by php-execution id.

This producer contain statistics per each request url that includes number of requests, time and memory spent on request execution metrics.

Using Counter producer

PHP Agent has ability to count some statistics values by using counter producer.

First of all we need to create CounterProducer class instance:

counter-producer
$counterProducer = new CounterProducer('counter', 'php', 'php');

Counter producer has counstructor with three arguments. First is producer id, second - producer category, third - producer subsystem. 

For increasing some value it simply need to call incStats($name, $by = 1) method of counter producer. Where first argument is statistic name and second optional argument is increasing amount (1 by default):

counter-inc
$counterProducer->incStats('someValue1');
$counterProducer->incStats('someValue2', 4);

By executing code snippets above producer be available by counter id:

Using Service Producer

Service stats producer gives ability to count some code snippet execution time.

First of all we need to create ServiceOrientedProducer class instance:

service-producer
$serviceProducer = new ServiceOrientedProducer('service', 'php', 'php');

Counter producer has counstructor with three arguments. First is producer id, second - producer category, third - producer subsystem. 

Producer object has method getWatcher($statsName) that returns instance of ServiceWatcher class. This object has two methods:

start() and stop($error = false) first method is starts counting execution and second stops count. Argument of second method should indicate is there is an error occured due code snippet execution.

Here is full example of this producer usage:

service-producer demo
$serviceProducer = new ServiceOrientedProducer('service', 'php', 'php');
$executionWatcher = $serviceProducer->getWatcher('sample-execution');
$executionWatcher->start();
// Some long executing code to measure
sleep(3);
$executionWatcher->end();

After executing of this code snippet next producer statistics should appear in moskito:

  • No labels