Cluster Management API reference

This section describes cluster management-related requests.

All database examples provided in this guide are specific to MySQL. If you use a different database, use syntax that is appropriate for your respective database.

createServerComment

Creates a new server comment. Server comments are displayed on the Home page of the Cluster Manager machine.

Required arguments

Field	Description
text	The text of the comment.

Field

Description

text

The text of the comment.

Optional arguments

None.

Syntax

cmtool createServerComment <text>▼

Example

cmtool createServerComment "cluster needs more servers to handle production builds"▼

Creates the server comment "cluster needs more servers to handle production builds".

deleteLicense

Deletes a license.

Required arguments

Field Description

Field	Description
productName	The name of the license, which is `ElectricAccelerator`.
featureName	Feature name of the license, which is Server.

productName

The name of the license, which is ElectricAccelerator.

featureName

Feature name of the license, which is Server.

Optional arguments

None.

Syntax

cmtool deleteLicense <productName> <featureName>▼

Example

cmtool deleteLicense ElectricAccelerator Server▼

Deletes the license stored in the server.

deleteMessage

Deletes a specific message, including all dependent records. Messages are listed in the Cluster Manager interface Messages tab and generally are notifications about issues with agents or the Cluster Manager.

Required arguments

Field	Description
messageId	The numeric value that uniquely identifies each message.

Field

Description

messageId

The numeric value that uniquely identifies each message.

Optional arguments

None.

Syntax

cmtool deleteMessage <messageId>▼

Example

cmtool deleteMessage 501▼

Deletes the message with ID 501.

deleteMessages

Deletes a set of messages, including all dependent records.

Required arguments

None.

Optional arguments

Field	Description
filter	A SQL query used to limit the result set. For a list of possible SQL values, see the getMessages command.

Field

Description

filter

A SQL query used to limit the result set. For a list of possible SQL values, see the getMessages command.

Syntax

cmtool deleteMessages [optionals...]▼

Example

cmtool deleteMessages --filter "create_time <date_sub(curdate( ), interval 200 day)"▼

Removes all messages more than 200 days old.

This example is valid for MySQL only. If you use a different database, use syntax that is appropriate for your respective database.

deleteServerComment

Deletes a server comment.

Required arguments

Field	Description
commentId	The unique key that identifies a comment.

Field

Description

commentId

The unique key that identifies a comment.

Optional arguments

None.

Syntax

cmtool deleteServerComment <commentId>▼

Example

cmtool deleteServerComment 1396▼

Deletes the server comment with ID 1396.

exportData

Exports Cluster Manager data to a file. This is a full database dump, which might take substantial time for a large database.

NOTE:

Manual migration using the exportData and importData commands is recommended only to replicate data between Cluster Manager instances running the same version of the Cluster Manager. For example, you could use it to make a backup dump and then restore it to a new instance of the Cluster Manager of the same version.
For a very large database, you should work with a database administrator to use the native database export/import facilities rather than using cmtool.

Required arguments

Field Description

Field	Description
fileName	Target file name or path. If you use a file name, the destination is the current working directory of the Java process ( `/opt/ecloud/i686_Linux` or `C:\ECloud\i686_win32` by default). If you use a path, the Cluster Manager Java user ( `eacmuser` ) must have execute and write access to that path.

fileName

Target file name or path. If you use a file name, the destination is the current working directory of the Java process ( /opt/ecloud/i686_Linux or C:\ECloud\i686_win32 by default). If you use a path, the Cluster Manager Java user ( eacmuser ) must have execute and write access to that path.

Optional arguments

None.

Syntax

cmtool exportData <filename>▼

Example

cmtool exportData fileabc▼

getLicense

Retrieves information for one license.

Required arguments

Field Description

Field	Description
productName	The name of the license, which is `ElectricAccelerator`.
featureName	The name of the feature, which is Server.

productName

The name of the license, which is ElectricAccelerator.

featureName

The name of the feature, which is Server.

