Compile-time debugging facilities.

RemoteIp uses the debug/3 macro to instrument its implementation with debug events at compile time. If an event is enabled, the macro will expand into a Logger.debug/2 call with a specific message. If an event is disabled, the logging will be purged, thus generating no extra code and having no impact on run time.

Basic usage

Events are fired on every call to RemoteIp.call/2 or RemoteIp.from/2. To enable or disable all debug events at once, you can set a boolean in your Config file:

config :remote_ip, debug: true

By default, the debugger is turned off (i.e., debug: false).

Because RemoteIp.Debugger works at compile time, you must make sure to recompile the :remote_ip dependency whenever you change the configuration:

$ mix deps.clean --build remote_ip

Advanced usage

You may also pass a list of atoms into the :debug configuration naming which events to log.

These are all the possible events:

• :options - the keyword options after any runtime configuration has been evaluated (see RemoteIp.Options)

• :headers - all incoming headers, either from the Plug.Conn's req_headers or the list passed directly into RemoteIp.from/2; useful for seeing if you're even getting the forwarding headers you expect in the first place

• :forwarding - the subset of headers (as configured by RemoteIp.Options) that contain forwarding information

• :ips - the entire sequence of IP addresses parsed from the forwarding headers, in order

• :type - for each IP (until we find the client), classifies the address either as a known client, a known proxy, a reserved address, or none of the above (and thus presumably a client)

• :ip - the final result of the remote IP processing; when rewriting the Plug.Conn's remote_ip, the message will tell you the original IP that is being replaced

Therefore, debug: true is equivalent to passing in all of the above:

config :remote_ip, debug: [:options, :headers, :forwarding, :ips, :type, :ip]

But you could disable certain events by removing them from the list. For example, to log only the incoming headers and resulting IP:

config :remote_ip, debug: [:headers, :ip]

Interactions with Logger

Since they both work at compile time, your configuration of :logger will also affect the operation of RemoteIp.Debugger. For example, it's possible to enable debugging but still purge all the resulting logs:

# All events *would* be logged...
config :remote_ip, debug: true

# ...But :debug logs will actually get purged at compile time
config :logger, compile_time_purge_matching: [[level_lower_than: :info]]