feat: number every record with a meta sequenceId

  <134>1 ... solid-syslog-example - BOOT [meta sequenceId="1"] device started

  Flash  +6,052 B  (+944 on the previous stage)
  RAM    +1,972 B    (+64)

The counter increments once per record *formatted*, not per record delivered. A
record that never reaches the collector therefore leaves a gap in the sequence
rather than no trace at all — which is the whole value of the field, and the
reason it lands before the circular buffer rather than after it. Instrument
first, then introduce the failure mode; the other order means asserting a drop
you already caused.

The first SD-ELEMENT also introduces the rule that governs the rest: unlike a
header field, an SD PARAM has no NILVALUE, so an unset one is omitted entirely
rather than written as "-".

StdAtomic joins the platform list, and here that is all it is. Naming it compiles
its two sources exactly as naming LwipRaw compiles its eleven, because the
fragment hands back sources rather than link targets. The counter is the real one
rather than the Null fallback that reports 1 forever — the image retains its
StdAtomicCounter symbols.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: DavidCozens

README.md

@@ -10,43 +10,51 @@ It builds on a baseline that simulates the sort of device you might be adding th
 measures itself: see [docs/baseline.md](docs/baseline.md) for what the baseline is, how the
 figures are made, and how to run it.
 
-## This stage — Header fields
+## This stage — Sequence numbers
 
-The record so far carries no timestamp and no device name. Fill the RFC 5424 header fields from
-what the device already has: the clock it acquired at boot, the address on its interface, and its
-own name.
+Add the first structured-data element, `SolidSyslogMetaSd`, carrying a sequence number. Elements
+are supplied to the logger as an array and read on every record, so they must outlive the call that
+creates the logger.
 
 ```c
+static struct SolidSyslogStructuredData* sd[1];
+
+struct SolidSyslogMetaSdConfig metaConfig = {
+    .Counter = SolidSyslogStdAtomicCounter_Create(),
+};
+sd[0] = SolidSyslogMetaSd_Create(&metaConfig);
+
 struct SolidSyslogConfig config = {
     /* ... */
-    .Clock       = SyslogFields_Clock,
-    .GetHostname = SyslogFields_Hostname,
-    .GetAppName  = SyslogFields_AppName,
+    .Sd      = sd,
+    .SdCount = 1U,
 };
 ```
 
 ```text
-<134>1 2026-08-16T19:17:54.430000Z 10.0.2.15 solid-syslog-example - BOOT - device started
+... BOOT [meta sequenceId="1"] device started
 ```
 
-PROCID stays nil, because a bare-metal image has no process to identify, and so does
-STRUCTURED-DATA until the next stage.
+The sequence number is incremented once per record *formatted*, not once per record delivered. A
+record that never arrives therefore leaves a gap in the sequence rather than no trace at all, which
+is why it is worth adding before any buffering or storage that could drop one. Instrument first,
+then introduce the failure mode.
+
+Unlike a header field, an SD PARAM has no nil value: one that is unset is omitted entirely rather
+than written as `-`.
 
-Two things the adapters have to get right. The timestamp struct is zeroed before it is filled, so a
-clock that cannot answer leaves `Month == 0`, fails the library's validation, and is emitted as the
-nil value rather than as a wrong time. And the hostname is read under the lwIP core lock, with
-`ip4addr_ntoa_r` rather than `ip4addr_ntoa` — the latter shares one static buffer across callers.
+The counter comes from `SolidSyslogStdAtomicCounter`. If your toolchain has no atomics, supply your
+own to the contract `SolidSyslogAtomicCounter_Increment` states — and note that logging from more
+than one task is what makes the atomic part of it necessary.
 
-Where a device has no resolvable name, RFC 5424 section 6.2.4 allows its address in the HOSTNAME
-field instead, which is this device exactly.
+`StdAtomic` joins the platform list, and here that is all it is: naming it compiles its two sources
+exactly as naming `LwipRaw` compiles its eleven.
 
-**When you need it.** As soon as more than one device reports to the collector, or a record's time
-will be relied on. Everything the later stages add — a sequence number, the clock's quality, the
-device's own identity — builds on these fields rather than replacing them.
+**When you need it.** If anyone needs to know that records have gone missing.
 
 <!-- STAGE-COST:START (generated by scripts/gen-cost-table.py — do not edit by hand) -->
 
