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

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

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

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]]