Cupola API Logger

https://cupo.la

A Nimbus Dynamics product

Description

Designed to be used with the API logging service, Cupola. Before use, you must have generated both a Public and Private API key for your organization.

Issues

Please only open issues related to this package. API or Dashboard-related issues should be submitted on the Cupola contact page

Usage

This package implements Psr\Log\LoggerInterface, per PSR-3 and RFC 5424.

Sample Code (tl;dr)

$publicKey = '[40-character key]';
$secretKey = '[64-character key]';

try
{
    $log = new NimbusDynamics\Cupola\Cupola();
    $log->setKeys($publicKey, $secretKey);
}
catch (Exception $e)
{
    // die($e->getMessage());
}


// Loop over a list of things to do
foreach($pretendArray as $item)
{
    if (!$item->doSomething())
    {
        $additionalInfo =
        [
            'msgid' => 'item-failed',
            'structured_data =>
            [
                'itemID' => $item->ID,
                'itemProperty' => $item->property
            ]
        ];

        try
        {
            $log->error($item->name . ' failed.', $additionalInfo);
        }
        catch(Exception $e)
        {
            // die($e->getMessage());
        }
    }

}

Initialization

The Public and Private keys can be provided upon initialization or with setKeys():

$log = new Cupola($publicKey, $privateKey);
// or
$log = new Cupola();
$log->setKeys($publicKey, $privateKey);

The latter can also be used to switch to a new set of API credentials later on in a script.

Arguments

Each severity accepts two arguments, $message and $context.

• $message is the main content of the entry; the point you're trying to get across.
• $context allows extra information to be sent to Cupola (see "$context Argument" below)

Severities

Each severity can be accessed by its lowercase method:

$log->debug()
$log->info()
$log->notice()
$log->warning()
$log->error()
$log->critical()
$log->alert()
$log->emergency()

A ninth method, $log->log() accepts the first parameter as the log level, e.g $log->log('notice', $message, $context)

$context Argument

The $context argument plays a few roles.

Placeholder substitution

Passing a string wrapped in curly braces in $message and a corresponding key in $context will alter the $message with the replaced value. This only works if the value is a string, implements __toString() or is an Exception.

Example:

$log->notice('{service} is awesome!', [ 'service' => 'Cupola' ]);
// $message will be "Cupola is awesome!"

Passing an object containing a __toString() method will use the return of __toString().

If an exception is used, getMessage() will be called.

Cupola-specific keys

All are optional.

Additional Methods

Although most of the time, "set it and forget it" prevails, if you wish to get more information, several methods are available (useful during initial development).