Job configuration overlays reference
You can specify or change configuration parameters when you use the
submitjob
or updateoperators
operations. The settings control
submission constraints, host constraints and locations, and operator status. Parameters are captured
and updated in the configuration JSON file. When you change the values in the job configuration overlay file, the changes override any previously set values.
A value that you set in a job configuration overlay file will override any corresponding value provided by a submission-time parameter or a corresponding value provided in the application. If your application requires submission-time values, you must still set those values in the application, even though they will be overridden.
Job parameters format
The following categories classify parameters as input or output related:
AttributeName | Type | Value |
---|---|---|
comment (optional) | String | Comment text. |
jobConfigOverlays (optional) | Array JobConfigOverlay | Each element of the array contains the job configuration settings. Only the first jobConfigOverlay element is supported. Other elements in the array are ignored. |
results (optional) | Results | Produced from the submitjob --preview command or from the updateoperators command. This parameter is output only and is ignored for job preview, update, or submission. Results can be successful, partially successful, or failure. |
- jobConfigOverlays
- Single element array of jobConfigOverlays.
- Results
-
Output from the submitjob --preview command or the updateoperators command. This parameter is output only and it is ignored for job preview, update, or submission. For parameters, see Results.
JobConfigOverlay
The following parameters define the contents of the job configuration overlay:
AttributeName | Type | Value | Operation |
---|---|---|---|
jobConfig (optional) | Object JobConfig | Job configuration values | submitjob |
deploymentConfig (optional) | Object DeploymentConfig | Deployment configuration values. | submitjob |
operatorConfigs (optional) Ignored when fusionScheme=legacy. |
Object OperatorConfigs | Operator configuration values. | submitjob |
configInstructions (optional) | Object ConfigInstructions | Configuration instructions. | submitjob
|
operationConfig (optional) | Object OperationConfig | Operation configuration values. | submitjob
|
JobConfig
The following parameters define the contents of the job configuration:
AttributeName | Type | Value | Operation |
---|---|---|---|
jobName (optional) | String | The name that is assigned to the job. | submitjob |
jobGroup (optional) | String | The job group to use to control the permissions for the submitted job. | submitjob |
submissionParameters (optional) | Array SubmissionParameter | Job-specific key: value submission parameters. | submitjob |
dataDirectory (optional) | String | Specifies the location of the data directory. | submitjob |
preloadApplicationBundles (optional) | Boolean | Specifies whether to preload the job onto all resources in the instance, even
if the job is not currently needed on each. Values are Preloading the job can improve the performance if the PEs are relocated to a new resource. |
submitjob |
tracing (optional) | String | Specifies the trace setting for the PEs. The valid values are
error , warn , info , debug , and
trace . |
submitjob |
SubmissionParameter
The following elements comprise the submission parameters:
AttributeName | Type | Value | Operation |
---|---|---|---|
name | String | Parameter name. | submitjob |
value | String | Parameter value. | submitjob |
Operation Config
The following elements comprise the contents of the operation configuration:
AttributeName | Type | Value | Operation |
---|---|---|---|
overrideResourceLoadProtection (optional) | Boolean | False : (default). The instance property setting for resource
overload protections will be used.
Note: You must have jobs-override authority on the instance object to use this option. |
submitjob |
forcePeStopped (optional) | Boolean | True : If a currently running PE is required to be stopped by
the operation, this operation will stop the PE.
|
updateoperators |
enableAutomaticAugmentation (optional) | Boolean | True : Resources are added automatically as needed to
minimally solve resource placement problems.
|
updateoperators |
DeploymentConfig
The following elements comprise the contents of the deployment configuration:
AttributeName | Type | Value | Operation |
---|---|---|---|
fusionScheme (optional) | String |
|
submitjob |
fusionTargetPeCount (optional) Requires fusionScheme=manual or instance.fusionScheme=manual. |
Number | Use this option to set the number of PEs to create.
fusionScheme must be set to manual . |
submitjob |
placementScheme (optional) | String |
For both balanced schemes, the balancing pass selects the candidate host that has the lowest PE to core ratio. If there is a tie, the balancing process chooses the host with the lowest load. |
submitjob |
threadingModel (optional) | String |
|
submitjob |
dynamicThreadingThreadCount (optional) | Number | Specifies the number of threads that scheduled ports should use. Inherits its value from instance.dynamicThreadingThreadCount, if set. | submitjob |
dynamicThreadingElastic (optional) | Boolean | Specifies whether the number of dynamic threads as well as
the number of operators under the dynamic threading model can change at runtime to maximize
throughput. Specify true to make elastic adjustment or
false to keep the number of dynamic threads and the number of operators under
the dynamic threading model static.
Note: This setting can only be used if the application configuration
threadingModel is set to dynamic . |
submitjob |
parallelRegionConfig (optional) Ignored if fusionScheme=legacy. |
Object parallelRegionConfig | Configuration information for all the parallel regions in the job. | submitjob |
jobResourceSharing
(optional) If not specified, the instance.jobResourceSharing property value is used. |
String | sameJob : Job resources are only allowed to be used within
this job.
|
submitjob |
proposedOperatorsPerResource (optional) | Integer greater than 0. | Ratio of the number of operators per resource. This ratio is a suggestion to
the scheduler to influence the number of resources that are requested to support the job's resource
needs. The default is the value of the instance.proposedOperatorsPerResource property. |
submitjob |
parallelRegionConfig
The following elements comprise the submission parameters:
AttributeName | Type | Value | Operation |
---|---|---|---|
fusionType | String |
|
submitjob |
OperatorConfigs
The following parameters define the contents of the operator configurations:
AttributeName | Type | Value | Operation |
---|---|---|---|
operators (optional) | Array Operator | Configuration attributes for individual operators. Not all existing operators
must be in the array, but only operators defined by the application are allowed. If an operator is referenced multiple times, the configuration updates are made one at a time in the order that they appear in the JSON file. The resulting configuration will be cumulative from the application of all the configurations. |
submitjob |
hostColocationGroups (optional) | Array LocationGroup | Each element of the array represents a hostColocationGroup, where each member of the group must be placed onto the same host as other operators in this group. These groups are combined with groups that are defined in the application bundle. | submitjob |
hostExlocationGroups (optional) | Array LocationGroup | Each element of the array represents a hostExlocationGroup, where each member of the group cannot be placed onto the same host as any other operators in this group. These groups are combined with groups that are defined in the application bundle. | submitjob |
partitionColocationGroups (optional) | Array LocationGroup | Each element of the array represents a partitionColocationGroup, where each member of the group must be fused together with other operators in the group into the same PE. These groups are combined with groups that are defined in the application bundle. | submitjob |
partitionExlocationGroups (optional) | Array LocationGroup | Each element of the array represents a partitionExlocationGroup, where each member of this group cannot be fused together with any other operators from this group into the same PE. These groups are combined with groups that are defined in the application bundle. | submitjob |
poolPlacementGroups (optional) | Array PoolPlacementGroup | Each element of the array represents a host pool definition. | submitjob |
LocationGroup
The following parameters define the location groups:
AttributeName | Type | Value | Operation |
---|---|---|---|
groupName (optional) | String | Name of a location group. | submitjob : If this name matches the name of a group that is
defined in the application bundle, this group replaces the group in the
bundle.
|
members (optional) | Array String | Each element of the array is a nameSpec of the operator or operators that are included in this group. If this attribute is not specified, or the array is empty, then a group with a matching groupName that is defined in the application bundle is removed. | submitjob
|
PoolPlacementGroup
The following parameters define the details for pool placement groups:
AttributeName | Type | Value | Operation |
---|---|---|---|
name (optional) | String | Name of the host pool. For the |
submitjob |
operatorsInPool (optional) | Array OperatorInPool | A specific operator can be specified in only one PoolPlacementGroup or in the declaredHost attribute of the Operator. | submitjob |
membershipMode (optional) | String | SHARED : (default). Hosts that are members of this pool are
allowed to be in other pools as well.
|
submitjob |
size (optional) | Number | Optional number. Defines the number of hosts that are allowed in the host
pool. If specified, the number must be greater than 0. If declaredHosts size is greater than 0, then the value that is specified for size is ignored. |
submitjob |
tags (optional) Exclusive with declaredHosts |
Array String | Defines what the tagging requirements are for hosts to be considered for membership of this pool. | submitjob |
declaredHosts (optional) Exclusive with the following:
Not allowed if applicationResourceAllocationMode=job. |
Array String | Defined hosts that are members of this host pool. | submitjob |
numberOfResourcesToRequest (optional)
Exclusive with declaredHosts. |
Number | The submitjob operation will request this number of resources
that match the requirements for the poolPlacementGroup parameter. If operators
with different poolPlacementGroups are partition colocated together, the
largest number for this field will be used. |
submitjob |
OperatorInPool
The following parameters define the operator pools:
AttributeName | Type | Value | Operation |
---|---|---|---|
nameSpec | String | nameSpec of the operators in the pool. | submitjob |
inPoolIndex (optional) | Number | Optional number. The index within the host pool, for example, the fourth host listed in the host pool. This value can be specified only as part of a PoolPlacementGroup that has a size specified. The index number must be smaller than the specified size. | submitjob |
Operator
The following parameters define the details for operator configuration:
AttributeName | Type | Value | Operation |
---|---|---|---|
nameSpec | String | Specification of a name of an existing operator instance or
instances in an application after User defined parallelism (UDP)
transformations. The name might contain zero or more '*' characters in the specification. The '*' represents 0 or more occurrences of any legal name character. For example, "Main.*.MyComp2.Filter[*]" '[ ]' are normal characters, and do not have any regular expression meaning. |
submitjob |
restartable (optional) | Boolean | true : A PE that contains this operator is able to be
restarted. If you set the value to true , it will not be specified
in the preview output.
If you specify this parameter, it will override the currently active value. |
submitjob |
relocatable (optional) | Boolean | true : A PE that contains this operator is able to be
relocated. If you set the value to true , it will not be specified
in the preview output.
If you specify this parameter, it will override the currently active value. |
submitjob |
partitionIsolation (optional) | Boolean | true : A PE that contains this operator cannot be fused with
any other operator.
If you specify this parameter, it will override the currently active value. |
submitjob |
partitionGroupIsolation (optional) | Boolean | true : The only operators that are allowed to be fused with
this operator or those that have been configured with partitionColocation placement with
it.
If you specify this parameter, it will override the currently active value. |
submitjob |
hostIsolation (optional) | Boolean | true : A PE that contains this operator cannot be placed on
the same host as any other PE.
If you specify this parameter, it will override the currently active value. |
submitjob |
declaredHost (optional) Not allowed if applicationResourceAllocationMode=job). |
String | A PE that contains this operator must be placed on this specific host. If this
attribute is specified, then the operator cannot be included in any of the
PoolPlacement sections. If you specify this parameter, it will override the currently active value. |
submitjob |
ConfigInstructions
The following parameters define the details for the configuration instructions:
AttributeName | Type | Value | Operation |
---|---|---|---|
ignoreBundleRelationalPlacements (optional) Ignored when fusionScheme=legacy. |
String | PARTITION : Clear all
current partition relational placements from bundle (partitionIsolation,
partitionColocationGroups,
partitionExlocationGroups).
Tip: Be careful when you use this keyword because the effects can counteract the
intentions of the application developer.
|
submitjob |
ignoreBundleHostPlacements (optional) Ignored when fusionScheme=legacy. |
Boolean | true : All operators are placed in the default pool.
(default=false )Tip: Be careful when you use this keyword because the effects can counteract the
intentions of the application developer.
|
submitjob |
convertTagSet (optional) | Array tagConversion | Replace tags in the poolPlacementGroups with tags in the
convertTagSet. If poolPlacementGroup.tags is a superset of originalTagSet, then tags in originalTagSet are removed from poolPlacementGroup.tags, and tags in targetTagSet are inserted in its place. If the originalTagSet is not specified, then a poolPlacementGroup with an empty tag set, known as a default host pool, has its tags changed to include targetTagSet. The parameter does not convert tags within the jobConfigOverlay. |
submitjob |
changeThreadedPortSettings (optional) | Object ThreadedPortSetting | Change settings for all threaded ports that are defined in the application. | submitjob |
adjustmentSection (optional) | Array AdjustmentSubsection | Adjustment section definition. The operator set that makes up the adjustment section of the job is defined by the union of the composite set of operators of all the subsections. The composite set of operators for each subsection is defined by the union of the target operators and the operator sets that make up the target PEs. |
submitjob : Multiple sections are
supported.
|
AdjustmentSubsection
The following parameters define the adjustment subsection:
AttributeName | Type | Value | Operation |
---|---|---|---|
targetParallelRegion (optional) | object TargetParallelRegion | Parallel region to be targeted. | submitjob
|
numberOfResourcesToBeAdded (optional) Ignored during
the |
Number | Number of resources to be added to job. The tagging requirement for the resources is defined by the tagsForAddedResources parameter. If the tagsForAddedResources parameter is not specified, then an untagged request will be made. Ignored if the width of the parallel region is not increased. |
updateoperators |
tagsForAddedResources (optional) Ignored if numberOfResourcesToBeAdded is not specified. |
Array string | Defines the tagging requirements for the hosts to be added. An empty tag array is supported. |
updateoperators |
TargetParallelRegion
The following parameters define the target parallel region:
AttributeName | Type | Value | Operation |
---|---|---|---|
regionName | NameSpec | Name of parallel region. The parallel region name is the logical name of the
operator that the @parallel annotation was applied to. The asterisk
( |
submitjob
Important: Changes to the width of multiple parallel regions at once is supported only for a
submitjob operation. For an updateoperators operation, only one
width change at a time is allowed. (You cannot change multiple widths of a running
job.) |
newWidth (optional) | Number | New width for parallel region. If the new width is same as current, then no
adjustment is performed. The new width must be greater than 0. The fusionType
parameter must be set to |
submitjob
|
ThreadedPortSetting
The following parameter defines the threaded port settings:
AttributeName | Type | Value | Operation |
---|---|---|---|
queueSize | Number | Size of threaded port queue. Must be greater than or equal to 1. | submitjob |
TagConversion
The following parameters define the tag conversion:
AttributeName | Type | Value | Operation |
---|---|---|---|
originalTagSet (optional) | Array String | An array of strings that represent a list of tags to convert from. | submitjob |
targetTagSet | Array String | An array of strings that represent a list of tags to convert to. | submitjob |
OriginalTagSet | TargetTagSet | poolPlacementGroupTags Before | poolPlacementGroupTags After | Notes |
---|---|---|---|---|
"A" | "X" | "A,B" | "X,B" | One to one |
"A" | "X,Y" | "A,B" | "X,Y,B" | One to many |
"A,B" | "Y" | "A,B,C" | "Y,C" | Many to one |
"A,B" | "W,Y,Z" | "A,B,C" | "W,Y,Z,C" | Many to many |
"A,B" | "Z" | "A,C,D" Not a superset; missing B. |
"A,C,D" | No change, since not all tags exist in the "Before" set |
" " | "X,Y" | " " | "X,Y" | Adding tags to default host pool. |
Results
The following parameters define the submission results. These parameters are output only and are ignored on input:
AttributeName | Type | Value |
---|---|---|
placementResults (optional) | Array PlacementResult | Each element of the array describes a resulting PE. This field is not specified if fusionErrors occur, but is specified if only placementErrors occur. |
fusionErrors (optional) | Array FusionError | Each element of the array provides information on errors that occurred while the system is trying to fuse operators into a PE. |
placementErrors (optional) | Array PlacementError | Each element of the array provides information on errors that occurred while the system is trying to place a PE onto a host. |
jobResources (optional) | Array ResourceConfig | Each element describes a resource that is being used by an operator in the target parallel region, a PE in the target parallel region, or by a collateral operator. Collateral operators are operators that have a relationship with the operators in the targeted parallel region. The collateral operators are either fused in same PE as a target operator or they connect with the targeted parallel region with a splitter or a merger. |
collateralOperators (optional) | Array String | Names of the collateral operators that are affected by the
updateoperators operation. Collateral operators are operators that have a
relationship with the operators in the targeted parallel region. The collateral operators are either
fused in same PE as a target operator or they connect with the targeted parallel region with a
splitter or a merger. |
parallelRegionsInfo (optional) | Array ParallelRegionInfo | Each element provides information on a parallel region defined in the job. |
deploymentConfig (optional) | Object DeploymentConfig | The deployment config information that is active for this job. |
PlacementResult
If the fusion phase completes successfully, a placementResults
element is returned whether the placementPhase was successful or not. If the
placement phase fails, the hostPlacement field is not set. This partial return
is useful if you want to use submitjob --preview
to get feedback on the fusing
phase before you have your test instance fully configured.
AttributeName | Type | Value |
---|---|---|
peId (optional) | Number | PE identifier. |
names | Array String | Names of the operators to fuse together into this PE. |
tags (optional) | Array String | The host placement tags that are associated with this fused PE. |
declaredHosts (optional) | Array String | Any declared host that this PE is associated with. |
hostPlacement (optional) | String | The target host for PE placement if the job was submitted. If
placementPhase is not successful, then this field is not set. Since the
current runtime situation is temporal and affects the host selection, this
hostPlacement might not be the same for subsequent |
ResourceConfig
AttributeName | Type | Value |
---|---|---|
resourceId | String | ID of the resource. |
numberOfCores | Number | Number of CPU cores in the resource. |
amountOfMemory | Number | Number of megabytes of memory in the resource. |
networkBandwidth | Number | Number of kilobytes per second that are supported in the resource. |
tags | Array String | Each element is a tag identifier that is assigned to the resource. |
FusionError
The FusionError information describes the set of operators that were intended to be fused together, as well as what factors might have prevented successful fusion.
AttributeName | Type | Value |
---|---|---|
operatorNames | Array String | Names of operators that were not successfully fused. |
detailedProblemMessages | Array Message | Messages that describe in detail the problems that were detected that
prevented successful fusion. The messages are scoped to the collection of operators and not to a
single operator. For example: CDISR3203E One or more of the operators are specified as partitionIsolate which prohibits from being fused with any other operator. CDISR3210E Different indexes [0, 1] within the 0 host pool were specified by the operators. |
PlacementError
The PE placement process is hierarchical in nature. A job contains one or more PE colocation groups. A PE colocation group contains one or more PEs. A PE contains one or more operators. The placement process cycles through various constraints to arrive at a candidate host set for each placementNode. If the host set is empty, that node in the placement tree cannot be placed.
The error messages are also hierarchical. In the previously described scenario, the reported error is not the last constraint that makes the set empty, but rather a composite message structure that describes the bigger picture of what causes the failure. At each node in the placement tree, there can be constraints that nominate or eliminate hosts to the candidate host set.
For example, each child node of a node nominates its candidate host set to its parent's candidate set. The parent node eliminates all hosts from its candidate set that are not included in each of its child's candidate set. That is, the parent set starts with the intersection of all child sets.
AttributeName | Type | Value |
---|---|---|
placementNodeInfo | PlacementNodeInfo | Contains information about the overall status of the placement node, including whether the node is able to be successfully placed. |
contributingMessages | Array Message | A set of messages that describe the contributions that produce the resulting
placementNodeInfo status. Some contributing messages describe why a set of hosts is nominated to the
candidate set, for example: CDISR3051I The following hosts were included in the scheduling process because the hosts are eligible to be included in the MyHostPool host pool by having the following host pool tags. The hosts are: 10.4.24.226, 10.4.40.236. The host pool tags that are shared by the hosts are: [Red,Blue]. Some contributing messages describe why a set of hosts is eliminated from the candidate set, for example: CDISR3066I: Because the following hosts are not supported by all the operators in the partition, these hosts cannot be included in the scheduling process: 10.4.24.226, 10.4.40.247. |
childContributions (optional) | Array PlacementError | A set of placement errors that detail how the child placement nodes contribute to these placement node results. |
PlacementNodeInfo
AttributeName | Type | Value |
---|---|---|
success | Boolean | If the value is true , this node has at least one valid
candidate host.If the value is |
name (optional) | String | If present, the placement node is related to the operator that is named by this parameter. |
peId (optional) | String | If present, the placement node is related to a PE. The peOperatorSet field contains the related operator name set for this PE. |
peOperatorSet (optional) | Array String | If present, the placement node is related to a PE, and this is the set of operator names that make up the PE. The ID for this PE is specified in the peID field. |
colocatedPeSet (optional) | Array String | If present, this placement node is related to a colocated set of PEs. This parameter expresses the array of PE IDs as a string. |
placementMessage | Message | A message that describes the placement status for this placement node. For
example: CDISR3046E The processing element ID 3: op1 cannot be scheduled. For more information, see the messages that follow this one. CDISR3047I: A constraint on the op1 operator requires that it be scheduled from the following hosts: 10.4.24.226, 10.4.40.236.. For more information, see the messages that follow this one. |
Message
AttributeName | Type | Value |
---|---|---|
messageCode | String | The code for the message, for example, CDISR3200E. |
substitutionTexts (optional) | Array String | The substitution text string for the message. |
displayMessage (optional) | String | Human readable display message with substitutionTexts inserted and
instantiated by the client in the client locale. This field is transient and is included to improve the readability of error messages in the JSON file. |
ParallelRegionInfo
AttributeName | Type | Value |
---|---|---|
name | String | Name of the parallel region. |
width | Number | Width of parallel region after an updateoperators operation.
In preview mode, it shows the value as if the updates were actually done. |