View Source ExDbug (ExDbug v1.0.0)

Advanced debug utility for debugging and analysis, inspired by the Node.js 'debug' package.

Usage

Add use ExDbug, context: :my_namespace to a module, and use dbug/1 or error/1 to log debug or error messages.

Debug output is controlled by:

  • The :enabled config key for :ex_dbug (compile-time)
  • The DEBUG environment variable (runtime), which determines which namespaces are displayed

Enabling/Disabling at Compile Time

In your config.exs:

config :ex_dbug, enabled: true

If enabled: false, calls to dbug and error are compiled out (no runtime overhead).

Using DEBUG Environment Variable

Set DEBUG to enable certain namespaces:

  • DEBUG="*" enables all namespaces
  • DEBUG="myapp:*" enables all namespaces starting with myapp:
  • DEBUG="*,-myapp:db" enables all but myapp:db

You can separate multiple patterns with commas. A leading - excludes a pattern.

Example:

DEBUG="myapp:*" mix run

Example

defmodule MyModule do
  use ExDbug, context: :my_feature

  def run do
    dbug("Starting run")
    :ok
  end
end

If DEBUG="my_feature", calling MyModule.run() will log the debug message.

Features

  • Namespace-based enabling/disabling of debug output
  • Compile-time toggle to remove debug calls entirely
  • Stack trace or timing info can be integrated if desired
  • Works similar to the Node.js 'debug' library

Summary

Functions

Format output by prefixing with [Namespace].

Check if debug is enabled based on application config.

Logging logic: We determine if we should log by checking

Check if a namespace matches any of the included patterns and is not excluded. If no patterns are set, default to enable if the library is enabled.

Merge options from app config, defaults, and module opts.

Check if a given namespace (context) is enabled by the DEBUG environment variable. If DEBUG is unset or empty, default to enabling everything if :enabled is true, otherwise no logging.

Parse the DEBUG environment variable for enable/disable patterns.

Perform a simple wildcard match.

Types

debug_opts()

@type debug_opts() :: [
  enabled: boolean(),
  context: atom() | String.t(),
  max_depth: non_neg_integer(),
  include_timing: boolean(),
  include_stack: boolean()
]

Functions

dbug(message, metadata \\ [], opts \\ [])

(macro)

error(message, metadata \\ [], opts \\ [])

(macro)

format_output(message, context)

Format output by prefixing with [Namespace].

get_debug_enabled(opts)

Check if debug is enabled based on application config.

log(level, message, opts, context)

Logging logic: We determine if we should log by checking:

  1. If the level is allowed
  2. If the context matches DEBUG patterns

matches_namespace?(namespace, arg)

Check if a namespace matches any of the included patterns and is not excluded. If no patterns are set, default to enable if the library is enabled.

merge_options(opts)

Merge options from app config, defaults, and module opts.

namespace_enabled?(context)

Check if a given namespace (context) is enabled by the DEBUG environment variable. If DEBUG is unset or empty, default to enabling everything if :enabled is true, otherwise no logging.

parse_debug_env()

Parse the DEBUG environment variable for enable/disable patterns.

Returns a tuple {includes, excludes}, where includes and excludes are lists of patterns. A pattern can have wildcards (*).

track(value, name)

(macro)

wildcard_match?(string, pattern)

Perform a simple wildcard match.

  • matches any sequence of characters.