Optional arguments

None.

Syntax

cmtool getLicense <productName> <featureName>▼

Example

cmtool getLicense ElectricAccelerator Server▼

getLicenses

Retrieves all license data.

Required arguments

None.

Optional arguments

None.

Syntax

cmtool getLicenses▼

Example

cmtool getLicenses▼

getMessage

Retrieves a particular message.

Required arguments

Field	Description
messageId	The numeric value that uniquely identifies each message.

Field

Description

messageId

The numeric value that uniquely identifies each message.

Optional arguments

None.

Result tags

See the getMessages command for descriptions.

agentIdagentNamebuildIdbuildNamecreateTimemessageIdseveritytext

Syntax

cmtool getMessage <messageId>▼

Example

cmtool getMessage 47▼

getMessages

Retrieves a list of messages

Required arguments

None.

Optional arguments

Field

Description

filter

A SQL query used to limit the result set. See the possible values below.

There is a syntax difference between MySQL and Oracle/MS SQL for enclosing criteria when using this argument for specific strings—for MySQL, use double quotes; for Oracle/MS SQL, use single quotes.

maxResults

The maximum number of elements to return from a query.

firstResult

The starting index for the query result set.

This argument takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.

order

A SQL order by clause. Used to specify ordering for the query result set.

profile

Can be details or info. This is the level of detail to return from a query; details gets all information and info gets a reduced information set.

Result tags and SQL query names

Field Description

Field	Description
agentId	A unique, internal number assigned to each agent by the Cluster Manager; this number can change. SQL query name for `--filter` and `--order`: N/A
agentName	A name defined by the host where the agent resides (numbers and/or letters). SQL query name for `--filter` and `--order`: `agent_name`
buildId	A unique number assigned by the Cluster Manager for each build. SQL query name for `--filter` and `--order`: `build_id`
buildName	The build name that is the expanded build class tag. SQL query name for `--filter` and `--order`: N/A
createTime	The time when the item was created. SQL query name for `--filter` and `--order`: `create_time`
messageId	The numeric value that uniquely identifies each message. SQL query name for `--filter` and `--order`: `id`
severity	The severity level of the event: Info, Warning, or Error. For `--filter` and `--order`, use the following numerical values: 1 = Info 2 = Warning 3 = Error SQL query name for `--filter` and `--order`: `severity`
text	The text of the item. SQL query name for `--filter` and `--order`: `text`

agentId

A unique, internal number assigned to each agent by the Cluster Manager; this number can change. SQL query name for --filter and --order: N/A

agentName

A name defined by the host where the agent resides (numbers and/or letters). SQL query name for --filter and --order: agent_name

buildId

A unique number assigned by the Cluster Manager for each build. SQL query name for --filter and --order: build_id

buildName

The build name that is the expanded build class tag. SQL query name for --filter and --order: N/A

createTime

The time when the item was created. SQL query name for --filter and --order: create_time

messageId

The numeric value that uniquely identifies each message. SQL query name for --filter and --order: id

severity

The severity level of the event: Info, Warning, or Error. For --filter and --order, use the following numerical values: 1 = Info 2 = Warning 3 = Error SQL query name for --filter and --order: severity

text

The text of the item. SQL query name for --filter and --order: text

Syntax

cmtool [optionals...]▼

Example

cmtool --output csv --fields buildId,severity,text getMessages --filter "text like ’%I/O%’"▼

Lists all messages in the Cluster Manager that contain the string ’I/O’.

getResourceStats

Retrieves resource usage statistics.

Required arguments

None.

Optional arguments

Field

Description

filter

A SQL query used to limit the result set. See the possible values below.

There is a syntax difference between MySQL and Oracle/MS SQL for enclosing criteria when using this argument for specific strings—for MySQL, use double quotes; for Oracle/MS SQL, use single quotes.

maxResults

The maximum number of elements to return from a query.

firstResult

The starting index for the query result set.

