Collectors

The Collector API provide a consistent way of collecting arbitrary data from a target. Data is collected via an instance of a class derived from CollectorBase.

Example

The following example shows how to use a collector to read the logcat output from an Android target.

# import and instantiate the Target and the collector
# (note: this assumes exactly one android target connected
#  to the host machine).
In [1]: from devlib import AndroidTarget, LogcatCollector

In [2]: t = AndroidTarget()

# Set up the collector on the Target.

In [3]: collector = LogcatCollector(t)

# Configure the output file path for the collector to use.
In [4]: collector.set_output('adb_log.txt')

# Reset the Collector to preform any required configuration or preparation.
In [5]: collector.reset()

# Start Collecting
In [6]: collector.start()

# Wait for some output to be generated
In [7]: sleep(10)

# Stop Collecting
In [8]: collector.stop()

# Retrieved the collected data
In [9]: output = collector.get_data()

# Display the returned ``CollectorOutput`` Object.
In [10]: output
Out[10]: [<adb_log.txt (file)>]

In [11] log_file = output[0]

# Get the path kind of the the returned CollectorOutputEntry.
In [12]: log_file.path_kind
Out[12]: 'file'

# Get the path of the returned CollectorOutputEntry.
In [13]: log_file.path
Out[13]: 'adb_log.txt'

# Find the full path to the log file.
In [14]: os.path.join(os.getcwd(), logfile)
Out[14]: '/tmp/adb_log.txt'

API

CollectorBase

class devlib.collector.CollectorBase(target, **kwargs)

A CollectorBase is the the base class and API that should be implemented to allowing collecting various data from a traget e.g. traces, logs etc.

Collector.setup(*args, **kwargs)

This will set up the collector on the target. Parameters this method takes are particular to subclasses (see documentation for specific collectors below). What actions are performed by this method are also collector-specific. Usually these will be things like installing executables, starting services, deploying assets, etc. Typically, this method needs to be invoked at most once per reboot of the target (unless teardown() has been called), but see documentation for the collector you’re interested in.

CollectorBase.reset()

This can be used to configure a collector for collection. This must be invoked before start() is called to begin collection.

CollectorBase.start()

Starts collecting from the target.

CollectorBase.stop()

Stops collecting from target. Must be called after start().

CollectorBase.set_output(output_path)

Configure the output path for the particular collector. This will be either a directory or file path which will be used when storing the data. Please see the individual Collector documentation for more information.

CollectorBase.get_data()

The collected data will be return via the previously specified output_path. This method will return a CollectorOutput object which is a subclassed list object containing individual CollectorOutputEntry objects with details about the individual output entry.

CollectorOutputEntry

This object is designed to allow for the output of a collector to be processed generically. The object will behave as a regular string containing the path to underlying output path and can be used directly in os.path operations.

CollectorOutputEntry.path

The file path for the corresponding output item.

CollectorOutputEntry.path_kind

The type of output the is specified in the path attribute. Current valid kinds are: file and directory.

CollectorOutputEntry.__init__(path, path_kind)

Initialises a CollectorOutputEntry object with the desired file path and kind of file path specified.

Available Collectors

This section lists collectors that are currently part of devlib.

Todo

Add collectors