Download the PHP package pluggit/monitoring without Composer

Pluggit Monitoring

Monitoring is an application monitor and event service, which gives you the ability to monitor and health check from the code.

Installation

Require the library as usual:

Types of monitoring data

Metrics

Metric are statistic values taken at a given point, so it can be graphed and aggregated to be studied.

Supported Metrics

• Counter: Tracks how many times something happened like the number of database requests or page views.
• Gauge: Measure the value of a particular thing at a particular time, like the amount of fuel in a car’s gas tank or the number of users connected to a system.
• Histogram: Track the statistical distribution of a set of values, like the duration of a number of database queries or the size of files uploaded by users.
• Sets: Are used to count the number of unique elements in a group. If you want to track the number of unique visitor to your site, sets are a great way to do that.
• Timers: Timers are essentially a special case of histograms, but specifically sending time measures.

Events

Events are useful to give context information over the metrics, for example tag a new release, a server migration or a library update.

How to use the Monitoring libraries

Two new entities have been defined to model real world usage to code.

The metric entity

The metric entity contains all the information a metric must have.

• Name: The metric name.
• Type: The metric type.
• Value: The metric value. Different type depending on the metric type
• Tags: Associated tags with the metric, it has to be a keyed array. Use them to segregate the data.
• Sample rate: An integer greater than 0 and less or equal than 1. Use it to sample the metric, .I. ex: to send only a 10% of the metrics set a sample rate of 0.1.

The event entity

The event entity describes an occurred event at one specific moment.

• Title: Short event title.
• Text: Long description of the event if necessary.
• Host: The host where the event occurred.
• Timestamp: The exact time when the event occurred.
• Tags: Associated tags with the metric, it has to be a keyed array.
• Type: Indicates the type of event: one of info, success, warning or error.

Creating the entities

There are two factories created to facilitate the creation of the entities, both allow the creation of the entities and provide default data and tags for them in one step

• MetricFactory: Allows the creation of metrics with default tags and prefixes
• EventFactory: Allow the creation of Event entities with default host and tags

NOTE: Both factories allow to add more default tags after they are instantiated using the method:

Send the metrics/events to back end storage

Once you have one of this entities you can send them to different back ends (i.ex: log files, email, DataDog, statsd server, etc.). The Senders are the classes that know of to send a Metric or an Event to a back end storage.

They have to comply with the Metric/SenderInterface interface to send metrics:

Or the Event/SenderInterface interface to send events

The monitor

To ease the creation and the sending of the metrics and events a new class Monitor has been created, for most common use cases this is the only class you will have to interact with from the code.

Configuration of the monitor

the monitor requires both the metric and the event factory as dependencies, it also requires a Monolog logger that will register the posible exceptions that are found. The monitor will prevent all exceptions from being raised, so the normal execution flow of the code using the monitor won't be broken by any exception in the monitoring libraries After the monitor is created, it has to be populated with the metric and events senders using this methods:

NOTE: If no senders are pushed the monitor, it will work normally but will not send the metric to any backend, so it is a nice way to disable the monitor temporary.

Accesing the factories

You can access the factories inside the monitor (for example to add more default tags) with those two accessors:

One-step methods

The monitor can create metrics and events and send them to all backend with one step methods:

• counter: This method will create and send a counter metric with the given count.

• increment: This method will increment a counter metric in +1 and send it.

• decrement: This method will decrement a counter metric in -1 and send it.

• gauge: This method will create and send a gauge metric with the given level.

• set: It will create a set counter with the given unique value and send it.

• histogram: This method will create and send a histogram metric with the given duration in milliseconds.

• start: This method will create a timer and begin to count the milliseconds, this method will not send the metric yet.

• end: This method has to be called after a timer has been started, and it will calculate the time spend between the starting time and the end time and then send the metric. You can also pass new tags that will be merged to those specified when starting the timer.

• event: This method will create and send an event, if the timestamp is not given the current time will be used

Sending custom metrics or events with the monitor

The monitor class can also send custom metrics and events with the methods:

Typical setup

NOTE: Now there is a factory that can be used to ease the creation method, see the next section For using the monitor the typical steps are:

• Create a monitor with the provided Metric and Event factories
• Create and push the metric senders and events sender to the monitor
• Start sending metrics and events with the monitor

This code is a simplified demonstration of the setup process without the object dependencies.

Creation through the factory

NOTE The factory comes with some default values, you can see them in the MonitorFactory code

Available back end senders

Psr-3 logger

With the psr-3 compatible sender you can send events and metrics to PS-3 Logger Handlers. The typical case scenario will be log to files but you can setup very powerful handlers by plug in, for example, Monolog (let you log to databases, send mails or send the metrics and events to online platforms like Splunk. Of course, you can also build custom ones.)

composer.json``` file

Example of setup for the metric sender with native CURL transport

IMPORTANT NOTE: This sender will perform synchronous HTTP requests, so it's not recommended using it on user applications. (see Message back end sender to see how can be used asynchronous)

Message

These senders are not usual senders because they don't directly perform operation to metrics or events.

This back ends senders make use of the Message system libraries included on the CMP/base libraries to be able to send metrics and events to a messaging system, so they can be processed by other senders in an asynchronous way

Imagine we want to send an event to DataDog using the datadog event sender every time a user upgrades his account, if we do it directly with the native datadog sender we are going to block the user with a synchronous call to DataDog's HTTP API, so we can use this back end sender to make the request asynchronous.

Example of the Message event sender using RabbitMQ as messaging system

Now there should be another daemon task that will read the event messages and send them to other senders

NOTE ON ASYNCHRONOUS METRICS: The metrics don't have a timestamp, so if there is a delay while consuming the messages the metrics will be delayed. The worst case could be if the consumer crashes and then is restarted later, it start consuming queued message and generate a lot of metrics with wrong timestamps