API

Job Description

Jobs

JVMs

Hooks

Workloads

Tools

Filters

Library which abstracts SFTP and FTP connections

Module author: Fabian Hirschmann <fabian@hirschmann.email>

copyright:PenchY Developers 2011-2012, see AUTHORS
license:MIT License, see LICENSE
class penchy.deploy.CopyDeploy[source]

Bases: penchy.deploy.Deploy

Allows you to copy files locally.

connection_required(*args, **kwds)

Contextmanager to make sure we are connected before uploading to this host.

class penchy.deploy.Deploy(hostname, username, password, port=None)[source]

Bases: object

Base class from which all deployment methods must inherit from.

Parameters:
  • hostname (str) – hostname of the host
  • username (str) – username on the host
  • password (str) – password on the host
  • port (int) – port of the service
connect()[source]

Establish connection to this host.

connected

Indicates if we are connected to the host.

connection_required(*args, **kwds)[source]

Contextmanager to make sure we are connected before uploading to this host.

disconnect()[source]

Disconnect from this host.

put(local, remote)[source]

Upload a file to this host.

Parameters:
  • local (str) – file to upload
  • remote (str) – destination to upload to
class penchy.deploy.FTPDeploy(*args, **kwargs)[source]

Bases: penchy.deploy.Deploy

Provides communication with a FTP Server.

Parameters:
  • hostname (str) – hostname of the host
  • username (str) – username on the host
  • password (str) – password on the host
  • port (int) – port of the service (defaults to 21)
  • tls (boolean) – use TLS support as described in RFC 4217 (defaults to True)
  • passive (boolean) – ftp passive mode (defaults to True)
connection_required(*args, **kwds)

Contextmanager to make sure we are connected before uploading to this host.

class penchy.deploy.SFTPDeploy(*args, **kwargs)[source]

Bases: penchy.deploy.Deploy

Provides communication with a SFTP Server.

Parameters:
  • hostname (str) – hostname of the host
  • username (str) – username on the host
  • keyfile (str) – private key to use (defaults to system keyfile)
  • password (str) – password on the host can be empty for passphraseless public key authentication or set to the passphrase of a key
  • port (int) – port of the service (defaults to 22)
connection_required(*args, **kwds)

Contextmanager to make sure we are connected before uploading to this host.

Plots

Type checking

Pipeline dependency specification

Maven Dependencies

class penchy.maven.MavenDependency(groupId, artifactId, version, repo=None, classifier=None, artifact_type=None, packaging=None, filename=None, checksum=None)[source]

Bases: object

This class represents a Maven Dependency.

A sample Maven Dependency might look like:

dep = MavenDependency('de.tu_darmstadt.penchy',
                      'pia', '2.0.0.0', 'http://mvn.0x0b.de')

This class will try its best to determine the filename on its own, but since it’s not always clear what the exact filename will be like, it might be neccessary to pass it as keyword argument. If the filename cannot be determined, LookupError will be thrown.

If the checksum parameter is specified, the file’s sha1 checksum will be checked against this checksum. An artifact’s checksum can be computed using:

$ sha1sum myartifact-0.1.jar

A real life MavenDependency making use of the checksum feature would look like:

MavenDependency(
    'org.scalabench.benchmarks',
    'scala-benchmark-suite',
    '0.1.0-20110908.085753-2',
    'http://repo.scalabench.org/snapshots/',
    filename='scala-benchmark-suite-0.1.0-SNAPSHOT.jar',
    checksum='fb68895a6716cc5e77f62ed7992d027b1dbea355')
Parameters:
  • groupId (string) – the maven group id.
  • artifactId (string) – the maven artifact id.
  • version (string) – the version of the artifact.
  • repo (string) – the maven repository to use.
  • classifier (string) – the classifier of the artifact.
  • artifact_type (string) – the type of the artifact.
  • packaging (string) – the packaging of the artifact.
  • filename (string) – filename of the artifact; guessed if not specified.
  • checksum (string) – the sha1 checksum of the file.
actual_checksum

The actual checksum of this artifact. Will be computed and cached.

check_checksum()[source]

Checks if the checksum is correct.

Raises:IntegrityError if the checksum is not correct.
filename

The full absolute path to this artifact.

Returns:path to artifact
Return type:string

Elements of the Pipeline

Communication

Client

Executes benchmarks and filters generated data.

Module author: Fabian Hirschmann <fabian@hirschmann.email>

copyright:PenchY Developers 2011-2012, see AUTHORS
license:MIT License, see LICENSE
class penchy.client.Client(job, config, identifier, loglevel=20)[source]