-**Cost above baseline: Flash +5,108 B, RAM +1,908 B.**
+**Cost above baseline: Flash +6,052 B, RAM +1,972 B.**
 
 <!-- STAGE-COST:END -->
 
@@ -65,6 +73,7 @@ committed as [`run-report.md`](run-report.md), and rewritten by every stage.
 | Logger created | the logger object, reporting exactly what is still missing from it | +1,060 | +184 |
 | First record | a valid RFC 5424 record on the wire, over UDP | +4,724 | +1,908 |
 | Header fields | a timestamped record naming the device, instead of nil values | +5,108 | +1,908 |
+| Sequence numbers | every record numbered, so a gap in the sequence is visible | +6,052 | +1,972 |
 
 *Deltas are bytes above the baseline, which is itself Flash 350,124 B, RAM 111,192 B.*
 

app/syslog/Syslog.c

@@ -2,7 +2,10 @@
  *
  * The smallest wiring that delivers: a UDP sender over lwIP, with a passthrough
  * buffer in front of it. Passthrough means Log sends inline on the calling task
- * — no queue, no background drain, nothing to service. */
+ * — no queue, no background drain, nothing to service.
+ *
+ * Unlike a header field, an SD PARAM has no NILVALUE: an unset one is omitted
+ * entirely rather than written as "-". */
 
 #include "Syslog.h"
 
@@ -13,8 +16,10 @@
 #include "SolidSyslogLwipRawDatagram.h"
 #include "SolidSyslogLwipRawMarshal.h"
 #include "SolidSyslogLwipRawResolver.h"
+#include "SolidSyslogMetaSd.h"
 #include "SolidSyslogNullStore.h"
 #include "SolidSyslogPassthroughBuffer.h"
+#include "SolidSyslogStdAtomicCounter.h"
 #include "SolidSyslogUdpSender.h"
 #include "SyslogFields.h"
 
@@ -32,6 +37,9 @@
 
 static struct SolidSyslog* s_logger = NULL;
 
+/* The logger reads these on every record, so they outlive Syslog_Start. */
+static struct SolidSyslogStructuredData* s_sd[1];
+
 /* Every lwIP Raw call the datagram makes has to happen on the thread that owns
  * the lwIP core. lwipopts.h sets LWIP_TCPIP_CORE_LOCKING, so taking the core
  * lock in the caller's own task is simpler and cheaper than posting to the tcpip
@@ -70,6 +78,11 @@ void Syslog_Start(void)
     };
     struct SolidSyslogSender* sender = SolidSyslogUdpSender_Create(&senderConfig);
 
+    /* One counter Increment per record formatted, so a record that never reaches
+     * the collector leaves a gap in the sequence rather than no trace at all. */
+    struct SolidSyslogMetaSdConfig metaConfig = {.Counter = SolidSyslogStdAtomicCounter_Create()};
+    s_sd[0] = SolidSyslogMetaSd_Create(&metaConfig);
+
     struct SolidSyslogConfig config = {
         .Buffer = SolidSyslogPassthroughBuffer_Create(sender),
         .Sender = sender,
@@ -80,6 +93,8 @@ void Syslog_Start(void)
         .Clock = SyslogFields_Clock,
         .GetHostname = SyslogFields_Hostname,
         .GetAppName = SyslogFields_AppName,
+        .Sd = s_sd,
+        .SdCount = sizeof(s_sd) / sizeof(s_sd[0]),
     };
 
     s_logger = SolidSyslog_Create(&config);

make/solidsyslog.mk

@@ -3,7 +3,7 @@
 # upstream option it needs.
 # https://docs.cososo.co.uk/solid-syslog/getting-started/#path-b--non-cmake-integrator-the-manifest
 
-SOLIDSYSLOG_PLATFORMS := LwipRaw
+SOLIDSYSLOG_PLATFORMS := LwipRaw StdAtomic
 include $(THIRD_PARTY)/solid-syslog/solidsyslog.mk
 
 SOLIDSYSLOG_LIB := $(BUILD)/libSolidSyslog.a

measurements/sequence-id.csv

@@ -0,0 +1,13 @@
+# sequence-id figures (bytes) — captured by scripts/run.sh (CAPTURE=1).
+# The device reads measurements/Baseline.csv as its frozen baseline and reports current-minus-Baseline.
+flash_text,355704
+flash_data,472
+static_bss,112692
+heap_used,4440
+mbedtls_peak,21320
+mbedtls_free,11448
+lwip_mem_free,7576
+lwip_pbufs_free,14
+stack_log,1024
+stack_service,52
+stack_harness,2848

