1
0
Fork 0
mirror of https://github.com/warmcat/libwebsockets.git synced 2025-03-16 00:00:07 +01:00
libwebsockets/READMEs/README.logging.md
Andy Green 0ceba15d9c lws_lifecycle
This adds some new objects and helpers for keeping and logging
info on grouped allocations, a group is, eg, SS handles or client
wsis.

Allocated objects get a context-unique "tag" string intended to replace
%p / wsi pointers etc.  Pointers quickly become confusing when
allocations are freed and reused, the tag string won't repeat
until you produce 2^64 objects in a context.

In addition the tag string documents the object group, with prefixes
like "wsi-" or "vh-" and contain object-specific additional
information like the vhost name, address / port  or the role of the wsi.
At creation time the lws code can use a format string and args
to add whatever group-specific info makes sense, eg, a wsi bound
to a secure stream can also append the guid of the secure stream,
it's copied into the new object tag and so is still available
cleanly after the stream is destroyed if the wsi outlives it.
2021-01-04 05:26:50 +00:00

4.3 KiB

lws logging

lwsl_ logging apis

LWS provides logging arrangements that are not indirected through the lws context, because logging may be needed before and after the context existence. For that reason it's processwide.

By default the logs are emitted on stdout, but this can be overridden using lws_set_log_level() and either syslog (provided by lwsl_emit_syslog()) or custom log emission is possible if you point it to your own.

Currently the following log levels are defined

name function release meaning
LLL_ERR lwsl_err() y Serious operation errors anyone needs to know
LLL_WARN lwsl_warn() y Operation errors you may need to know
LLL_USER lws_user() y Information user code wants you to know
LLL_NOTICE lwsl_notice() y Information about what lws is doing useful for logging
LLL_INFO lwsl_info() n Detailed information about what lws is doing
LLL_DEBUG lwsl_debug() n Very detailed information about what lws is doing
LLL_PARSER lwsl_parser() n Very detailed information about parsing
LLL_HEADER lwsl_header() n Very detailed information about header processing
LLL_EXT lwsl_ext() n Very detailed information about ws extensions
LLL_CLIENT lwsl_client() n Very detailed information about client connections
LLL_LATENCY lwsl_latency() n detailed latency stats
LLL_THREAD lwsl_thread() n detailed threadpool information

The first four log levels are built into lws even on Release builds, the others are only built in Debug builds.

You can select between Debug and Release builds using cmake -DCMAKE_BUILD_TYPE= DEBUG or Release

lws_set_log_level() is used to OR together the logging bitfields you want to see emitted, only log levels that were built in can be enabled since the code for them is just not there otherwise.

Finegrained control of log level build

You can deviate from the default log inclusion for release / debug by overriding it at cmake, using LWS_LOGGING_BITFIELD_SET and LWS_LOGGING_BITFIELD_CLEAR.

For example you can set -DLWS_LOGGING_BITFIELD_SET="LLL_INFO|LLL_DEBUG", which will cause those log level traces to be built in even in Release mode. Clear works similarly to defeat build of specific log levels.

Object tags in lws

Commonly logging wants to refer to an object in a repeatable way, the usual way to do this is with %p to print the object pointer. But this has a couple of drawbacks, first the same memory may be freed and reallocated for a different instance of the same or another object, causing confusion, and second when multiple processes are allocating objects and logging, the same address may be allocated in different process also causing confusion.

Lws has introduced unique tag strings to refer to object identity in logging instead, these contain various information such as a 64-bit ordinal for the group the object belongs to that won't repeat even if reallocated to the same address (until 2^64 allocations, anyway).

Tags are fixed at object creation time for the whole object lifetime, although in some cases the tag may be appended to... accepted server wsis for example don't have much information available to form the tag until they start to indicate what they want to do.

At their simplest the tags look like this (in a log indicating creation)

[2020/12/27 08:49:19:2956] N:  ++ (4) [wsi|5|h2]

It means a wsi has been created with the tag [wsi|5|h2], and after that, there are 4 active objects in the wsi group.

The corresponding object destruction log with the tag is

[2020/12/27 08:49:24:4226] N:  -- (3)   5.126s [wsi|5|h2]

it indicates the object's tag, that it lived for 5.126s and after its destruction, there are 3 objects in its group left.

Compound tags

If the object has bindings, the tag can reflect that, eg

[2020/12/27 08:49:19:4787] N:  ++ (2) [wsiSScli|6|d_h1]
[2020/12/27 08:49:19:4793] N:  ++ (2) [wsicli|6|GET/h1/httpbin.org/([wsiSScli|6|d_h1])]

the first log is describing a proxied SS client connection at the proxy, and the second is a wsi bound to the SS object from the first log to do the outgoing client action.

Tags in user code

When user code wants to refer to a tagged object like a wsi or vhost, there are helpers that return a const char * containing the tag

lws_wsi_tag(wsi) lws_vh_tag(vh)