Library for communicating with Cupola logging API.

log, logging, api, Cupola, Nimbus Dynamics


Cupola API Logger

A Nimbus Dynamics product


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.


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


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

Sample Code (tl;dr)

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

    $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

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



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.


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)


Severity Description (Guideline)
Debug Detailed debug information
Info Interesting event
Notice Normal but significant event
Warning Exceptional occurrences that are not errors
Error Runtime errors that do not require immediate action but should typically be logged and monitored
Critical Critical conditions
Alert Action must be taken immediately
Emergency System is unusable

Each severity can be accessed by its lowercase method:


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.


$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.

Key Type Explanation
structured_data array Additional data that shows up underneath an entry in the feed
msgid string A short, easily-identifiable key code for an entry (searchable in the feed)
external_link string An external link (provides easy context from feed)
exception object Will attempt to call getTraceAsString() and append result to structured_data as _backtrace

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).

Key Returns Description
wasError() boolean Returns TRUE if the last call resulted in an error, otherwise FALSE.
wasSuccess() boolean Returns TRUE if the last call went through successfully, otherwise FALSE.
lastID() string Returns the returned entryID of the last-successful call.
remainingCount() integer Returns the number of remaining API calls for the current 24-hour period (extracted from a previous call's headers)
remainingBytes() integer Returns the amount of remaining bytes for the current 24-hour period (extracted from a previous call's headers)