- import babeltrace.writer as btw
- import babeltrace.common
- import tempfile
-
-
- trace_path = tempfile.mkdtemp()
-
- print('trace path: {}'.format(trace_path))
-
-
- writer = btw.Writer(trace_path)
-
- clock = btw.Clock('my_clock')
- clock.description = 'this is my clock'
- writer.add_clock(clock)
-
- stream_class = btw.StreamClass('my_stream')
- stream_class.clock = clock
-
- event_class = btw.EventClass('my_event')
-
- # 32-bit signed integer field declaration
- int32_field_decl = btw.IntegerFieldDeclaration(32)
- int32_field_decl.signed = True
-
- # string field declaration
- string_field_decl = btw.StringFieldDeclaration()
- string_field_decl.encoding = babeltrace.common.CTFStringEncoding.UTF8
-
- # IEEE 754 single precision floating point number field declaration
- float_field_decl = btw.FloatingPointFieldDeclaration()
- float_field_decl.exponent_digits = btw.FloatingPointFieldDeclaration.FLT_EXP_DIG
- float_field_decl.mantissa_digits = btw.FloatingPointFieldDeclaration.FLT_MANT_DIG
-
- # enumeration field declaration (variant's tag)
- enum_field_decl = btw.EnumerationFieldDeclaration(int32_field_decl)
- enum_field_decl.add_mapping('INT', 0, 0)
- enum_field_decl.add_mapping('STRING', 1, 1)
- enum_field_decl.add_mapping('FLOAT', 2, 2)
-
- # variant field declaration (variant's tag field will be named `vartag`)
- variant_field_decl = btw.VariantFieldDeclaration(enum_field_decl, 'vartag')
+ import bt2
+ import sys
+
+ # Create an empty graph.
+ graph = bt2.Graph()
+
+ # Add a `source.text.dmesg` component.
+ #
+ # graph.add_component() returns the created and added component.
+ #
+ # Such a component reads Linux kernel ring buffer messages (see
+ # `dmesg(1)`) from the standard input and creates corresponding event
+ # messages. See `babeltrace2-source.text.dmesg(7)`.
+ #
+ # `my source` is the unique name of this component within `graph`.
+ comp_cls = bt2.find_plugin('text').source_component_classes['dmesg']
+ src_comp = graph.add_component(comp_cls, 'my source')
+
+ # Add a `sink.text.pretty` component.
+ #
+ # Such a component pretty-prints event messages on the standard output
+ # (one message per line). See `babeltrace2-sink.text.pretty(7)`.
+ #
+ # The `babeltrace2 convert` CLI command uses a `sink.text.pretty`
+ # sink component by default.
+ comp_cls = bt2.find_plugin('text').sink_component_classes['pretty']
+ sink_comp = graph.add_component(comp_cls, 'my sink')
+
+ # Connect the `out` output port of the `source.text.dmesg` component
+ # to the `in` input port of the `sink.text.pretty` component.
+ graph.connect_ports(src_comp.output_ports['out'],
+ sink_comp.input_ports['in'])
+
+ # Run the trace processing graph.
+ graph.run()
+
+Run this example:
+
+.. code-block:: text
+
+ $ dmesg -t | python3 example.py
+
+Output example:
+
+.. code-block:: text
+
+ string: { str = "ata1.00: NCQ Send/Recv Log not supported" }
+ string: { str = "ata1.00: ACPI cmd ef/02:00:00:00:00:a0 (SET FEATURES) succeeded" }
+ string: { str = "ata1.00: ACPI cmd f5/00:00:00:00:00:a0 (SECURITY FREEZE LOCK) filtered out" }
+ string: { str = "ata1.00: ACPI cmd ef/10:03:00:00:00:a0 (SET FEATURES) filtered out" }
+ string: { str = "ata1.00: NCQ Send/Recv Log not supported" }
+ string: { str = "ata1.00: configured for UDMA/133" }
+ string: { str = "ata1.00: Enabling discard_zeroes_data" }
+ string: { str = "OOM killer enabled." }
+ string: { str = "Restarting tasks ... done." }
+ string: { str = "PM: suspend exit" }
+
+Query a component class
+-----------------------
+Component classes, provided by plugins, can implement a method to
+support *query operations*.
+
+A query operation is similar to a function call: the caller makes a
+request (a query) with parameters and the component class's query
+method returns a result object.
+
+The query operation feature exists so that you can benefit from a
+component class's implementation to get information about a trace, a
+stream, a distant server, and so on. For example, the
+``source.ctf.lttng-live`` component class (see
+:bt2man:`babeltrace2-source.ctf.lttng-live(7)`) offers the ``sessions``
+object to list the available
+`LTTng live <https://lttng.org/docs/v2.11/#doc-lttng-live>`_ tracing
+session names and other properties.
+
+The semantics of the query parameters and the returned object are
+completely defined by the component class implementation: the library
+and its Python bindings don't enforce or suggest any layout.
+The best way to know which objects you can query from a component class,
+what are the expected and optional parameters, and what the returned
+object contains is to read this component class's documentation.
+
+The following example queries the "standard" ``babeltrace.support-info``
+query object (see
+:bt2man:`babeltrace2-query-babeltrace.support-info(7)`) from the
+``source.ctf.fs`` component class
+(see :bt2man:`babeltrace2-source.ctf.fs(7)`) and
+pretty-prints the result. The ``babeltrace.support-info`` query object
+indicates whether or not a given path locates a
+:abbr:`CTF (Common Trace Format)` trace directory::
+
+ import bt2
+ import sys
+
+ # Get the `source.ctf.fs` component class from the `ctf` plugin.
+ comp_cls = bt2.find_plugin('ctf').source_component_classes['fs']
+
+ # The `babeltrace.support-info` query operation expects a `type`
+ # parameter (set to `directory` here) and an `input` parameter (the
+ # actual path or string to check, in this case the first command-line
+ # argument).
+ #
+ # See `babeltrace2-query-babeltrace.support-info(7)`.
+ params = {
+ 'type': 'directory',
+ 'input': sys.argv[1],
+ }
+
+ # Create a query executor.
+ #
+ # This is the environment in which query operations happens. The
+ # queried component class has access to this executor, for example to
+ # retrieve the query operation's logging level.
+ query_exec = bt2.QueryExecutor(comp_cls, 'babeltrace.support-info',
+ params)
+
+ # Query the component class through the query executor.
+ #
+ # This method returns the result.
+ result = query_exec.query()
+
+ # Print the result.
+ print(result)