Skip to content

Logging and Diagnostics

Jump to bottom
Robert Spencer edited this page Jun 13, 2024 · 7 revisions

Logging and Diagnostics

1. Background

We receive a lot of support requests either in our Gitter chat or via GitHub Issues. However, we can only offer generic assistance unless we are provided with some details specific to your setup. There are literally hundreds of different ways to host ChurchCRM from dedicated hardware, virtual machines, shared hosting or containerized setups. How we support you and what we might suggest is heavily dependent on how you have deployed ChurchCRM.

This wiki page endeavors to explain the information we need, and how to get it, to support you.

2. Your setup

Please let us know the following about your ChurchCRM setup:

  • Are you running on bare metal? (dedicated physical hardware)
  • Shared hosting: which provider, and is it using cPanel or something else?
  • Virtual machine hosting.
  • Containerized hosting: Docker etc, something else?

In all setups as much of the following information as possible:

  • Operating system:
    • Windows - XAMPP/MAMP/etc
    • Linux - distribution/version/etc
    • MacOS - version/MAMP/Homebrew
  • Webserver:
    • Apache - we currently only support Apache web server, but knowing how you have deployed as a dedicated vhost or under a subdirectory etc.
    • PHP - version, configuration and installed extensions. Adding PHP info page can be useful.
  • MySQL/MariaDB:
    • Version and configuration. Is it co-hosted on the same machine as the webserver or is it on a different machine?
  • File System Permissions:

3. Logs

Logs are your friend, and consequently, OUR friend too! We really need to see what is happening "under the hood".

3.1 ChurchCRM Logs

Thankfully, ChurchCRM has a number of logs we can use to help which are in the logs directory where you deployed it. For example, if you deployed ChurchCRM at /var/www/vhosts/churchcrm then the logs directory will be /var/www/vhosts/churchcrm/logs. In that directory, ChurchCRM will write three different logs grouped by days:

  1. yyyy-mm-dd-auth.log - authentication log: tracking user access and failed access attempts etc.
  2. yyyy-mm-dd-app.log - application log: with internal events and basic debugging information (this is the log we usually need to see).
  3. yyyy-mm-dd-orm.log - ORM logs: not usually stuff we would ask for, but if we do, we will ask for the "ORM logs".

3.2 Apache Logs

Apache logs its own messages and developers will sometimes ask for the Apache error log. Where this log is entirely dependent on the way Apache is configured. Generally speaking, if you are self-hosting or running on a virtual machine, it will be somewhere under /var/log/....

XAMPP/MAMP will have their own logging setup too, so please review the setup for your hosting to find this log.

Shared hosting providers sometimes hide Apache error logs and you may need to raise a support case with your provider to get a copy of it Sometimes the Apache error log might be buried in cPanel or your hosting provider's management portal, so have a look around first.

4. Sharing Logs With Developers

Logs can contain sensitive information or information you want to hide (IP addresses, usernames, hostnames, domains, etc). If you choose to redact your logs please make it obvious what information you have replaced and please be consistent. For instance here is a raw log, and a redacted log (although they have been formatted for clarity):

Raw Log

[2021-07-09T21:29:41.473127+10:00] authLogger.INFO: User partially authenticated, pending 2FA:
    jbloggs [] {
        "url":"/session/begin",
        "remote_ip":"111.222.333.444",
        "correlation_id":"60e8332573831",
        "context":{
            "ContextClass":"ChurchCRM\\Authentication\\AuthenticationManager",
            "ContextMethod":"Authenticate"
         }
    }

Redacted Log

[2021-07-09T21:29:41.473127+10:00] authLogger.INFO: User partially authenticated, pending 2FA:
    username [] {
        "url":"/session/begin",
        "remote_ip":"Remote.IP.Redacted",
        "correlation_id":"60e8332573831",
        "context":{
            "ContextClass":"ChurchCRM\\Authentication\\AuthenticationManager",
            "ContextMethod":"Authenticate"
         }
    }

Notice the user name consistently replaced jbloggs with username and the remote IP address consistently replaced 111.222.333.444 with Remote.IP.Redacted.

4.1 Some do's and don'ts

DO

  • If you redact your logs, please be consistent with what you replace. Replacing different details with same "redacted" comment renders your logs useless.

  • Wrap logs in triple back-ticks (on their own line), in both GitHub Issues and Gitter chats, e.g.:

    ```
Those triple back-ticks need to be on a line by themselves.
This is my log
```

  • Be aware with shared hosting or remote hosting, your webserver may be in a different time zone - please supply the logs covering the time you encountered a problem as recorded by your web server. This may be different to "local time".

  • Feel free to format your logs for clarity (see examples above).

DON'T

  • Assume we know what you are seeing purely because of the log. Describe the behavior you experience including what you did to create it.
  • Screenshots are great, but don't screenshot your logs - they are hard to read and we can't search them for specific strings etc.

5. Log All The Things

The default logging is usually sufficient to identify most problems we are asked about. However, you may be be asked to do one or more of the following...

5.1 Coaxing SLIM to display the real error

Described here, remove the keys from the slim $app:

unset($app->getContainer()['errorHandler']);
unset($app->getContainer()['phpErrorHandler']);

5.2 Configure the Bootstrapper debug mode

In Include/Config.php, set $debugBootstrapper = true;. If the variable is not already present in Config.php, you should add it.

This will cause the bootstrapper to write verbose logs as it sets up the environment.

The resulting debug log entries will be written to the log file for the current date (ending in -app.log see section 3.1).

To revert this debug behavior, set $debugBootstrapper = false;

Website - Demo System - Twitter @church_crm

Clone this wiki locally