--firstResult takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.

order

A SQL order by clause. Used to specify ordering for the query result set.

profile

Can be details or info. This is the level of detail to return from a query; details gets all information and info gets a reduced information set.

Result tags and SQL query names

Field Description

Field	Description
agentClusterShortage	How many additional agents could have been used by the builds over the specified time period. This value is filled in only for cluster statistics—it is not available for individual resource statistics. SQL query name for `--filter` and `--order`: `agent_cluster_shortage`
agentDemand	The average number of agents all builds could have used if those agents were available. For example, if two builds use two different resources and each build could use 15 agents, the cluster load shows an Agent Demand of 30 agents, and each resource shows 15. SQL query name for `--filter` and `--order`: `agent_demand`
agentLicenseShortage	The difference between the maximum request for agents by all builds and the number of agents the license allows. SQL query name for `--filter` and `--order`: `agent_license_shortage`
agentsAvailable	The average number of enabled and active agents in the cluster over the specified time period. This value is available only for cluster statistics—it is not available for individual resource statistics. SQL query name for `--filter` and `--order`: `agents_available`
agentsInUse	The total number of agents assigned to builds. SQL query name for `--filter` and `--order`: `agents_in_use`
availableResults	This is a count of ’max’ or ’first’ results if `--maxResults` or `--firstResult` is specified. SQL query name for `--filter` and `--order`: N/A
buildsDuration	The average amount of time the current builds have been running. SQL query name for `--filter` and `--order`: `builds_duration`
buildsRunning	Average number of simultaneous builds running during a specific time period. SQL query name for `--filter` and `--order`: `builds_running`
createTime	The time when the item was created. SQL query name for `--filter` and `--order`: `create_time`
duration	The number of milli-seconds the build has been running. SQL query name for `--filter` and `--order`: `duration`
resourceName	This name is used on the eMake parameter: `--emake-resource`, and can be specified in a build class. It is used in the ea_resource table and also matches the resource requirement string for eMake. SQL query name for `--filter` and `--order`: `resource_name`
resourceStatId	The resource ID number that uniquely identifies every resource. SQL query name for `--filter` and `--order`: `id`

agentClusterShortage

How many additional agents could have been used by the builds over the specified time period. This value is filled in only for cluster statistics—it is not available for individual resource statistics. SQL query name for --filter and --order: agent_cluster_shortage

agentDemand

The average number of agents all builds could have used if those agents were available. For example, if two builds use two different resources and each build could use 15 agents, the cluster load shows an Agent Demand of 30 agents, and each resource shows 15. SQL query name for --filter and --order: agent_demand

agentLicenseShortage

The difference between the maximum request for agents by all builds and the number of agents the license allows. SQL query name for --filter and --order: agent_license_shortage

agentsAvailable

The average number of enabled and active agents in the cluster over the specified time period. This value is available only for cluster statistics—it is not available for individual resource statistics. SQL query name for --filter and --order: agents_available

agentsInUse

The total number of agents assigned to builds. SQL query name for --filter and --order: agents_in_use

availableResults

This is a count of ’max’ or ’first’ results if --maxResults or --firstResult is specified. SQL query name for --filter and --order: N/A

buildsDuration

The average amount of time the current builds have been running. SQL query name for --filter and --order: builds_duration

buildsRunning

Average number of simultaneous builds running during a specific time period. SQL query name for --filter and --order: builds_running

createTime

The time when the item was created. SQL query name for --filter and --order: create_time

duration

The number of milli-seconds the build has been running. SQL query name for --filter and --order: duration

resourceName

This name is used on the eMake parameter: --emake-resource, and can be specified in a build class. It is used in the ea_resource table and also matches the resource requirement string for eMake. SQL query name for --filter and --order: resource_name

resourceStatId

The resource ID number that uniquely identifies every resource. SQL query name for --filter and --order: id

Syntax

cmtool getResourceStats [optionals...]▼

Example