Bases: object

This class represents a client which executes a job and sends the results to the server.

Parameters:args (list) – arguments; this would normally be sys.argv
run()[source]

Runs the client.

send_signal_to_composition(signum)[source]

Send signal signum to the composition which is currently running.

Parameters:signum (int) – signal number as defined in the signal module

Nodes

This module contains classes which deal with nodes (that is, connecting via ssh, uploading the job, starting it...).

Module author: Fabian Hirschmann <fabian@hirschmann.email>

copyright:PenchY Developers 2011-2012, see AUTHORS
license:MIT License, see LICENSE
class penchy.node.Node(setting, compositions)[source]

Bases: object

This class represents a node (a system on which the benchmark will be run on) and provides basic ssh/sftp functionality.

Initialize the node.

Parameters:
  • setting (NodeSetting) – the node setting
  • compositions (module) – the job module to execute
close()[source]

Close node (disconnect, receive the logs and kill the client if neccessary).

If we have not received all results from this node, the PenchY client will be killed on this node.

connect()[source]

Connect to node.

connected

Indicates whether we are connected to this node.

connection_required(*args, **kwds)[source]

Contextmanager to make sure we are connected before working on this node.

disconnect()[source]

Disconnect from node.

execute(cmd)[source]

Executes command on node.

Parameters:cmd (string) – command to execute
execute_penchy(args)[source]

Executes penchy on node.

Parameters:args (string) – arguments to pass to penchy_bootstrap
get_logs()[source]

Read the client’s log file and log it using the server’s logging capabilities.

kill()[source]

Kill PenchY on node. This will kill all processes whose parent id match penchy’s id.

A pidfile named penchy.pid must exist on the node.

kill_composition()[source]

Kill the current SystemComposition on this node.

A pidfile named penchy.pid must exist on the node.

put(local, remote=None)[source]

Upload a file to the node

Parameters:
  • local (string) – path to the local file
  • remote (string) – path to the remote file
received(composition)[source]

Should be called when a SystemComposition was received for this node.

Parameters:composition (SystemComposition) – composition which was received
received_all_results

Indicates wheter we are received all results. In other words, this is False if we are still waiting for a job which is running on a SystemComposition.

exception penchy.node.NodeError[source]

Bases: exceptions.Exception

Raised when errors occur while dealing with Node.

Server

Initiates multiple JVM Benchmarks and accumulates the results.

Module author: Fabian Hirschmann <fabian@hirschmann.email>

copyright:PenchY Developers 2011-2012, see AUTHORS
license:MIT License, see LICENSE
class penchy.server.Server(config, job)[source]

Bases: object

This class represents the server.

Parameters:
  • config (module) – config module to use
  • job (module) – module of job to execute
composition_for(hashcode)[source]

Find the SystemComposition for a given hashcode.

Parameters:hashcode (string) – hashcode of the wanted composition
Returns:the system composition
Return type:SystemComposition
exp_rcv_data(hashcode, result)[source]

Receive data from nodes.

Parameters:
  • hashcode (string) – the hashcode to identify the SystemComposition by
  • result (dict) – the result of the job
exp_report_error(hashcode, reason=None)[source]

Deal with client-side errors. Call this for each composition for which a job failed.

Parameters:hashcode (string) – the hashcode to identify the SystemComposition
exp_set_timeout(hashcode, timeout)[source]

Sets the timeout for the node identified by hashcode to timeout

Parameters:
  • hashcode (string) – hashcode for composition
  • timeout (int) – timeout in seconds
node_for(setting)[source]

Find the Node for a given NodeSetting.

Parameters:setting (string) – setting identifier to receive Node for
Returns:the Node
Return type:Node
received_all_results

Indicates wheter we have received results for all SystemComposition.

remaining_compositions

Number of composition we are still waiting for.

run()[source]

Run the server component.

run_clients()[source]

Run the client on all nodes.

run_pipeline()[source]

Called when we have received results for all compositions; starts the server-side pipeline.

Maven

Deals with Apache Maven.

Module author: Fabian Hirschmann <fabian@hirschmann.email>

copyright:PenchY Developers 2011-2012, see AUTHORS
license:MIT License, see LICENSE
class penchy.maven.BootstrapPOM[source]

Bases: penchy.maven.POM

This class represents a bootstrap POM which is used to deploy PenchY and its dependencies.

All it does is extending POM so that the POM depends on the PenchY client as found in the Maven Repository.

add_dependency(dep)

Adds a given dependency to the POM.

Parameters:dep (MavenDependency) – the dependency
add_repository(url, identifier=None)

