Logging

Access vs Error

Each endpoint has two independent logging interfaces. One for access logs and one for error logs. By default, access logs are written to stdout and error logs are written to stderr. Each logging interface may be optionally redirected to an arbitrary C++ stream (including file streams).

Logging Channels

Each logging interface is divided into 32 named channels. Log messages are written to a specific interface on a specific channel. Which log messages are actually printed is determined by which channels are enabled or not. Channels can be enabled or disabled either at compile time or at runtime.

Enabling and Disabling Channels

Channels disabled at compile time are removed from the code entirely (assuming correct compiler optimization settings) and are not available for runtime enabling or disabling. To disable channels at compile time, use the alog_level and elog_level values within your config. Channels not disabled at compile time can be enabled or disabled at runtime using the set_access_channels(), clear_access_channels(), set_error_channels(), and clear_error_channels() methods of the endpoint class.

The set and clear functions act only on the channels specified. set_access_channels(log::alevel::connect) will enable logging of new connections. Following this with set_access_channels(log::alevel::disconnect) will enable logging of disconnections in addition to connections. Use clear* functions to disable a specific channel. Channels may be combined using bitwise operations to create aggregate packages of channels that may be set or cleared at once. Default packages include log::alevel::all, log::elevel::all, log::alevel::none, log::elevel::none. These represent all possible access/error channels and no access/error channels respectively. For convenience, setting none is aliased to clearing all.

Examples

Disable all

clear_access_channels(log::alevel::all)

Disable all (alternative method)

set_access_channels(log::alevel::none)

Multiple channels at once

log::alevel::message_payload | log::alevel::message_payload

All except one

log::alevel::all ^ log::alevel::message_payload

Default settings

By default, only debug/development logging is disabled.

Logging Policies

Advanced logging behavior is controlled by the logging policy defined in your config. All loggers implement the logging interface, but some have additional features or behavior. For advanced uses, custom logging policies can be created to meet specific needs. WebSocket++ ships with two logging policies. The websocketpp::log::basic policy provides a basic thread safe logger that logs to the specified C++ iostream with timestamps and channel names. This is the default policy. The websocketpp::log::stub policy implements the logging interface but ignores all input and provides no output. It can be used to stub out the logging system in tests or to completely disable and remove all logging related code.

Logging interfaces may be directly accessed via their associated endpoint using get_alog() and get_elog(). This allows access to methods specific to the chosen logging policy. The following are some common use cases for this:

Redirecting output / Logging to files

The basic (default) logging policy allows redirecting output to an arbitrary stream using the set_ostream() method.

Error Logging Levels

Each of these channels is in the namespace websocketpp::log::elevel

Level Description
none Special aggregate value representing "no levels"
devel Low level debugging information (warning: very chatty). Requires debug or custom config.
library Information about unusual system states or other minor internal library problems, less chatty than devel.
info Information about minor configuration problems or additional information about other warnings.
warn Information about important problems not severe enough to terminate connections.
rerror Recoverable error. Recovery may mean cleanly closing the connection with an appropriate error code to the remote endpoint.
fatal Unrecoverable error. This error will trigger immediate unclean termination of the connection or endpoint.
all Special aggregate value representing "all levels"

Access Logging Levels

Each of these channels is in the namespace websocketpp::log::alevel

Level Description
none Special aggregate value representing "no levels"
connect One line for each new connection that includes a host of information including: the remote address, websocket version, requested resource, http code, remote user agent
disconnect One line for each connection that is closed. Includes closing codes and reasons
control One line per control message
frame_header One line per frame, includes the full frame header
frame_payload One line per frame, includes the full message payload (warning: very chatty)
message_header Reserved
message_payload Reserved
endpoint Reserved
debug_handshake Extra information about opening handshakes
debug_close Extra information about closing handshakes
devel Development messages (warning: very chatty). Requires debug or custom config.
app Special channel for application specific logs. Not used by the library.
all Special aggregate value representing "all levels"

Add new comment

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
By submitting this form, you accept the Mollom privacy policy.