.. _bag-introspect:
.. _tool-introspect:

================
 bag introspect
================

.. program:: bag introspect

Synopsis
========

:samp:`bag introspect {[OPTIONS]} {INPUT-FILE1 or -} [{INPUT-FILE2} ...]`

Description
===========

Display :term:`introspection` information for hosts, processes and
:term:`participants <participant>` that is stored in a :term:`log
files <log file>`.

.. seealso::

   :ref:`rsb:common-options`
     The usual RSB-related commandline options are accepted.

   :ref:`replay-related-options`
     The usual replay-related commandline options are accepted.

.. option:: --style SPEC, -s SPEC

   Specify a processing style for :term:`introspection`
   data. :samp:`{SPEC}` has to be of the form::

     KIND KEY1 VALUE1 KEY2 VALUE2 ...

   where keys and values are optional and depend on
   :samp:`{KIND}`. Examples (note that the single quotes have to be
   included only when within a shell):

   .. code-block:: sh

      --style object-tree
      -s monitor
      -s 'object-tree :delay 5'

   .. tip::

      Use the :option:`common --help-for` ``styles`` or
      :option:`common --help-for` ``all`` options to display the full
      help text for this item.

.. option:: --target-stream STREAM-NAME

   Stream to which produced output should be sent. Allowed values for
   :samp:`{STREAM-NAME}`: ``stdout``, ``standard-output``, ``stderr``,
   ``error-output``

Examples
========

* .. code-block:: sh

     $ bag introspect log-file.tide

  Gather introspection information from the :term:`log file`
  :file:`log-file.tide` and display it using the default formatting
  style.