Adds a repository to the POM.

The identifier of the repository will be equal to the url by default.

Parameters:url (string) – the URL of the repository
write(filename='pom.xml', pretty=True)

Writes the POM to a file.

Parameters:
  • filename (string) – the filename to write to
  • pretty (bool) – pretty-print resulting file
exception penchy.maven.IntegrityError[source]

Bases: exceptions.Exception

Error which occurs when the checksum of an artifact is incorrect.

class penchy.maven.MavenDependency(groupId, artifactId, version, repo=None, classifier=None, artifact_type=None, packaging=None, filename=None, checksum=None)[source]

Bases: object

This class represents a Maven Dependency.

A sample Maven Dependency might look like:

dep = MavenDependency('de.tu_darmstadt.penchy',
                      'pia', '2.0.0.0', 'http://mvn.0x0b.de')

This class will try its best to determine the filename on its own, but since it’s not always clear what the exact filename will be like, it might be neccessary to pass it as keyword argument. If the filename cannot be determined, LookupError will be thrown.

If the checksum parameter is specified, the file’s sha1 checksum will be checked against this checksum. An artifact’s checksum can be computed using:

$ sha1sum myartifact-0.1.jar

A real life MavenDependency making use of the checksum feature would look like:

MavenDependency(
    'org.scalabench.benchmarks',
    'scala-benchmark-suite',
    '0.1.0-20110908.085753-2',
    'http://repo.scalabench.org/snapshots/',
    filename='scala-benchmark-suite-0.1.0-SNAPSHOT.jar',
    checksum='fb68895a6716cc5e77f62ed7992d027b1dbea355')
Parameters:
  • groupId (string) – the maven group id.
  • artifactId (string) – the maven artifact id.
  • version (string) – the version of the artifact.
  • repo (string) – the maven repository to use.
  • classifier (string) – the classifier of the artifact.
  • artifact_type (string) – the type of the artifact.
  • packaging (string) – the packaging of the artifact.
  • filename (string) – filename of the artifact; guessed if not specified.
  • checksum (string) – the sha1 checksum of the file.
actual_checksum

The actual checksum of this artifact. Will be computed and cached.

check_checksum()[source]

Checks if the checksum is correct.

Raises:IntegrityError if the checksum is not correct.
filename

The full absolute path to this artifact.

Returns:path to artifact
Return type:string
exception penchy.maven.MavenError[source]

Bases: exceptions.Exception

Error which occurs when there Maven causes errors.

class penchy.maven.POM(encoding='UTF-8', **kwargs)[source]

Bases: object

This class represents a basic Maven POM.

Duplicates are discarded, so no repository or dependency will be defined twice in the POM.

Keywords are directly translated into children of the <project> node:

POM(groupId='de.tu_darmstadt.penchy').write('pom.xml')

would result in something like:

<project>
    <groupId>de.tu_darmstadt.penchy</groupId>
</project>
add_dependency(dep)[source]

Adds a given dependency to the POM.

Parameters:dep (MavenDependency) – the dependency
add_repository(url, identifier=None)[source]

Adds a repository to the POM.

The identifier of the repository will be equal to the url by default.

Parameters:url (string) – the URL of the repository
write(filename='pom.xml', pretty=True)[source]

Writes the POM to a file.

Parameters:
  • filename (string) – the filename to write to
  • pretty (bool) – pretty-print resulting file
exception penchy.maven.POMError[source]

Bases: exceptions.Exception

Error which occurs if there are problems during the generation of a POM.

class penchy.maven.PenchyPOM[source]

Bases: penchy.maven.POM

This class represents the POM for PenchY. It is used to install PenchY’s dependencies.

This is similar to BootstrapPOM

add_dependency(dep)

Adds a given dependency to the POM.

Parameters:dep (MavenDependency) – the dependency
add_repository(url, identifier=None)

Adds a repository to the POM.

The identifier of the repository will be equal to the url by default.

Parameters:url (string) – the URL of the repository
write(filename='pom.xml', pretty=True)

Writes the POM to a file.

Parameters:
  • filename (string) – the filename to write to
  • pretty (bool) – pretty-print resulting file
penchy.maven.extract_maven_credentials(id_, path='~/.m2/settings.xml')[source]

Extracts the username and password for a given id_ from a maven settings.xml.

Parameters:
  • id (str) – id of the remote machine as defined in the settings file
  • filename (str) – path to settings.xml; ~ constructions will be expanded
penchy.maven.get_classpath(*args, **kwargs)[source]

Returns the Java classpath using Maven.

