Skip to content

Logging and Diagnostics

Jump to bottom
James G edited this page Jul 11, 2021 · 7 revisions

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 containerised setups. How we support you and what we might suggest is heavily dependent on how you have deployed ChurchCRM.

This wiki page endeavours 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.
  • Containerised 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 happenning "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 log ins and failed log in attempts etc.
  2. yyyy-mm-dd-app.log - application log with internal events and basic debugging information.
  3. yyyy-mm-dd-orm.log - ORM logs. Usually not 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 most often, the log developers will ask for is 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"
         }
    }
[2021-07-09T21:29:45.066806+10:00] authLogger.INFO: User succefully logged in with 2FA:
    jbloggs [] {
        "url":"/session/two-factor",
        "remote_ip":"111.222.333.444",
        "correlation_id":"60e8332910501",
        "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"
         }
    }
[2021-07-09T21:29:45.066806+10:00] authLogger.INFO: User succefully logged in with 2FA:
    username [] {
        "url":"/session/two-factor",
        "remote_ip":"Remote.IP.Redacted",
        "correlation_id":"60e8332910501",
        "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, in both GitHub Issues and Gitter chats, eg: 
    ```
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 behaviour 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 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).

Website - Demo System - Twitter @church_crm

Clone this wiki locally