cmtool getResourceStats --maxResults 100 --order "id desc" --filter "resource_name=’Cluster’"▼

Retrieves the 100 most current resource statistic records for the entire cluster.

getServer

Retrieves server configuration.

Required arguments

None.

Optional arguments

None.

Result tags

Field	Description
agentAllocationPolicy	Defined as either exclusive or shared.
agentLockTimerSec	When jobs run beyond this number of seconds, the agent should be locked.
badAgents	The number of enabled agents with a bad status.
disabledAgents	The number of disabled agents.
emailInterval	The number of minutes between email notifications.
emailItemLimit	Maximum number of messages per email notification.
goodAgents	The number of enabled agents with a good status.
logDaysToKeep	The number of days to keep message log entries.
lsfAvailable	No longer used. False (0) is always returned.
mailFrom	The value to use in the From header element.
mailPrefix	The string used to prefix subject lines.
maxAgents	The maximum number of agents to request for this build.
maxClockSkew	The maximum clock skew (in seconds) allowed between the eMake client and agents in the cluster.
minAgents	The minimum number of agents required for this build to run.
preemptionPolicy	The allocation preemption policy.
priority	The build priority level. When assigning resources, an optional priority boost value can be selected to give a build class preference over other builds of the same priority level. Higher boost values correspond to greater preference.
resourceStatInterval	In minutes, the interval to collect stats on resource usage.
resourceStatKeep	The number of minutes of resource usage statistics to keep.
runningBuilds	The number of incomplete builds in the system.

Field

Description

agentAllocationPolicy

Defined as either exclusive or shared.

agentLockTimerSec

When jobs run beyond this number of seconds, the agent should be locked.

badAgents

The number of enabled agents with a bad status.

disabledAgents

The number of disabled agents.

emailInterval

The number of minutes between email notifications.

emailItemLimit

Maximum number of messages per email notification.

goodAgents

The number of enabled agents with a good status.

logDaysToKeep

The number of days to keep message log entries.

lsfAvailable

No longer used. False (0) is always returned.

mailFrom

The value to use in the From header element.

mailPrefix

The string used to prefix subject lines.

maxAgents

The maximum number of agents to request for this build.

maxClockSkew

The maximum clock skew (in seconds) allowed between the eMake client and agents in the cluster.

minAgents

The minimum number of agents required for this build to run.

preemptionPolicy

The allocation preemption policy.

priority

The build priority level. When assigning resources, an optional priority boost value can be selected to give a build class preference over other builds of the same priority level. Higher boost values correspond to greater preference.

resourceStatInterval

In minutes, the interval to collect stats on resource usage.

resourceStatKeep

The number of minutes of resource usage statistics to keep.

runningBuilds

The number of incomplete builds in the system.

Syntax

cmtool getServer▼

Example

cmtool getServer▼

getServerComments

Retrieves a list of related server comments.

Required arguments

None.

Optional arguments

Field	Description
commentId	The unique key that identifies a comment.

Field

Description

commentId

The unique key that identifies a comment.

Result tags

Field	Description
commentId	The unique key that identifies a comment.
createTime	The time when the item was created.
lastModifiedBy	The user who last modified the item.
modifyTime	The time when the item was last modified.
text	The text of the item.

Field

Description

commentId

The unique key that identifies a comment.

createTime

The time when the item was created.

lastModifiedBy

The user who last modified the item.

modifyTime

The time when the item was last modified.

text

The text of the item.

Syntax

cmtool getServerComments [optionals...]▼

Example

cmtool getServerComments▼

Returns all comments related to the server.

getVersion

Retrieves server version information.

Required arguments

None.

Optional arguments

None.

Result tags

Field	Description
label	The CloudBees build label for the server.
protocolVersion	The server protocol version.
schemaVersion	The server database schema version.
version	The string identifying a component version.

Field

Description

label

The CloudBees build label for the server.

protocolVersion

The server protocol version.

schemaVersion