This method expects a Maven POM (pom.xml). A POM can be generated using the BootstrapPOM or POM class:

>>> from penchy.maven import BootstrapPOM, get_classpath
>>> from penchy.jobs.workloads import ScalaBench
>>> pom = BootstrapPOM()
>>> for dep in ScalaBench.DEPENDENCIES:
...     pom.add_dependency(dep)
...
>>> pom.write()
>>> get_classpath()
'/home/fabian/.m2/repository/de/tu_darmstadt/penchy/penchy/0.1/penchy-0.1-py.zip:/home/fabian/.m2/repository/org/scalabench/benchmarks/scala-benchmark-suite/0.1.0-SNAPSHOT/scala-benchmark-suite-0.1.0-SNAPSHOT.jar'
Parameters:path (string) – path to look for pom.xml in
Returns:java classpath
Return type:string
penchy.maven.make_bootstrap_pom()[source]

Creates a Bootstrap POM and returns the temporary file it has been written to.

Returns:temporary file
Return type:NamedTemporaryFile
penchy.maven.setup_dependencies(pomfile, dependencies)[source]

Installs the required dependencies.

Parameters:
  • pomfile (string) – POM to use
  • dependencies (string) – dependencies to install
penchy.maven.write_penchy_pom(dependencies, path)[source]

Creates a POM specifying dependencies.

Parameters:
  • dependencies (Sequence of MavenDependency) – dependencies to install
  • path (string) – path to write the pom to

Internal

Utilities

This module provides miscellaneous utilities.

Module author: Fabian Hirschmann <fabian@hirschmann.email>

Module author: Michael Markert <markert.michael@googlemail.com>

copyright:PenchY Developers 2011-2012, see AUTHORS
license:MIT License, see LICENSE
penchy.util.default(value, replacement)[source]

Check if value is None and then return replacement or else value.

Parameters:
  • value – value to check
  • replacement – default replacement for value
Returns:

return the value or replacement if value is None
penchy.util.depth(l)[source]

Computes the depth of a nested balanced list. Raises ValueError if the lists are not balanced.

Parameters:l – the nested list
Return type:int
Raises:ValueError
penchy.util.dict2tree(elem, dict_)[source]

Transform the given dictionary to a ElementTree and add it to the given element.

Parameters:
  • elem (xml.etree.ElementTree.Element) – parent element
  • dict (dict) – dict to add to elem
penchy.util.die(msg)[source]

Print msg to stderr and exit with exit code 1.

Parameters:msg (str) – msg to print
penchy.util.disable_write_bytecode(*args, **kwds)[source]

Contextmanager to temporarily disable writing bytecode while executing.

penchy.util.get_config_attribute(config, name, default_value)[source]

Returns an attribute of a config module or the default value.

Parameters:
  • config – config module to use
  • name (str) – attribute name
  • default – default value
penchy.util.load_config(filename)[source]

Loads the config module from filename.

Parameters:filename (str) – filename of the config file
penchy.util.load_job(filename)[source]

Loads a job.

Parameters:filename (str) – filename of the job
penchy.util.make_bootstrap_client()[source]

Returns the temporary filename of a file containing the bootstrap client.

penchy.util.memoized(f)[source]

Decorator that provides memoization, i.e. a cache that saves the result of a function call and returns them if called with the same arguments.

The function will not be evaluated if the arguments are present in the cache.

penchy.util.sha1sum(filename, blocksize=65536)[source]

Returns the sha1 hexdigest of a file.

penchy.util.tempdir(*args, **kwds)[source]

Contextmanager to execute in new created temporary directory.

Parameters:
  • prefix (str) – prefix of the temporary directory
  • delete (bool) – delete the temporary directory afterwards
penchy.util.tree_pp(elem, level=0)[source]

Pretty-prints an ElementTree.

Parameters:
  • elem (Element) – root node
  • level (int) – current level in tree
penchy.util.unify(xs)[source]

Removes duplicates from xs while preserving the order.

Parameters:xs (list object) – the list

This module provides common statistical functions.

Module author: Pascal Wittmann <mail@pascal-wittmann.de>

copyright:PenchY Developers 2011-2012, see AUTHORS
license:MIT License, see LICENSE
penchy.statistics.average(xs)[source]

Average the numbers in xs.

Parameters:xs (list of numbers) – numbers to average
Returns:averaged numbers
Return type:float
penchy.statistics.coefficient_of_variation(xs)[source]

Computes the coefficient of variation of the samples xs, i.e. the standard deviation divided by the mean.

