logger

Documentation

Overview

Package logger holds the log level control shared by every package of the library and the fallback logger for packages that cannot reach engineio.Options.Logger.

Variables

Log is the fallback logger: the parser, the transports, engineio/packet and the client dialer log through it, and it writes to whatever slog.Default() is when a record is logged. Level is the library log level described below. To route library records, pass a logger as engineio.Options.Logger or call slog.SetDefault; assigning Log bypasses Wrap.

Runtime level

The environment variable SOCKETIO_LOG_LEVEL is read once at program start. Accepted values, case-insensitive: error, warn, info, debug, trace. When it is set, Level decides which library records are enabled, regardless of the level configured on the application's handler, so an operator can turn on debug output of a running deployment without a rebuild. When it is unset, the application's handler decides. An invalid value logs one WARN, "logger: invalid level ignored" with the value under value, and behaves as unset. Applications can change Level at runtime with Level.Set, with or without the variable; Level.Set(LevelUnset) hands the decision back to the application's handler.

engineio.Options.Logger chooses where records go; it never chooses the level. Every logger the library uses is passed through Wrap.

Levels

The library logs WARN and DEBUG records only; it logs no ERROR or INFO record. WARN marks a failure no caller receives, such as "socketio: unhandled error" or a rejected request (DEBUG for an unknown sid). Expected closure (EOF, a closed connection, a peer close, a ping timeout and any failure after a close started), errors also returned to a caller or delivered to an OnError handler, and the boundary records (session open and close, namespace connect, disconnect) are DEBUG. LevelTrace is reserved for per-packet and ping/pong lines, guarded by Enabled so that disabled trace logging does not allocate; no v1 call site logs at it yet. Records an application logs through the deprecated Error and Info are its own.

Messages and keys

Every library record has a constant message matching

^(engineio|socketio|logger): [a-z][a-z0-9 ]*$

prefixed engineio for the engineio packages, socketio for the root package, the parser and the Redis broadcast, and logger for this package. Attribute keys come only from this list:

• sid: the engine.io session id
• nsp: the namespace; the root namespace is "/"
• err: the error
• transport: the transport name, following upgrades
• remote_addr: the peer address
• reason: why a request was rejected, a session closed or a namespace disconnected
• duration: how long a session was open
• event: the event name
• ack_id: the acknowledgement id
• type: the packet type
• value: an invalid setting, such as SOCKETIO_LOG_LEVEL

No record carries packet payloads.

Index

• Constants
• Variables
• func Error(msg string, err error)
• func Info(msg string, args ...interface{})
• func ReplaceAttr(_ []string, a slog.Attr) slog.Attr
• func Wrap(l *slog.Logger) *slog.Logger

Constants

const EnvLevel = "SOCKETIO_LOG_LEVEL"

EnvLevel is the name of the environment variable that sets Level.

const LevelTrace = slog.LevelDebug - 4

LevelTrace is below slog.LevelDebug. Handlers render it as "DEBUG-4" unless they use ReplaceAttr.

const LevelUnset = slog.Level(math.MaxInt32)

LevelUnset is the value of Level while no override is active: the application's handler decides what is enabled.

Variables

var Level = new(slog.LevelVar)

Level is the library log level. It starts at the value of SOCKETIO_LOG_LEVEL, or LevelUnset when the variable is unset or invalid. Setting it to any other level at runtime turns the override on; setting it to LevelUnset turns it off.

var Log = slog.New(&levelHandler{next: &defaultHandler{}})

Log is the fallback logger for packages without access to engineio.Options: the parser, the transports, engineio/packet and the client dialer. It writes to whatever slog.Default() is when a record is logged, so an application's later slog.SetDefault applies to it.

Functions

func Error

func Error(msg string, err error)

Error logs msg with err at ERROR through Log. A nil err is logged as such.

Deprecated: the library no longer calls Error. Use slog's methods on logger.Log or on the logger passed as engineio.Options.Logger instead.

func Info

func Info(msg string, args ...interface{})

Info logs msg with args at INFO through Log.

Deprecated: the library no longer calls Info. Use slog's methods on logger.Log or on the logger passed as engineio.Options.Logger instead.

func ReplaceAttr

func ReplaceAttr(_ []string, a slog.Attr) slog.Attr

ReplaceAttr renders LevelTrace as "TRACE". Pass it as slog.HandlerOptions.ReplaceAttr to the handler given to the library.

func Wrap

func Wrap(l *slog.Logger) *slog.Logger

Wrap returns a logger over l's handler whose Enabled follows Level while Level is not LevelUnset, whether it was set by SOCKETIO_LOG_LEVEL or by Level.Set, and l's handler otherwise. A nil l means Log, which follows slog.Default() at log time. Wrapping an already wrapped logger returns it unchanged.