Logging

In order to learn more about what is happening in your dashboard application, KoolReport's Dashboard provide you a robust logging services that allow you to write messages to files, system error log or even to Slack channels to notify your team.

Dashboard logging based on "channel". Each channels define a specific way to write message. For example, "stream" channel can allow you to write message to file, while "slack" channel allows you to send message to a slack channel. Logging message can be written to multiple channels depending on its severity.

Under the hood, KoolReport's Dashboard use Monolog, a powerful logging library to get the job done. If you have not known about Monolog, it is a great library with proven powerfulness and stability. KoolReport's Dashboard provide easier settings via our Log class that allow you to quickly set up logging system.

Configuration #

Your dashboard will need to have its own logging class that derived from our \koolreport\dashboard\Log class. Inside your class, you will define your own settings.

Example:

<?php
//AppLog.php

class AppLog extends \koolreport\dashboard\Log
{
    protected function settings()
    {
        return [
            "mychannel"=>[                                      //Channel name, any name
                "stream"=>[                                     //Handler name
                    "stream"=>dirname(__DIR__)."/logs/app.log", //Settings
                    "level"=>"debug",
                ]
            ]
        ];
    }
}

Above code, we define a channel named "mychannel" with 1 handler called "stream". The settings for stream are the file name and the level of severity to trigger writing to this handle (in this case is "debug" the lowest level of severity).

Level of severity #

The handler will be triggered if the message severity is greater or equal to handler's level. Here is increasing level of severity that you set for each handler:

  1. "debug"
  2. "info"
  3. "notice"
  4. "warning"
  5. "error"
  6. "critical"
  7. "alert"
  8. "emergency"

Most used channel handlers #

Namedescription
streamA StreamHandler based Monolog driver to stream message to log file
slackA SlackWebhookHandler based Monolog driver
rotatingFileA RotatingFileHandler based Monolog driver
syslogA SyslogUdpHandler based Monolog driver
syslogudpA SyslogUdpHandler based Monolog driver
errorlogA ErrorLogHandler based Monolog driver

Example:

class AppLog extends \koolreport\dashboard\Log
{
    protected function settings()
    {
        return [
            "mychannel"=>[                                      
                "stream"=>[
                    "stream"=>dirname(__DIR__)."/logs/app.log", 
                    "level"=>"debug",                           
                    "buddle"=>true,
                    "filePermission"=>
                    "useLocking"=>false
                ],
                "slack"=>[
                    "webhookUrl"=>"https://...",
                    "channel"=>"app-error",
                    "username"=>"username"
                    "useAttachment"=>true,
                    "iconEmoji"=>null,
                    "useShortAttachment"=>false,
                    "includeContextAndExtra"=>false,
                    "level"=>"critical",
                    "bubble"=>true,
                    "excludeFields"=>[],
                ],
                "rotatingFile"=>[
                    "filename"=>"path/to/file"
                    "maxFiles"=>0,
                    "level"=>"debug",
                    "buddle"=>true,
                    "filePermission"=>null,
                    "useLocking"=>false
                ],
                "syslog"=>[
                    "ident"=>"",
                    "facility"=>LOG_USER,
                    "level"=>"debug",
                    "bubble"=>true,
                    "logopts"=>LOG_PID,
                ],
                "syslogudp"=>[
                    "host"=>"host",
                    "port"=>514,
                    "facility"=>LOG_USER,
                    "level"=>"debug",
                    "bubble"=>true,
                    "ident"=>"php",
                    "rfc"=>\Monolog\Handler\SyslogUdpHandler::RFC5424
                ],
                "errorlog"=>[
                    "level"=>"debug",
                    "messageType"=>\Monolog\Handler\ErrorLogHandler::OPERATING_SYSTEM,
                    "bubble"=>true,
                    "expandNewlines"=>false
                ]
            ]
        ];
    }
}

Other Monolog handlers #

Beside above most-used logging driver, there are many other Monolog's handlers that you may added. In this case, you can directly provide a custom handler name with Monolog's Handler object. For example, let say you want to create SocketHandler:

class AppLog extends \koolreport\dashboard\Log
{
    protected function settings()
    {
        return [
            "mychannel"=>[                                      
                "mySocketHandler"=> new SocketHandler('unix:///var/log/httpd_app_log.socket'),
                ...
            ]
        ];
    }
}

The full list of handlers you can find in here.

Writing log messages #

You will use your app Log class to write information to log

Example:

use \myapp\AppLog; // The namespace is defined by you, we just make it up.

AppLog::emergency($message);
AppLog::alert($message);
AppLog::critical($message);
AppLog::error($message);
AppLog::warning($message);
AppLog::notice($message);
AppLog::info($message);
AppLog::debug($message);

You can call each of these methods to log a message at corresponding level

use \koolreport\dashboard\google\BarChart;
use \myapp\AppLog;

class MyChart extends BarChart
{
    protected function onCreated()
    {
        AppLog::debug("MyChart is created");
    }
}

Contextual information #

An array of contextual data may also be passed to the log methods. This contextual data will be formatted and displayed with the log message:

AppLog::info('User failed to login.', ['username' => $username]);

Writing to specific channel #

Sometime, you want to write message to a specific channel, you can do so by using channel() method:

AppLog::channel("another-channel")->info("User login");

If you wish to write message to some channels of your choice, you can use channels() method:

AppLog::channels(["first-channel","second-channel"])->info("User login");

Get started with KoolReport

KoolReport will help you to construct good php data report by gathering your data from multiple sources, transforming them into valuable insights, and finally visualizing them in stunning charts and graphs.