The server database schema version.

version

The string identifying a component version.

Syntax

cmtool getVersion▼

Example

cmtool getVersion▼

importData

Imports Cluster Manager data from a file. This command imports a full database dump, which might take substantial time for a large database.

NOTE:

You must manually delete any old or unused agents from the agents list.
You must update the license file after importing it, if it has expired.
Manual migration using the exportData and importData commands is recommended only to replicate data between Cluster Manager instances running the same version of the Cluster Manager. For example, you could use it to make a backup dump and then restore it to a new instance of the Cluster Manager of the same version.
For a very large database, you should work with a database administrator to use the native database export/import facilities rather than using cmtool.

Required arguments

Field Description

Field	Description
fileName	Name of the file to import. The file path is relative to the current working directory of the Java process ( `/opt/ecloud/i686_Linux` or `C:\ECloud\i686_win32` by default).

fileName

Name of the file to import. The file path is relative to the current working directory of the Java process ( /opt/ecloud/i686_Linux or C:\ECloud\i686_win32 by default).

Optional arguments

None.

Syntax

cmtool importData <filename>▼

Example

cmtool importData fileabc▼

importLicenseData

Imports one or more licenses.

Required arguments

Field	Description
licenseFile	Name of the file containing the license with the path.

Field

Description

licenseFile

Name of the file containing the license with the path.

Optional arguments

None.

Syntax

cmtool importLicenseData <licenseFile>▼

Example

cmtool importLicenseData ./license.xml▼

logMessage

Creates a custom message on the Cluster Manager Messages page.

Required arguments

Field	Description
text	Message text.

Field

Description

text

Message text.

Optional arguments

If --buildId and --agentName are on the same line, the message is applied to the build and the agent name.

Field	Description
severity	Can be Debug, Info, Warning, or Error. You can also use 0, 1, 2, or 3.
buildId	The message applies to this specified build only.
agentName	The message applies to this specified agent name only.

Field

Description

severity

Can be Debug, Info, Warning, or Error. You can also use 0, 1, 2, or 3.

buildId

The message applies to this specified build only.

agentName

The message applies to this specified agent name only.

Syntax

cmtool logMessage <text> [optionals...]▼

Example

cmtool logMessage "some text"▼

modifyServer

Modifies the server configuration.

Required arguments

None.

Optional arguments

Field Description

Field	Description
priority	The default priority value is 120 (normal). 220 is high and 20 is low. Priority value can be adjusted up or down by 1-10 to “boost” the priority to give certain build classes preference over other builds of the same priority level. Higher boost values correspond to greater preference.
emailInterval	The number of minutes between email notifications.
emailItemLimit	The maximum number of messages per email notification.
agentAllocationPolicy	Can be exclusive or shared. Exclusive means all agents on a specific machine are assigned to the same build. Shared means all agents on the same machine can be assigned to different builds. This policy requires that eMake client and agent machines have synchronized clocks.
wideDeepAllocationPolicy	Can be deep or wide. Deep means the agent allocation algorithm favors assigning more agents on the same host to a build. Wide means the algorithm favors assigning more agents from different hosts. If wide, be sure `--agentAllocationPolicy` is set to shared.
preemptionPolicy	The allocation preemption policy.
maxClockSkew	The maximum clock skew (in seconds) allowed between the eMake client and agents in the cluster.
maxAgents	The maximum number of agents to request for this build.
minAgents	The minimum number of agents required for this build to run.
mailFrom	The value to use in the From header element.
mailPrefix	The string used to prefix subject lines.
logDaysToKeep	The number of days to keep message log entries.
resourceStatInterval	In minute units, this is the interval to collect statistics on resource usage.
resourceStatKeep	The number of days of Resource usage statistics to keep.
agentLockTimerSec	The number of seconds an agent is locked from being taken by another build. This interval provides a buffer so the current build can perform any housekeeping tasks before being taken over by a subsequent build.
reportUsage	Flag to control whether the cluster manager reports build performance metrics to CloudBees. If true, metrics are reported.
buildAccessLimited	Flag to control whether access to build information is limited to the owner of the build and the administrator only. If true, build information is limited.
serverIpAddress	The IP address of the Cluster Manager server used for agent connection during cloud bursting.

