Common Trace Format

I've read the CTF specs. for hours by now and I still think there's something wrong about it. It seems like there's a division between some structure fields and their descriptions. Instead of clearly describing fields of some structures, only examples are given. But how are the examples related to the descriptions?

I would really appreciate that all fields of the following structures be very well defined in the specs.:

• trace.packet.header
• stream.packet.context
• stream.event.header

This is actually done, but we don't see the relation between the field names and their descriptions.

Here's an example. The list following Event packet context (all fields are optional, specified by TSDL meta-data): is okay, but look at Event packet content size (in bits).: we don't know anything about this field yet. It's only later in the text that we learn:

If the content
size field is missing, the packet is filled (no padding). The content
and packet sizes include all headers.

Still, it's only when looking at the example that we see its name:

struct event_packet_context {
  uint64_t timestamp_begin;
  uint64_t timestamp_end;
  uint32_t checksum;
  uint32_t stream_packet_count;
  uint32_t events_discarded;
  uint32_t cpu_id;
  uint32_t/uint16_t content_size;
  uint32_t/uint16_t packet_size;
  uint8_t  compression_scheme;
  uint8_t  encryption_scheme;
  uint8_t  checksum_scheme;
};

But an example isn't very formal, is it? So if I want to know something about this field, I have to look at 3 different places in the specs.

And what about the cpu_id field in there? Is this LTTng-related or standard within CTF? I guess this one is really an example, but it's confusing because we learn the content size field name at the same place.

A good and easy format to understand/read would be a table, for each aforementioned structure, with the following columns:

• optional/mandatory/conditional?
• absence of field meaning: what exactly to expect if the field is absent?
• conditions if field is conditional (depends on other parameters)
• field name (e.g. content_size)
• complete description

Maybe a since version column would also be great, so we may have some backward compatibility.

Also: for each structure, is it allowed to add custom fields?