Parameters:xs (list of numbers) – sample values
Returns:coefficient of variation
Return type:float
penchy.statistics.standard_deviation(xs, ddof)[source]

Computes the sample standard deviation of the samples xs.

Parameters:
  • xs (list of numbers) – sample values
  • ddof (integer) – Delta Degrees of Freedom (ddof): ddof is substracted from the divisor.
Returns:

sample standard deviation
Return type:

float

Pipeline dependency resolution

Maven

penchy.maven.get_classpath(*args, **kwargs)[source]

Returns the Java classpath using Maven.

This method expects a Maven POM (pom.xml). A POM can be generated using the BootstrapPOM or POM class:

>>> from penchy.maven import BootstrapPOM, get_classpath
>>> from penchy.jobs.workloads import ScalaBench
>>> pom = BootstrapPOM()
>>> for dep in ScalaBench.DEPENDENCIES:
...     pom.add_dependency(dep)
...
>>> pom.write()
>>> get_classpath()
'/home/fabian/.m2/repository/de/tu_darmstadt/penchy/penchy/0.1/penchy-0.1-py.zip:/home/fabian/.m2/repository/org/scalabench/benchmarks/scala-benchmark-suite/0.1.0-SNAPSHOT/scala-benchmark-suite-0.1.0-SNAPSHOT.jar'
Parameters:path (string) – path to look for pom.xml in
Returns:java classpath
Return type:string
penchy.maven.setup_dependencies(pomfile, dependencies)[source]

Installs the required dependencies.

Parameters:
  • pomfile (string) – POM to use
  • dependencies (string) – dependencies to install
class penchy.maven.POM(encoding='UTF-8', **kwargs)[source]

Bases: object

This class represents a basic Maven POM.

Duplicates are discarded, so no repository or dependency will be defined twice in the POM.

Keywords are directly translated into children of the <project> node:

POM(groupId='de.tu_darmstadt.penchy').write('pom.xml')

would result in something like:

<project>
    <groupId>de.tu_darmstadt.penchy</groupId>
</project>
add_dependency(dep)[source]

Adds a given dependency to the POM.

Parameters:dep (MavenDependency) – the dependency
add_repository(url, identifier=None)[source]

Adds a repository to the POM.

The identifier of the repository will be equal to the url by default.

Parameters:url (string) – the URL of the repository
write(filename='pom.xml', pretty=True)[source]

Writes the POM to a file.

Parameters:
  • filename (string) – the filename to write to
  • pretty (bool) – pretty-print resulting file
class penchy.maven.MavenError[source]

Bases: exceptions.Exception

Error which occurs when there Maven causes errors.

class penchy.maven.IntegrityError[source]

Bases: exceptions.Exception

Error which occurs when the checksum of an artifact is incorrect.

class penchy.maven.POMError[source]

Bases: exceptions.Exception

Error which occurs if there are problems during the generation of a POM.

class penchy.maven.BootstrapPOM[source]

Bases: penchy.maven.POM

This class represents a bootstrap POM which is used to deploy PenchY and its dependencies.

All it does is extending POM so that the POM depends on the PenchY client as found in the Maven Repository.

add_dependency(dep)

Adds a given dependency to the POM.

Parameters:dep (MavenDependency) – the dependency
add_repository(url, identifier=None)

Adds a repository to the POM.

The identifier of the repository will be equal to the url by default.

Parameters:url (string) – the URL of the repository
write(filename='pom.xml', pretty=True)

Writes the POM to a file.

Parameters:
  • filename (string) – the filename to write to
  • pretty (bool) – pretty-print resulting file
class penchy.maven.PenchyPOM[source]

Bases: penchy.maven.POM

This class represents the POM for PenchY. It is used to install PenchY’s dependencies.

This is similar to BootstrapPOM

add_dependency(dep)

Adds a given dependency to the POM.

Parameters:dep (MavenDependency) – the dependency
add_repository(url, identifier=None)

Adds a repository to the POM.

The identifier of the repository will be equal to the url by default.

Parameters:url (string) – the URL of the repository
write(filename='pom.xml', pretty=True)

Writes the POM to a file.

Parameters:
  • filename (string) – the filename to write to
  • pretty (bool) – pretty-print resulting file
penchy.maven.make_bootstrap_pom()[source]

Creates a Bootstrap POM and returns the temporary file it has been written to.

Returns:temporary file
Return type:NamedTemporaryFile
penchy.maven.write_penchy_pom(dependencies, path)[source]

Creates a POM specifying dependencies.

Parameters:
  • dependencies (Sequence of MavenDependency) – dependencies to install
  • path (string) – path to write the pom to