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

text

Description: 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

productName

Description: The name of the license, which is ElectricAccelerator.

featureName

Description: 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

messageId

Description: 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

filter

Description: 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

commentId

Description: 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

fileName

Description: 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

productName

Description: The name of the license, which is ElectricAccelerator.

featureName

Description: 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

messageId

Description: 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

filter

Description: 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

Description: The maximum number of elements to return from a query.

firstResult

Description: 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

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

profile

Description: 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

agentId

Description: 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

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

buildId

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

buildName

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

createTime

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

messageId

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

severity

Description: 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

Description: 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

filter

Description: 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

Description: The maximum number of elements to return from a query.

firstResult

Description: 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

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

profile

Description: 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

agentClusterShortage

Description: 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

Description: 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

Description: 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

Description: 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

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

availableResults

Description: 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

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

buildsRunning

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

createTime

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

duration

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

resourceName

Description: 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

Description: 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

agentAllocationPolicy

Description: Defined as either exclusive or shared.

agentLockTimerSec

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

badAgents

Description: The number of enabled agents with a bad status.

disabledAgents

Description: The number of disabled agents.

emailInterval

Description: The number of minutes between email notifications.

emailItemLimit

Description: Maximum number of messages per email notification.

goodAgents

Description: The number of enabled agents with a good status.

logDaysToKeep

Description: The number of days to keep message log entries.

lsfAvailable

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

mailFrom

Description: The value to use in the From header element.

mailPrefix

Description: The string used to prefix subject lines.

maxAgents

Description: The maximum number of agents to request for this build.

maxClockSkew

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

minAgents

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

preemptionPolicy

Description: The allocation preemption policy.

priority

Description: 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

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

resourceStatKeep

Description: The number of minutes of resource usage statistics to keep.

runningBuilds

Description: 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

commentId

Description: The unique key that identifies a comment.

Result Tags

commentId

Description: The unique key that identifies a comment.

createTime

Description: The time when the item was created.

lastModifiedBy

Description: The user who last modified the item.

modifyTime

Description: The time when the item was last modified.

text

Description: 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

label

Description: The CloudBees build label for the server.

protocolVersion

Description: The server protocol version.

schemaVersion

Description: The server database schema version.

version

Description: 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

fileName

Description: 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

licenseFile

Description: 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

text

Description: Message text.

Optional Arguments

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

severity

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

buildId

Description: The message applies to this specified build only.

agentName

Description: 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

priority

Description: 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

Description: The number of minutes between email notifications.

emailItemLimit

Description: The maximum number of messages per email notification.

agentAllocationPolicy

Description: 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

Description: 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

Description: The allocation preemption policy.

maxClockSkew

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

maxAgents

Description: The maximum number of agents to request for this build.

minAgents

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

mailFrom

Description: The value to use in the From header element.

mailPrefix

Description: The string used to prefix subject lines.

logDaysToKeep

Description: The number of days to keep message log entries.

resourceStatInterval

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

resourceStatKeep

Description: The number of days of Resource usage statistics to keep.

agentLockTimerSec

Description: 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

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

buildAccessLimited

Description: 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

Description: 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

commentId

Description: The unique key that identifies a comment.

text

Description: 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

restart

Description: 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

agentId

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

agentName

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

filter

Description: 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.