WebsockexNova.Behaviors.LoggingHandler behaviour (WebsockexNova v0.1.1)
View SourceDefines the behavior for standardized, configurable logging in WebsockexNova.
The LoggingHandler behavior enables pluggable, context-aware logging for connection, message, and error events. This allows applications to customize log levels, formats, and destinations, supporting both structured and unstructured logging.
Usage
All Gun pipeline modules, helpers, and test/mock handlers now use the logging handler for connection, message, and error events. If a logging handler is not present in the connection state, logging falls back to Elixir's Logger.
Configuring a Custom Logging Handler
To use a custom logging handler, add it to your connection state:
state = %{logging_handler: MyApp.LoggingHandler, ...}
Your handler module must implement the WebsockexNova.Behaviors.LoggingHandler
behavior.
Implementing the LoggingHandler Behavior
defmodule MyApp.LoggingHandler do
@behaviour WebsockexNova.Behaviors.LoggingHandler
@impl true
def log_connection_event(event, context, state) do
# Custom connection event logging
:ok
end
@impl true
def log_message_event(event, context, state) do
# Custom message event logging
:ok
end
@impl true
def log_error_event(event, context, state) do
# Custom error event logging
:ok
end
end
Example: Plugging in a Custom Handler
state = %{logging_handler: MyApp.LoggingHandler, ...}
# Pass this state to your connection pipeline
Example: Capturing Log Events in Tests
defmodule MyTest.LoggingHandler do
@behaviour WebsockexNova.Behaviors.LoggingHandler
def log_connection_event(event, context, state), do: send(self(), {:log, :connection, event, context}); :ok
def log_message_event(event, context, state), do: send(self(), {:log, :message, event, context}); :ok
def log_error_event(event, context, state), do: send(self(), {:log, :error, event, context}); :ok
end
# In your test setup:
state = %{logging_handler: MyTest.LoggingHandler, ...}
Callbacks
log_connection_event/3
- Log a connection lifecycle eventlog_message_event/3
- Log a message send/receive eventlog_error_event/3
- Log an error event with context
Configuration
Implementations should support configuration for log level (e.g., :debug, :info, :warn, :error) and log format (e.g., :plain, :json). These can be provided via handler state or options.
Example
defmodule MyApp.LoggingHandler do
@behaviour WebsockexNova.Behaviors.LoggingHandler
@impl true
def log_connection_event(event, context, state) do
# Custom logging logic
:ok
end
@impl true
def log_message_event(event, context, state) do
# Custom logging logic
:ok
end
@impl true
def log_error_event(event, context, state) do
# Custom logging logic
:ok
end
end
Summary
Types
Context information about the event (e.g., connection details, message payload, error info).
Event type for connection, message, or error events.
Log format (:plain, :json, or custom atom).
Log level (:debug, :info, :warn, :error).
Handler state
Callbacks
Log a connection lifecycle event (e.g., connect, disconnect, reconnect). Returns
Log an error event with context. Returns
Log a message event (send/receive). Returns
Types
@type context() :: map()
Context information about the event (e.g., connection details, message payload, error info).
Event type for connection, message, or error events.
@type log_format() :: :plain | :json | atom()
Log format (:plain, :json, or custom atom).
@type log_level() :: :debug | :info | :warn | :error
Log level (:debug, :info, :warn, :error).
@type state() :: map()
Handler state
Callbacks
Log a connection lifecycle event (e.g., connect, disconnect, reconnect). Returns:
:ok
Log an error event with context. Returns:
:ok
Log a message event (send/receive). Returns:
:ok