README

symfony-logbook is a bundle that allows you to collect logs generated by your Symfony application and then submit them into LogBook. This bundle provides seamless integration with monolog-bundle and allows you to create and store log messages in a variety of different places while triggering various actions.

To install symfony-logbook, use the composer package manager by executing the following command in your terminal:

composer require solvrtech/symfony-logbook

After the installation, register the symfony-logbook bundle in your application's config/bundles.php file by adding the following code:

return [
    //  ...
    Solvrtech\Symfony\Logbook\LogbookBundle::class => ['all' => true],
];

In case you did not execute the recipe during the composer require command, you will need to manually create a new logbook configuration file at /config/packages/logbook.yaml with the following contents:

logbook:
    api:
        # The base url of the logbook app.
        url: "https://logbook.com"
        # The API key of logbook client app.
        key: "4eaa39a6ff57c4d5b2cd0a..."

    # Instance ID is a unique identifier per instance of your apps.
    instance_id: "default"

Make sure to replace the url value with the actual URL of your LogBook installation, and the key value with the API key that was generated for your app.

The instance_id value sets a unique identifier for your app’s deployment. This is useful when you have multiple instances or deployments (e.g. in horizontally-scaled environments). For example, you can set "app-1" for the first instance and "app-2" for the second one. The instance ID information will be shown as part of log details in LogBook.

Register the health status check route, it will be accessed by the logbook to check the health status of the application. To register it in your Symfony application, add the following configuration to your config/routes/logbook.yaml file:

logbook_health:
    resource: "@LogbookBundle/Resources/config/routes.yaml"
    prefix: /logbook-health

Finally, configure the security for the health status check route in your Symfony application by adding the following configuration into your config/packages/security.yaml file:

security:
    providers:
        # ...
        logbook_provider:
            id: Solvrtech\Logbook\Security\LogbookUserProvider

    firewalls:
        health_check:
            pattern: ^/logbook-health
            stateless: true
            provider: logbook_provider
            custom_authenticator: logbook.authenticator

Submitting logs into LogBook

The process of submitting logs to LogBook involves defining a logbook handler on the monolog configuration in your Symfony application. This can be done by adding the following configuration to your config/packages/monolog.yaml file ( see Writing Logs to different Locations):

monolog:
    handlers:
        # ...
        logbook:
            # passed *all* logs
            type: stream
            # passed only log with debug level or higher
            level: debug

By using the level config above, you can specify the minimum log level that will be submitted to your LogBook installation. The ordered log levels are (from low to high):

DEBUG
INFO
NOTICE
WARNING
ERROR
CRITICAL
ALERT
EMERGENCY

For example, when you set "level: warning", then only higher priority log levels such as WARNING, ERROR, CRITICAL, ALERT, and EMERGENCY are going to be submitted to your LogBook installation.

To submit log messages in your code, you can inject the default logger instance into your controller or service and then use it. For example:

use Psr\Log\LoggerInterface;

public function index(LoggerInterface $logger)
{
    $logger->info('I just got the logger');

    // include extra "context" info in your logs
    $logger->critical(
        'I left the oven on!', 
        [
            'cause' => 'in_hurry',
        ]
    );

    // ...
}

For more information on how to use the LoggerInterface, you can refer to its documentation.

Submitting logs asynchronously

By default, logs will be submitted synchronously as soon as they are being recorded. and this might lead to a performance issue for your application. Fortunately, you can submit the logs asynchronously by queuing the logs (inside database or Redis) and then create a background task to submit the queue of logs in batch.

So first, you need to configure the logs transport config in your app’s config/packages/logbook.yaml file. Transport is registered using a DSN.

1.a Using Doctrine Transport

To use the Doctrine transport for asynchronous log handling, add the following configuration into your config/packages/logbook.yaml file:

logbook:
    transport: 'doctrine://default?batch=15'

In the example above:

"default" means that it will use the default Doctrine connection being used by your app.
"batch=" specifies the maximum number of logs to be sent from your application into LogBook in a batch.

1.b Using Redis Transport

To use the Redis transport for asynchronous log handling, add the following configuration to your config/packages/logbook.yaml file:

logbook:
    transport: 'redis://localhost:6379?batch=15'

In the example above:

"localhost:6379" specifies the Redis connection URL that will be used.
"batch=" specifies the maximum number of logs to be sent from your application into LogBook in a batch.

Choose the transport option that best suits your application's needs and configure it accordingly in the logbook.yaml file. Remember to adjust the batch size according to your needs.

After configuring the transport mechanism, you will need to submit the queue of logs in a background task by running php bin/console logbook:log:consume command periodically. You can do this by using Systemd or Supervisor.

2.a Using Systemd

Create a new service file for log consume service, for example /etc/systemd/system/log-consume.service, then add the following configurations into the file:

[Unit]
Description=Log Consume
After=network.target

[Service]
ExecStart=/usr/bin/php /path/to/your/symfony/bin/console logbook:log:consume
WorkingDirectory=/path/to/your/symfony
User=www-data
Restart=always

[Install]
WantedBy=multi-user.target

Start the service and enable it during system reboot:

sudo systemctl start log-consume && sudo systemctl enable log-consume

2.b Using Supervisor

Create a new configuration file for the log consume service, for example /etc/supervisor/conf.d/log-consume.conf. Add the following configurations into the file:

[program:log-consume]
command=php /path/to/your/symfony/bin/console logbook:log:consume
directory=/path/to/your/symfony
autostart=true
autorestart=true
stderr_logfile=/var/log/log-consume.err.log
stdout_logfile=/var/log/log-consume.out.log
user=www-data

To start the service, run the following commands:

sudo supervisorctl reread && sudo supervisorctl update && sudo supervisorctl start log-consume

Optional: set your application version

Application version is an optional parameter that can also be included inside log submission data into your LogBook installation. To do so, make sure to set the version in your Symfony app’s /config/service.yaml file:

parameters:
    # ...
    version: "1.0.0"

It's worth noting that while it is recommended to set the application version, it is an optional step. When the "version" config is not found, log submission should work normally, but the version information will not be found in the submitted logs.

solvrtech / symfony-logbook

Maintainers

Details