Graphitti

Introduction

The aim of Graphitti is to ease the use of the Render URL API provided by graphite. Graphitti provides a expressive fluid API around the Render URL API.

License

Graphitti is open-sourced software licensed under the MIT license

Installation

This packages works for Laravel versions 5.* and ^6.0 only.

Install Graphitti as you would with any other dependency managed by Composer:

composer require oceandba/graphitti

Configuration

To publish the configuration use the command :

php artisan vendor:publish --provider="OceanDBA\Graphitti\GraphittiServiceProvider" --tag="graphitti-config"

This will create the file config/graphitti.php. Use this file to configure your graphite hosts; the file should be self-explanatory and contains the appropriate configurations needed for you to get started.

Usage

Using Targets

You can create a new Target using the OceanDBA\Graphitti\Metrics\Target class as follows :

use OceanDBA\Graphitti\Metrics\Target;

$target = Target::make('oceandba.server1.load', 'Server-load-1');

You may also add a precision to the Target object which will serve to round DataPoints when retrieved.

$target = Target::make('oceandba.server1.load', 'Server-load-1')->precision(2);

The Target takes two parameters :

1. The path
2. An optional name for the Target

Applying functions to Target

To apply a function to the Target use the function name as a method call on the Target instance and pass parameters to it :

Target::make('oceandba.server1.load', 'Server-load-1')->add(10);

You can also chain the function calls :

Target::make('oceandba.server1.load', 'Server-load-1')
      ->add(10)
      ->aggregate('sum');

Refer to the Graphite Docs for list of available functions.

The Target class uses the Macroable trait of Laravel. So you are free to add your own methods to the class.

use OceanDBA\Graphitti\Metrics\Target;

// ...

public function boot()
{
    Target::macro('validate', function () {
        if(strpos($this->value(), 'oceandba') === false) {
            throw new \InvalidArgumentException('Target is invalid');
        }
        
        return $this;
    });
}

Target::make('oceandba.server1.load', 'Server-load-1')->validate();

Using GraphitePoints

The GraphitePoints class provides an expressive syntax to retrieve DataPoints from Graphite. You should supply at least one Target to the GraphitePoints.

use GraphitePoints;
use OceanDBA\Graphitti\Metrics\Target;

$dataPointsCollection = GraphitePoints::addTarget(Target::make('oceandba.server1.load', 'Server-load-1'))
                                      ->addTarget(Target::make('oceandba.server2.load', 'Server-load-2'))
                                      ->render();

This will return a OceanDBA\Graphitti\Series\DataPointsCollection. The object contains a collection of OceanDBA\Graphitti\Series\DataPoints, both classes are Macroable.

Contraint from/until

You can add time period constrains using the from and until methods available on the GraphitePoints.

 GraphitePoints::addTarget(Target::make('oceandba.server1.load', 'Server-load-1'))
               ->addTarget(Target::make('oceandba.server2.load', 'Server-load-2'))
               ->from('-1h')
               ->until('now')
               ->render()

The methods accept Carbon instances as well as relative time string. Refer to the Graphite Docs for how to form relative time string.

Additional graph parameters

You can add graph parameters using addParameter method on GraphitePoints :

GraphitePoints::addTarget(Target::make('oceandba.server1.load', 'Server-load-1'))
               ->addTarget(Target::make('oceandba.server2.load', 'Server-load-2'))
               ->from('-1h')
               ->until('now')
               ->addParameter('maxDataPoints', 50)
               ->render()

Refer to the Graphite Docs for full list of accepted parameters.

Credits

Big Thanks to all developers who worked hard to create something amazing!

Creator

Twitter: @OceanDBA
GitHub: OceanDBA Ltd