Logging and debugging

All logging in django-sio goes through the standard Django logging configuration and uses loggers under the "sio" namespace.

Logger names

sio.sio

Root package imports and version info.

sio.engineio.*

Engine.IO transports, packets, and sessions.

sio.socketio.*

Socket.IO protocol, server, namespaces, and sockets.

sio.consumer

SocketIOConsumer wiring and event dispatch.

Enable debug logging

Configure a "sio" logger in Django LOGGING settings:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "verbose_sio": {
            "format": (
                "%(asctime)s [%(levelname)s] "
                "%(name)s %(pathname)s:%(lineno)d %(funcName)s(): "
                "%(message)s"
            ),
        },
    },
    "handlers": {
        "console_sio": {
            "class": "logging.StreamHandler",
            "formatter": "verbose_sio",
        },
    },
    "loggers": {
        "sio": {
            "handlers": ["console_sio"],
            "level": "DEBUG",   # DEBUG for full protocol tracing
            "propagate": False,
        },
    },
}

What you will see

At import time you will see messages such as:

• "sio root package imported" with version and socketio_version in extra;

• "engineio package imported" with ENGINE_IO_VERSION;

• "socketio package imported" with SOCKET_IO_VERSION.

At DEBUG level you get detailed traces for:

• Engine.IO session lifecycle, including creation, destruction, and timeout;

• HTTP long-polling requests, including handshake, GET, POST, and payload sizes;

• WebSocket connect/upgrade and heartbeat pings/pongs;

• packet parsing and encoding for both Engine.IO and Socket.IO;

• room joins, room leaves, and room-based broadcasts;

• consumer wiring, connect hooks, disconnect hooks, event handlers, per-event dispatch, and whether handlers used acks.

Production logging

For production, keep the same handler and raise the level to INFO to only see high-level lifecycle events:

"loggers": {
    "sio": {
        "handlers": ["console_sio"],
        "level": "INFO",
        "propagate": False,
    },
}

You can send these logs to any Django-supported handler, including structured JSON logging, files, or external log aggregators.