[babeltrace.git] / doc / man / babeltrace-sink.ctf.fs.7.txt

babeltrace-sink.ctf.fs(7)
=========================
:manpagetype: component class
:revdate: 5 October 2017


NAME
----
babeltrace-sink.ctf.fs - Babeltrace's file system CTF sink component
class


DESCRIPTION
-----------
The Babeltrace compcls:sink.ctf.fs component class, provided by the
man:babeltrace-plugin-ctf(7) plugin, once instantiated, writes the
events it receives to one or more http://diamon.org/ctf/[CTF] traces on
the file system.

A compcls:sink.ctf.fs component does not merge traces, in that it writes
the notifications of different input traces to different output traces.

This component guarantees that the output traces are semantically
equivalent to the input traces. This means that a given output CTF trace
contains:

* The original trace environment.
* The original clock classes.
* The original event class names, log levels, and other static
  attributes, except for the numeric IDs.
* The original field _values_, except for:
** Timestamp fields, but the equivalent clock value remains the same.
** Numeric ID fields.

The component does not guarantee to keep:

* The original field type attributes (for example, the sizes of the
  integer field types).
* The original stream class and event class numeric IDs.


Output path
~~~~~~~~~~~
The path of a CTF trace is the directory which directly contains the
metadata and data stream files as children.

The rules to determine the path of a generated CTF trace are:

* If the param:single-trace parameter is true, use the value of the
  param:path parameter.
+
Otherwise:
+
--
* If the input trace has a name, use `OUTPUTPATH/TRACENAME[SUFFIX]`,
  where `OUTPUTPATH` is the value of the param:path parameter,
  `TRACENAME` is the input trace's name, and `SUFFIX` is an optional
  numeric suffix if `OUTPUTPATH/TRACENAME` already exists.
+
Note that the name of a trace that a compcls:source.ctf.fs component
creates includes its hostname and its relative path while making sure to
avoid conflicts.
+
Otherwise, use `OUTPUTPATH/trace[SUFFIX]`, where `OUTPUTPATH` and
`SUFFIX` are defined above.
--


INITIALIZATION PARAMETERS
-------------------------
param:path='PATH' (string, mandatory)::
    Depending on the value of the param:single-trace parameter, prefix
    of output trace paths or full output trace path.

param:single-trace=`yes` (boolean, optional)::
    Assume that the component only receives notifications related to
    a single source trace.


PORTS
-----
Input
~~~~~
`in`::
    Single input port from which the component receives the
    notifications.


QUERY OBJECTS
-------------
This component class has no objects to query.


ENVIRONMENT VARIABLES
---------------------
include::common-ctf-plugin-env.txt[]


Component class
~~~~~~~~~~~~~~~
include::common-common-compat-env.txt[]

`BABELTRACE_SINK_CTF_FS_LOG_LEVEL`::
    Component class's log level. The available values are the
    same as for the manopt:babeltrace(1):--log-level option of
    man:babeltrace(1).


include::common-footer.txt[]


SEE ALSO
--------
man:babeltrace-plugin-ctf(7),
man:babeltrace-intro(7)
Commit	Line	Data
0659f3af PP	1	babeltrace-sink.ctf.fs(7)
	2	=========================
	3	:manpagetype: component class
	4	:revdate: 5 October 2017
	5
	6
	7	NAME
	8	----
	9	babeltrace-sink.ctf.fs - Babeltrace's file system CTF sink component
	10	class
	11
	12
	13	DESCRIPTION
	14	-----------
	15	The Babeltrace compcls:sink.ctf.fs component class, provided by the
	16	man:babeltrace-plugin-ctf(7) plugin, once instantiated, writes the
	17	events it receives to one or more http://diamon.org/ctf/[CTF] traces on
	18	the file system.
	19
	20	A compcls:sink.ctf.fs component does not merge traces, in that it writes
	21	the notifications of different input traces to different output traces.
	22
	23	This component guarantees that the output traces are semantically
	24	equivalent to the input traces. This means that a given output CTF trace
	25	contains:
	26
	27	* The original trace environment.
	28	* The original clock classes.
	29	* The original event class names, log levels, and other static
	30	attributes, except for the numeric IDs.
	31	* The original field _values_, except for:
	32	** Timestamp fields, but the equivalent clock value remains the same.
	33	** Numeric ID fields.
	34
	35	The component does not guarantee to keep:
	36
	37	* The original field type attributes (for example, the sizes of the
	38	integer field types).
	39	* The original stream class and event class numeric IDs.
	40
	41
	42	Output path
	43	~~~~~~~~~~~
	44	The path of a CTF trace is the directory which directly contains the
	45	metadata and data stream files as children.
	46
	47	The rules to determine the path of a generated CTF trace are:
	48
	49	* If the param:single-trace parameter is true, use the value of the
	50	param:path parameter.
	51	+
	52	Otherwise:
	53	+
	54	--
	55	* If the input trace has a name, use `OUTPUTPATH/TRACENAME[SUFFIX]`,
	56	where `OUTPUTPATH` is the value of the param:path parameter,
	57	`TRACENAME` is the input trace's name, and `SUFFIX` is an optional
	58	numeric suffix if `OUTPUTPATH/TRACENAME` already exists.
	59	+
	60	Note that the name of a trace that a compcls:source.ctf.fs component
	61	creates includes its hostname and its relative path while making sure to
	62	avoid conflicts.
	63	+
	64	Otherwise, use `OUTPUTPATH/trace[SUFFIX]`, where `OUTPUTPATH` and
65	`SUFFIX` are defined above.
66	--
67
68
69	INITIALIZATION PARAMETERS
70	-------------------------
71	param:path='PATH' (string, mandatory)::
72	Depending on the value of the param:single-trace parameter, prefix
73	of output trace paths or full output trace path.
74
75	param:single-trace=`yes` (boolean, optional)::
76	Assume that the component only receives notifications related to
77	a single source trace.
78
79
80	PORTS
81	-----
82	Input
83	~~~~~
84	`in`::
85	Single input port from which the component receives the
86	notifications.
87
88
89	QUERY OBJECTS
90	-------------
91	This component class has no objects to query.
92
93
94	ENVIRONMENT VARIABLES
95	---------------------
96	include::common-ctf-plugin-env.txt[]
97
98
99	Component class
100	~~~~~~~~~~~~~~~
101	include::common-common-compat-env.txt[]
102
103	`BABELTRACE_SINK_CTF_FS_LOG_LEVEL`::
104	Component class's log level. The available values are the
105	same as for the manopt:babeltrace(1):--log-level option of
106	man:babeltrace(1).
107
108
109	include::common-footer.txt[]
110
111
112	SEE ALSO
113	--------
114	man:babeltrace-plugin-ctf(7),
115	man:babeltrace-intro(7)