Logging and Diagnostics

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 - Docker Desktop
  • 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:
  • Please verify your file permissions. Incorrect permissions cause a LOT of support requests and are easy to fix.

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.1.1 Viewing Logs Via Admin UI

System administrators can view, filter, and manage logs directly from the ChurchCRM admin interface:

1. Log in to ChurchCRM as an administrator
2. Go to Admin → System Logs
3. In the Log Settings section, you can adjust the log level (DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY)
4. In the System Logs section, you can:
   • View any log file by clicking the eye icon - this opens a modal where you can filter by log level and view specific entries
   • Delete individual log files by clicking the trash icon
   • Delete All Logs using the red button (if logs are present)
   • Adjust the log level to control the verbosity of future log entries

Note: Lower numbers log more details (DEBUG = 100), while higher numbers only log severe issues (EMERGENCY = 600). Changes to the log level apply to new log entries immediately.

3.1.2 Accessing Logs Directly From the File System

You can also access logs directly from the file system if you have SSH access or file manager access to your server. If you deployed ChurchCRM at /var/www/vhosts/churchcrm, the logs are stored at /var/www/vhosts/churchcrm/logs. You can download them using SFTP, SCP, or a file manager provided by your hosting provider.

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.

Self-Hosted / VPS (SSH): Generally speaking, if you are self-hosting or running on a virtual machine, look under /var/log/:

# Apache error log (common locations)
tail -100 /var/log/apache2/error_log     # Debian/Ubuntu
tail -100 /var/log/httpd/error_log       # CentOS/RHEL
# Search for errors
grep ERROR /var/log/apache2/error_log

Shared Hosting (cPanel): Shared hosting providers sometimes hide Apache error logs:

1. Log in to cPanel
2. Look for Error Log (usually in Main section, or search for "Error Log")
3. Download or view the current error log
4. If you can't find it, contact your hosting provider's support

Docker: See Docker Development Environment for details on viewing container logs.

Tip: When reporting an issue, if your ChurchCRM logs don't show the problem, an Apache error log is often very helpful for diagnosis.

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;