--- /dev/null
+.. _examples:
+
+********
+Examples
+********
+
+This section presents a few short and straightforward examples
+of Babeltrace Python bindings usage.
+
+The examples are divided into two categories: those which demonstrate
+the :ref:`reader API <reader-api>`, and those which demonstrate
+the :ref:`CTF writer API <ctf-writer-api>`.
+
+
+.. _reader-api-examples:
+
+Reader API examples
+===================
+
+The :ref:`reader API <reader-api>` includes everything needed to open
+traces and iterate on events in order.
+
+
+Open one trace and print all event names
+----------------------------------------
+
+This example shows how to open a single CTF trace, iterate on all the
+events, and print their names.
+
+.. code-block:: python
+
+ import babeltrace.reader
+ import sys
+
+
+ # get the trace path from the first command line argument
+ trace_path = sys.argv[1]
+
+ trace_collection = babeltrace.reader.TraceCollection()
+
+ trace_collection.add_trace(trace_path, 'ctf')
+
+ for event in trace_collection.events:
+ print(event.name)
+
+
+Open multiple traces and print all event field names
+----------------------------------------------------
+
+This example opens multiple CTF traces (their paths are provided as
+command line arguments), iterates on all their correlated events in
+order, and prints a list of their field names.
+
+.. code-block:: python
+
+ import babeltrace.reader
+ import sys
+
+
+ trace_collection = babeltrace.reader.TraceCollection()
+
+ for path in sys.argv[1:]:
+ trace_collection.add_trace(path, 'ctf')
+
+ for event in trace_collection.events:
+ print(', '.join(event.keys()))
+
+
+Print a specific event field
+----------------------------
+
+Reading the field value of an :class:`babeltrace.reader.Event` object
+is done by using its :class:`dict`-like interface:
+
+.. code-block:: python
+
+ field_value = event['field_name']
+
+As such, you can use Python's ``in`` keyword to verify if a given
+event contains a given field name:
+
+.. code-block:: python
+
+ if 'field_name' in event:
+ # ...
+
+The following example iterates on the events of a trace, and prints the
+value of the ``fd`` field if it's available.
+
+.. code-block:: python
+
+ import babeltrace.reader
+ import sys
+
+ # get the trace path from the first command line argument
+ trace_path = sys.argv[1]
+
+ trace_collection = babeltrace.reader.TraceCollection()
+
+ trace_collection.add_trace(trace_path, 'ctf')
+
+ for event in trace_collection.events:
+ if 'fd' in event:
+ print(event['fd'])
+
+Beware that different fields of the same event may share the same name
+if they are in different scopes. In this case, the :class:`dict`-like
+interface prioritizes event payload fields before event context fields,
+event context fields before stream event context fields, and so on
+(see :class:`babeltrace.reader.Event` for this exact list of
+priorities). It is possible to get the value of an event's field
+within a specific scope using
+:meth:`babeltrace.reader.Event.field_with_scope`:
+
+.. code-block:: python
+
+ import babeltrace.reader
+ import babeltrace.common
+
+ # ...
+
+ field_value = event.field_with_scope('field_name',
+ babeltrace.common.CTFScope.EVENT_CONTEXT)
+
+
+Bonus: top 5 running processes using LTTng
+------------------------------------------
+
+Since `LTTng <http://lttng.org/>`_ produces CTF traces, the
+Babeltrace Python binding can read LTTng traces.
+
+This somewhat more complex example reads a whole LTTng Linux kernel
+trace, and outputs the short names of the top 5 running processes on
+CPU 0 during the whole trace.
+
+.. code-block:: python
+
+ from collections import Counter
+ import babeltrace.reader
+ import sys
+
+
+ # a trace collection holds one or more traces
+ col = babeltrace.reader.TraceCollection()
+
+ # add the trace provided by the user (first command line argument)
+ # (LTTng traces always have the 'ctf' format)
+ if col.add_trace(sys.argv[1], 'ctf') is None:
+ raise RuntimeError('Cannot add trace')
+
+ # this counter dict will hold execution times:
+ #
+ # task command name -> total execution time (ns)
+ exec_times = Counter()
+
+ # this holds the last `sched_switch` timestamp
+ last_ts = None
+
+ # iterate on events
+ for event in col.events:
+ # keep only `sched_switch` events
+ if event.name != 'sched_switch':
+ continue
+
+ # keep only events which happened on CPU 0
+ if event['cpu_id'] != 0:
+ continue
+
+ # event timestamp
+ cur_ts = event.timestamp
+
+ if last_ts is None:
+ # we start here
+ last_ts = cur_ts
+
+ # previous task command (short) name
+ prev_comm = event['prev_comm']
+
+ # initialize entry in our dict if not yet done
+ if prev_comm not in exec_times:
+ exec_times[prev_comm] = 0
+
+ # compute previous command execution time
+ diff = cur_ts - last_ts
+
+ # update execution time of this command
+ exec_times[prev_comm] += diff
+
+ # update last timestamp
+ last_ts = cur_ts
+
+ # print top 5
+ for name, ns in exec_times.most_common(5):
+ s = ns / 1000000000
+ print('{:20}{} s'.format(name, s))
+
+
+Inspect event declarations and their field declarations
+-------------------------------------------------------
+
+When :meth:`babeltrace.reader.TraceCollection.add_trace` is called
+and a trace is successfully opened and added, a corresponding
+:class:`babeltrace.reader.TraceHandle` object for this trace is
+returned. It is then possible to iterate on the event declarations of
+this trace handle using :attr:`babeltrace.reader.TraceHandle.events`.
+Each generated :class:`babeltrace.reader.EventDeclaration` object
+contains common properties for this type of event, including its
+field declarations. This is useful for inspecting the available
+events of a trace, and their "signature" in terms of fields, before
+iterating its actual events.
+
+This example adds a trace to a trace collection, and uses the returned
+trace handle to iterate on its event declarations. The goal here is to
+make sure the ``sched_switch`` event exists, and that it contains
+at least the following fields:
+
+* ``prev_comm``, which should be an array of 8-bit integers
+* ``prev_tid``, which should be an integer
+
+.. code-block:: python
+
+ import babeltrace.reader as btr
+ import sys
+
+
+ def validate_sched_switch_fields(event_decl):
+ found_prev_comm = False
+ found_prev_tid = False
+
+ for field_decl in event_decl.fields:
+ if field_decl.name == 'prev_comm':
+ if isinstance(field_decl, btr.ArrayFieldDeclaration):
+ elem_decl = field_decl.element_declaration
+
+ if isinstance(elem_decl, btr.IntegerFieldDeclaration):
+ if elem_decl.size == 8:
+ found_prev_comm = True
+ elif field_decl.name == 'prev_tid':
+ if isinstance(field_decl, btr.IntegerFieldDeclaration):
+ found_prev_tid = True
+
+ return found_prev_comm and found_prev_tid
+
+
+ # get the trace path from the first command line argument
+ trace_path = sys.argv[1]
+
+ trace_collection = btr.TraceCollection()
+ trace_handle = trace_collection.add_trace(trace_path, 'ctf')
+ sched_switch_found = False
+
+ for event_decl in trace_handle.events:
+ if event_decl.name == 'sched_switch':
+ if validate_sched_switch_fields(event_decl):
+ sched_switch_found = True
+ break
+
+ print('trace path: {}'.format(trace_handle.path))
+
+ if sched_switch_found:
+ print('found sched_switch!')
+ else:
+ print('could not find sched_switch')
+
+
+.. _ctf-writer-api-examples:
+
+CTF writer API examples
+=======================
+
+The :ref:`CTF writer API <ctf-writer-api>` is a set of classes which
+allows a Python script to write complete
+`CTF <http://www.efficios.com/ctf>`_ (Common Trace Format) traces.
+
+
+One trace, one stream, one event, one field
+-------------------------------------------
+
+This is the most simple example of using the CTF writer API. It creates
+one writer (responsible for writing one trace), then uses it to create
+one stream. One event with a single field is appended to this single
+stream, and everything is flushed.
+
+The trace is written in a temporary directory (its path is printed
+at the beginning of the script).
+
+.. code-block:: python
+
+ import babeltrace.writer as btw
+ import tempfile
+
+
+ # temporary directory holding the CTF trace
+ trace_path = tempfile.mkdtemp()
+
+ print('trace path: {}'.format(trace_path))
+
+ # our writer
+ writer = btw.Writer(trace_path)
+
+ # create one default clock and register it to the writer
+ clock = btw.Clock('my_clock')
+ clock.description = 'this is my clock'
+ writer.add_clock(clock)
+
+ # create one default stream class and assign our clock to it
+ stream_class = btw.StreamClass('my_stream')
+ stream_class.clock = clock
+
+ # create one default event class
+ event_class = btw.EventClass('my_event')
+
+ # create one 32-bit signed integer field
+ int32_field_decl = btw.IntegerFieldDeclaration(32)
+ int32_field_decl.signed = True
+
+ # add this field declaration to our event class
+ event_class.add_field(int32_field_decl, 'my_field')
+
+ # register our event class to our stream class
+ stream_class.add_event_class(event_class)
+
+ # create our single event, based on our event class
+ event = btw.Event(event_class)
+
+ # assign an integer value to our single field
+ event.payload('my_field').value = -23
+
+ # create our single stream
+ stream = writer.create_stream(stream_class)
+
+ # append our single event to our single stream
+ stream.append_event(event)
+
+ # flush the stream
+ stream.flush()
+
+
+Basic CTF fields
+----------------
+
+This example writes a few events with basic CTF fields: integers,
+floating point numbers, enumerations and strings.
+
+The trace is written in a temporary directory (its path is printed
+at the beginning of the script).
+
+.. code-block:: python
+
+ import babeltrace.writer as btw
+ import babeltrace.common
+ import tempfile
+ import math
+
+
+ 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
+ int32_field_decl.base = btw.IntegerBase.HEX
+
+ # 5-bit unsigned integer field declaration
+ uint5_field_decl = btw.IntegerFieldDeclaration(5)
+ uint5_field_decl.signed = False
+
+ # 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 (based on the 5-bit unsigned integer above)
+ enum_field_decl = btw.EnumerationFieldDeclaration(uint5_field_decl)
+ enum_field_decl.add_mapping('DAZED', 3, 11)
+ enum_field_decl.add_mapping('AND', 13, 13)
+ enum_field_decl.add_mapping('CONFUSED', 17, 30)
+
+ # string field declaration
+ string_field_decl = btw.StringFieldDeclaration()
+ string_field_decl.encoding = babeltrace.common.CTFStringEncoding.UTF8
+
+ event_class.add_field(int32_field_decl, 'my_int32_field')
+ event_class.add_field(uint5_field_decl, 'my_uint5_field')
+ event_class.add_field(float_field_decl, 'my_float_field')
+ event_class.add_field(enum_field_decl, 'my_enum_field')
+ event_class.add_field(int32_field_decl, 'another_int32_field')
+ event_class.add_field(string_field_decl, 'my_string_field')
+
+ stream_class.add_event_class(event_class)
+
+ stream = writer.create_stream(stream_class)
+
+ # create and append first event
+ event = btw.Event(event_class)
+ event.payload('my_int32_field').value = 0xbeef
+ event.payload('my_uint5_field').value = 17
+ event.payload('my_float_field').value = -math.pi
+ event.payload('my_enum_field').value = 8 # label: 'DAZED'
+ event.payload('another_int32_field').value = 0x20141210
+ event.payload('my_string_field').value = 'Hello, World!'
+ stream.append_event(event)
+
+ # create and append second event
+ event = btw.Event(event_class)
+ event.payload('my_int32_field').value = 0x12345678
+ event.payload('my_uint5_field').value = 31
+ event.payload('my_float_field').value = math.e
+ event.payload('my_enum_field').value = 28 # label: 'CONFUSED'
+ event.payload('another_int32_field').value = -1
+ event.payload('my_string_field').value = trace_path
+ stream.append_event(event)
+
+ stream.flush()
+
+
+Static array and sequence fields
+--------------------------------
+
+This example demonstrates how to write static array and sequence
+fields. A static array has a fixed length, whereas a sequence reads
+its length dynamically from another (integer) field.
+
+In this example, an event is appended to a single stream, in which
+three fields are present:
+
+* ``seqlen``, the dynamic length of the sequence ``seq`` (set to the
+ number of command line arguments)
+* ``array``, a static array of 23 16-bit unsigned integers
+* ``seq``, a sequence of ``seqlen`` strings, where the strings are
+ the command line arguments
+
+The trace is written in a temporary directory (its path is printed
+at the beginning of the script).
+
+.. code-block:: python
+
+ import babeltrace.writer as btw
+ import babeltrace.common
+ import tempfile
+ import sys
+
+
+ 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')
+
+ # 16-bit unsigned integer field declaration
+ uint16_field_decl = btw.IntegerFieldDeclaration(16)
+ uint16_field_decl.signed = False
+
+ # array field declaration (23 16-bit unsigned integers)
+ array_field_decl = btw.ArrayFieldDeclaration(uint16_field_decl, 23)
+
+ # string field declaration
+ string_field_decl = btw.StringFieldDeclaration()
+ string_field_decl.encoding = babeltrace.common.CTFStringEncoding.UTF8
+
+ # sequence field declaration of strings (length will be the `seqlen` field)
+ seq_field_decl = btw.SequenceFieldDeclaration(string_field_decl, 'seqlen')
+
+ event_class.add_field(uint16_field_decl, 'seqlen')
+ event_class.add_field(array_field_decl, 'array')
+ event_class.add_field(seq_field_decl, 'seq')
+
+ stream_class.add_event_class(event_class)
+
+ stream = writer.create_stream(stream_class)
+
+ # create event
+ event = btw.Event(event_class)
+
+ # set sequence length field
+ event.payload('seqlen').value = len(sys.argv)
+
+ # get array field
+ array_field = event.payload('array')
+
+ # populate array field
+ for i in range(array_field_decl.length):
+ array_field.field(i).value = i * i
+
+ # get sequence field
+ seq_field = event.payload('seq')
+
+ # assign sequence field's length field
+ seq_field.length = event.payload('seqlen')
+
+ # populate sequence field
+ for i in range(seq_field.length.value):
+ seq_field.field(i).value = sys.argv[i]
+
+ # append event
+ stream.append_event(event)
+
+ stream.flush()
+
+
+Structure fields
+----------------
+
+A CTF structure is an ordered map of field names to actual fields, just
+like C structures. In fact, an event's payload is a structure field,
+so structure fields may contain other structure fields, and so on.
+
+This examples shows how to create a structure field from a structure
+field declaration, populate it, and write an event containing it as
+a payload field.
+
+The trace is written in a temporary directory (its path is printed
+at the beginning of the script).
+
+.. code-block:: python
+
+ 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
+
+ # structure field declaration
+ struct_field_decl = btw.StructureFieldDeclaration()
+
+ # add field declarations to our structure field declaration
+ struct_field_decl.add_field(int32_field_decl, 'field_one')
+ struct_field_decl.add_field(string_field_decl, 'field_two')
+ struct_field_decl.add_field(int32_field_decl, 'field_three')
+
+ event_class.add_field(struct_field_decl, 'my_struct')
+ event_class.add_field(string_field_decl, 'my_string')
+
+ stream_class.add_event_class(event_class)
+
+ stream = writer.create_stream(stream_class)
+
+ # create event
+ event = btw.Event(event_class)
+
+ # get event's structure field
+ struct_field = event.payload('my_struct')
+
+ # populate this structure field
+ struct_field.field('field_one').value = 23
+ struct_field.field('field_two').value = 'Achilles Last Stand'
+ struct_field.field('field_three').value = -1534
+
+ # set event's string field
+ event.payload('my_string').value = 'Tangerine'
+
+ # append event
+ stream.append_event(event)
+
+ stream.flush()
+
+
+Variant fields
+--------------
+
+The CTF variant is the most versatile field type. It acts as a
+placeholder for any other type. Which type is selected depends on the
+current value of an outer enumeration field, known as a *tag* from the
+variant's point of view.
+
+Variants are typical constructs in communication protocols with
+dynamic types. For example, `BSON <http://bsonspec.org/spec.html>`_,
+the protocol used by `MongoDB <http://www.mongodb.org/>`_, has specific
+numeric IDs for each element type.
+
+This examples shows how to create a CTF variant field. The tag, an
+enumeration field, must also be created and associated with the
+variant. In this case, the tag selects between three types: a
+32-bit signed integer, a string, or a floating point number.
+
+The trace is written in a temporary directory (its path is printed
+at the beginning of the script).
+
+.. code-block:: python
+
+ 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')
+
+ # register selectable fields to variant
+ variant_field_decl.add_field(int32_field_decl, 'INT')
+ variant_field_decl.add_field(string_field_decl, 'STRING')
+ variant_field_decl.add_field(float_field_decl, 'FLOAT')
+
+ event_class.add_field(enum_field_decl, 'vartag')
+ event_class.add_field(variant_field_decl, 'var')
+
+ stream_class.add_event_class(event_class)
+
+ stream = writer.create_stream(stream_class)
+
+ # first event: integer is selected
+ event = btw.Event(event_class)
+ tag_field = event.payload('vartag')
+ tag_field.value = 0
+ event.payload('var').field(tag_field).value = 23
+ stream.append_event(event)
+
+ # second event: string is selected
+ event = btw.Event(event_class)
+ tag_field = event.payload('vartag')
+ tag_field.value = 1
+ event.payload('var').field(tag_field).value = 'The Battle of Evermore'
+ stream.append_event(event)
+
+ # third event: floating point number is selected
+ event = btw.Event(event_class)
+ tag_field = event.payload('vartag')
+ tag_field.value = 2
+ event.payload('var').field(tag_field).value = -15.34
+ stream.append_event(event)
+
+ stream.flush()
projects / babeltrace.git / blobdiff