priority

The default priority value is 120 (normal). 220 is high and 20 is low. Priority value can be adjusted up or down by 1-10 to “boost” the priority to give certain build classes preference over other builds of the same priority level. Higher boost values correspond to greater preference.

emailInterval

The number of minutes between email notifications.

emailItemLimit

The maximum number of messages per email notification.

agentAllocationPolicy

Can be exclusive or shared. Exclusive means all agents on a specific machine are assigned to the same build. Shared means all agents on the same machine can be assigned to different builds. This policy requires that eMake client and agent machines have synchronized clocks.

wideDeepAllocationPolicy

Can be deep or wide. Deep means the agent allocation algorithm favors assigning more agents on the same host to a build. Wide means the algorithm favors assigning more agents from different hosts. If wide, be sure --agentAllocationPolicy is set to shared.

preemptionPolicy

The allocation preemption policy.

maxClockSkew

The maximum clock skew (in seconds) allowed between the eMake client and agents in the cluster.

maxAgents

The maximum number of agents to request for this build.

minAgents

The minimum number of agents required for this build to run.

mailFrom

The value to use in the From header element.

mailPrefix

The string used to prefix subject lines.

logDaysToKeep

The number of days to keep message log entries.

resourceStatInterval

In minute units, this is the interval to collect statistics on resource usage.

resourceStatKeep

The number of days of Resource usage statistics to keep.

agentLockTimerSec

The number of seconds an agent is locked from being taken by another build. This interval provides a buffer so the current build can perform any housekeeping tasks before being taken over by a subsequent build.

reportUsage

Flag to control whether the cluster manager reports build performance metrics to CloudBees. If true, metrics are reported.

buildAccessLimited

Flag to control whether access to build information is limited to the owner of the build and the administrator only. If true, build information is limited.

serverIpAddress

The IP address of the Cluster Manager server used for agent connection during cloud bursting.

Syntax

cmtool modifyServer [optionals...]▼

Example

cmtool modifyServer --mailFrom "cm@ourhost.com" --mailPrefix "cm message:"▼

Changes the mail “from” and mail prefix values used for mail notifications sent by the server.

modifyServerComment

Modifies a server comment.

Required arguments

Field	Description
commentI	The unique key that identifies a comment.
text	The comment text.

Field

Description

commentI

The unique key that identifies a comment.

text

The comment text.

Optional arguments

None.

Syntax

cmtool modifyServerComment <commentId> <text>▼

Example

cmtool modifyServerComment 1178 "Server is fine"▼

shutdownServer

Stops the server.

Use with caution.

Required arguments

None.

Optional arguments

Field	Description
restart	Restart the server. Can be true or false.

Field

Description

restart

Restart the server. Can be true or false.

Syntax

cmtool shutdownServer [optionals...]▼

Example

cmtool shutdownServer▼

testAgents

Instructs the Cluster Manager to contact each active agent and update its status.

Required arguments

None.

Optional arguments

Field	Description
agentId	A unique, internal number that can change; assigned by the Cluster Manager.
agentName	The name defined by the host where the agent resides (numbers and/or letters).
filter	A SQL query used to limit the result set. For a list of possible SQL values, see the getAgents command.

Field

Description

agentId

A unique, internal number that can change; assigned by the Cluster Manager.

agentName

The name defined by the host where the agent resides (numbers and/or letters).

filter

A SQL query used to limit the result set. For a list of possible SQL values, see the getAgents command.

Syntax

cmtool testAgents [optionals...]▼

Example

cmtool testAgents --filter "agent_name like ’%bl%’"▼

This command contacts all agents whose name contains bl and updates their status.