measurements/stages.tsv

@@ -15,3 +15,4 @@ error-handler	Error handler	a fault inside the logger reaches the console instea
 logger	Logger created	the logger object, reporting exactly what is still missing from it
 udp	First record	a valid RFC 5424 record on the wire, over UDP
 header-fields	Header fields	a timestamped record naming the device, instead of nil values
+sequence-id	Sequence numbers	every record numbered, so a gap in the sequence is visible

run-report.md

@@ -1,4 +1,4 @@
-# solid-syslog-example — run (header-fields)
+# solid-syslog-example — run (sequence-id)
 
 ## Device (self-measured)
 
@@ -10,12 +10,12 @@
 [device]   first record logged: yes
 [report] --- SolidSyslog cost above baseline (simulated existing application) ---
 [report] key,current,baseline,used_above_baseline
-[report] flash_text,354784,349808,4976
-[report] flash_data,448,316,132
-[report] static_bss,112652,110876,1776
+[report] flash_text,355704,349808,5896
+[report] flash_data,472,316,156
+[report] static_bss,112692,110876,1816
 [report] heap_used,4440,4440,0
-[report] mbedtls_peak,21292,21328,-36
-[report] mbedtls_free,11476,11440,36
+[report] mbedtls_peak,21352,21328,24
+[report] mbedtls_free,11416,11440,-24
 [report] lwip_mem_free,7576,7576,0
 [report] lwip_pbufs_free,14,13,1
 [report] stack_log,1024,120,904
@@ -29,7 +29,7 @@
 
 ```text
    text	   data	    bss	    dec	    hex	filename
- 354776	    456	 112652	 467884	  723ac	/w/build/baseline.elf
+ 355696	    480	 112692	 468868	  72784	/w/build/baseline.elf
 ```
 
 ## Listeners (proved before the device ran)
@@ -47,21 +47,21 @@
 ## Collector (syslog-ng) received
 
 ```text
-wire   <134>1 2026-08-16T19:19:27.850000Z 10.0.2.15 solid-syslog-example - BOOT - device started
-parsed PRIORITY=134 TIMESTAMP=2026-08-16T19:19:27+00:00 HOSTNAME=10.0.2.15 APP_NAME=solid-syslog-example PROCID= MSGID=BOOT STRUCTURED_DATA= MSG=device started
+wire   <134>1 2026-08-16T19:22:20.850000Z 10.0.2.15 solid-syslog-example - BOOT [meta sequenceId="1"] device started
+parsed PRIORITY=134 TIMESTAMP=2026-08-16T19:22:20+00:00 HOSTNAME=10.0.2.15 APP_NAME=solid-syslog-example PROCID= MSGID=BOOT STRUCTURED_DATA=[meta sequenceId="1"] MSG=device started
 ```
 
-## Self-check (vs measurements/header-fields.csv)
+## Self-check (vs measurements/sequence-id.csv)
 
 ```text
-  OK    flash_text: 354784 (expected 354784, Δ0)
-  OK    flash_data: 448 (expected 448, Δ0)
-  OK    static_bss: 112652 (expected 112652, Δ0)
+  OK    flash_text: 355704 (expected 355704, Δ0)
+  OK    flash_data: 472 (expected 472, Δ0)
+  OK    static_bss: 112692 (expected 112692, Δ0)
   OK    heap_used: 4440 (expected 4440, Δ0)
-  OK    mbedtls_peak: 21292 (expected 21288, Δ4)
-  OK    mbedtls_free: 11476 (expected 11480, Δ4)
+  OK    mbedtls_peak: 21352 (expected 21320, Δ32)
+  OK    mbedtls_free: 11416 (expected 11448, Δ32)
   OK    lwip_mem_free: 7576 (expected 7576, Δ0)
-  OK    lwip_pbufs_free: 14 (expected 13, Δ1)
+  OK    lwip_pbufs_free: 14 (expected 14, Δ0)
   OK    stack_log: 1024 (expected 1024, Δ0)
   OK    stack_service: 52 (expected 52, Δ0)
   OK    stack_harness: 2848 (expected 2848, Δ0)