This page explains how to activate and configure mod_compare.

In your apache config file:

<Location /myApiPath>

    # Make sure mod_compare's filters
    # are called to deserialize bodies when needed
    # after potential gziped body has been decompressed
    SetInputFilter DEFLATE;Compare 

    # activate mod_compare's execution in this Location
    Compare

</Location>

sudo a2enmod compare
sudo service apache2 restart

The following directives are only accessible inside an Apache Location or Directory.

Compare

• If present, mod_compare is active for the current Location
• If not present, the other directives are accepted but inactive
• You also need to add SetInputFilter Compare in order for mod_compare to actually perform deserialization

CompareHeader <IGNORE|STOP> <http_response_header> <regexp>

• use it to avoid too many false positives, but sparingly to still catch real differences
• applies on the two HTTP Server Response Headers (original and new) of the comparison.
• Two params are possible: IGNORE or STOP.
  • IGNORE: mod_compare will ignore the selected header when performing the diff, if the response header's value matches the regexp.
  • STOP: mod_compare will stop the comparison altogether and produce no diff as soon as the response header value matches the regexp in the original or new response.
• You may declare this as many times as you want per location, they are executed in the order declared
• The headers are selected case sensitively: even though per http standard, the header is insensitive, we compare sensitively to be able to catch even minor differences between APIs.
• If you wanted to STOP based on the request header, remember to just "not duplicate" that request using Prevent Filters in mod_dup

Example:

   CompareHeader IGNORE ETag "."
   CompareHeader IGNORE Date "."
   CompareHeader IGNORE Content-Length "."
   CompareHeader STOP Content-Type application/json

This will not produce diffs when only the ETag or the Date or the Content-Length of responses differ, and will not try to produce any diff if the response is of type application/json

CompareBody <IGNORE|STOP> <regexp>

• use it to avoid too many false positives, but sparingly to still catch real differences
• applies on both HTTP Response Bodies (of the original and new HTTP response).
• List of reg_ex to apply to the body for the comparison. Two params are possible: IGNORE or STOP.
  • IGNORE: mod_compare will ignore in the comparison the body line which matches the regexp.
  • STOP: mod_compare will stop comparing as soon as it finds that a body line matches the regexp.
• You may declare this as many times as you want per location, they are executed in the order declared

Example:

   CompareBody STOP "<Code>604</Code>"
   CompareBody IGNORE "Date"

CompareLogType <utf8json|simplejson|multiline|archive>

• Defaults to utf8json if missing
• utf8json: the content of the CompareLog will be in json-event format with any invalid utf8 characters suppressed. Recommended for production use with LogStash, Elastic Search and Kibana.
• simplejson: the content of the CompareLog will be in json-event format. No transformation is applied, so bad content in APIs may produce invalid utf8 characters in the json. Some CPU is saved though.
• multiline: human readable multi-line format - recommended for initial troubleshooting. Will not work well for simultaneous servers sending their logs to a central syslog, as the syslog multiline lock implemented in mod_compare only works for a local server.
• See more details on the different log formats in the mod_compare logs page.

CompareLog <FILE|SYSLOG> <filepath|syslog_facility>

• Sets the log type(FILE or SYSLOG) and the path(file or facility) where will be logged:
  • the differences - in comparison/default mode/DisableLibwsdiff false.
  • the two responses - in no comparison mode/DisableLibwsdiff true mode.
• Default is FILE /var/log/apache/compare_diff.log
• This configuration is independent from the location, meaning redefining it will override any previously set value, so make sure you define it only once in all apache confs.

CompareLog FILE "/var/log/apache2/my_diff.log"

# We activate CompareModule on the location /main/server
# Requests path that do not begin by this path will therefore not be interpreted by mod_compare
<Location /main/server>
  # Simple module activation
  Compare
  SetInputFilter Compare
  
  # Directives to avoid false positives
  CompareHeader IGNORE "Content-Length" "."
  CompareHeader "IGNORE" "Keep-Alive" "."
  CompareBody "STOP" "<Code>604</Code>"
  CompareBody "STOP" "<Code>920</Code>"

  Order deny,allow
  Allow from all
</Location>