tracing(3)

💖 tracing(3) — Library Functions Manual 💖

okay so bestie, this is the tracing(3) page from the Paho MQTT C Client Library, and it's all about how you turn on the ✨sparkle✨ of runtime tracing. no build flags, no recompiling, just vibes and environment variables. let's get into it. 💅

---

✨ NAME ✨

tracing — Tracing 🦋

so here's the tea: runtime tracing is controlled entirely by environment variables. no cap.

you switch tracing on by setting MQTT_C_CLIENT_TRACE. if you set it to ON, or to stdout, it prints to stdout (iconic, standard). literally any other value? that gets interpreted as a file name to use. so MQTT_C_CLIENT_TRACE=my-trace.log writes into that file, periodt.

how much detail you get is controlled by the MQTT_C_CLIENT_TRACE_LEVEL environment variable. valid values, from least verbose to most verbose:

1. ERROR
2. PROTOCOL
3. MINIMUM
4. MEDIUM
5. MAXIMUM

and then there's MQTT_C_CLIENT_TRACE_MAX_LINES 🌸 which limits how many lines of trace get output to a file. at most two files are used — and when they're full, the last one gets overwritten with the new trace entries. (so yeah, it rotates, don't get attached to file number two.) the default size is 1000 lines.

---

📦 MQTT Packet Tracing

okay this one is a genuine main character feature — it prints the actual MQTT packets that are sent and received. so useful, so slay. to<|place_holder_mm_span_0442|> it, use these environment variable settings:

MQTT_C_CLIENT_TRACE=ON
MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL

the output you should see looks like this:

20130528 155936.813 3 stdout-subscriber -> CONNECT cleansession: 1 (0)
20130528 155936.813 3 stdout-subscriber <- CONNACK rc: 0
20130528 155936.813 3 stdout-subscriber -> SUBSCRIBE msgid: 1 (0)
20130528 155936.813 3 stdout-subscriber <- SUBACK msgid: 1
20130528 155941.818 3 stdout-subscriber -> DISCONNECT (0)

where the fields are:

1. date
2. time
3. socket number
4. client id
5. direction (-> from client to server, <- from server to client)
6. packet details

---

🔍 Default Level Tracing

here's an extract of a default level trace of a call to connect:

19700101 010000.000 (1152206656) (0)> MQTTClient_connect:893
19700101 010000.000 (1152206656)  (1)> MQTTClient_connectURI:716
20130528 160447.479 Connecting to serverURI localhost:1883
20130528 160447.479 (1152206656)   (2)> MQTTProtocol_connect:98
20130528 160447.479 (1152206656)    (3)> MQTTProtocol_addressPort:48
20130528 160447.479 (1152206656)    (3)< MQTTProtocol_addressPort:73
20130528 160447.479 (1152206656)    (3)> Socket_new:599
20130528 160447.479 New socket 4 for localhost, port 1883
20130528 160447.479 (1152206656)     (4)> Socket_addSocket:163
20130528 160447.479 (1152206656)      (5)> Socket_setnonblocking:73
20130528 160447.479 (1152206656)      (5)< Socket_setnonblocking:78 (0)
20130528 160447.479 (1152206656)     (4)< Socket_addSocket:176 (0)
20130528 160447.479 (1152206656)     (4)> Socket_error:95
20130528 160447.479 (1152206656)     (4)< Socket_error:104 (115)
20130528 160447.479 Connect pending
20130528 160447.479 (1152206656)    (3)< Socket_new:683 (115)
20130528 160447.479 (1152206656)   (2)< MQTTProtocol_connect:131 (115)

where the fields are:

1. date
2. time
3. thread id
4. function nesting level
5. function entry (>) or exit (<)
6. function name : line of source code file
7. return value (if there is one)

---

🧠 Memory Allocation Tracing

setting the trace level to MAXIMUM (the most verbose one, remember) makes memory allocations and frees get traced along with the default trace entries. messages look like this:

20130528 161819.657 Allocating 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 177 ptr 0x179f930

20130528 161819.657 Freeing 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 201, heap use now 896 bytes

now listen, this next bit is the actual hero of the whole page 🫶 — when the last MQTT client object is destroyed, if the trace is being recorded and all memory allocated by the client library has not been freed, an error message gets written to the trace. which is so helpful for fixing memory leaks. the message will look like this:

20130528 163909.208 Some memory not freed at shutdown, possible memory leak
20130528 163909.208 Heap scan start, total 880 bytes
20130528 163909.208 Heap element size 32, line 354, file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c, ptr 0x260cb00
20130528 163909.208   Content
20130528 163909.209 Heap scan end

and then the page just… ends with this, verbatim, for reasons the page does not explain:

√*

iconic. keeping it. moving on. 😭

---

lowkey a whole debugging toolkit hiding in your environment variables. set MQTT_C_CLIENT_TRACE, pick your level, and go find those leaks bestie. 🔥

---

and that's the whole page, no skips, no cuts 💜 this was the tracing(3) manual from the Paho MQTT C Client Library, dated Tue Jun 2 2026 00:00:00. go trace something cute. 🎀✨🦋