Bug #1259
openimproved to description/usecases for streams and packets.
0%
Description
Its not clear from below documentation link that a stream is always a container of packets. The documentation says "A stream is a conceptual container of packets and/or events." . Because of the "or", the reader can think a stream can contain no packets, but still have events. This does not seem to be true, and a stream should always contain packets. Events can't sit in a stream without packets I think.
https://babeltrace.org/docs/v2.0/man7/babeltrace2-intro.7/#doc-concepts
Further it is not clear what are usecases of streams and packets. Mathieu cleared it for me that streams are use-case dependent, but I guess docs could be updated as well with these details. From our IRC chat:
[2020-04-27 09:45:04] <Compudj> joel_: I suspect that considering the scope of babeltrace2 is not limited to tracing CPUs (can be for GPU tracing for instance), it does not tie the notion of "stream" to any specific hardware concept
[2020-04-27 09:45:57] <Compudj> joel_: each stream can contain a set of event classes
[2020-04-27 09:46:13] <Compudj> more precisely, a stream class contains a set of event classes
[2020-04-27 09:46:39] <Compudj> and you can have many stream instances. One stream instance per CPU is one possible use-case
[2020-04-27 09:47:04] <Compudj> but a different tracer could choose to have one stream instance per thread
[2020-04-27 09:47:12] <Compudj> it's entirely up to the tracer
Also it is still not clear what a packet means from the above "basic concepts" documentation link. May be some details from here can be borrowed from here: ? https://wiki.eclipse.org/Linux_Tools_Project/TMF/CTF_guide#What_is_CTF.3F
Also, Mathieu said babeltrace is not tied to CTF format, but it seems to be sort of tied. The concept of Streams, packets, events seem to be 1:1. Can we have some more clarification on differences between babeltrace model and CTF in the docs as well?
Updated by Philippe Proulx 21 days ago
Because of the "or", the reader can think a stream can contain no packets, but still have events. This does not seem to be true, and a stream should always contain packets.
It can contain no packets. See the 'Supports packets?' property.
This is the trace intermediate representation (trace IR) of the Babeltrace 2 API, not CTF. CTF always has event records within packets within data streams.
Further it is not clear what are usecases of streams and packets. Mathieu cleared it for me that streams are use-case dependent, but I guess docs could be updated as well with these details.
I'll look into this, but in general I don't want the API to suggest/differentiate use cases. Reading the API docs should provide solutions to matching use cases you already have. Again, trace IR and CTF are two things, even though, because we do maintain both projects, we try to make trace IR featureful enough to support a CTF source. I don't want to mention CTF specifics in the libbabeltrace2 API docs.
Can we have some more clarification on differences between babeltrace model and CTF in the docs as well?
From the point of view of the API docs, it's only a coincidence 😉. Again, I don't think this documentation needs to specify CTF at all. CTF is only a specific use case—one that fits perfectly within the trace IR API, I'll admit that 👀.