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.

Important: When you set a value in the job configuration overlay file, you might override application configuration settings that the application developer defined and the changes can potentially conflict with the application developer's intention.

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

updateoperators

operationConfig (optional) Object OperationConfig Operation configuration values. submitjob

updateoperators

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 true or false (default).

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.

True: Resource overload protection is disabled for this job submission.

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.

False: (default). If a PE is required to stop, but it is not stopped, then the operation will fail.

updateoperators
enableAutomaticAugmentation (optional) Boolean True: Resources are added automatically as needed to minimally solve resource placement problems.

False: (default). Resources are not added automatically, regardless of placement problems.

updateoperators

DeploymentConfig

The following elements comprise the contents of the deployment configuration:

AttributeName Type Value Operation
fusionScheme (optional) String
  • automatic: (default). At submission time, Teracloud® Streams decides on a number of PEs that are appropriate to the job and the instance.
  • manual: At submission time, the user must provide a target number of PEs for each job.
  • legacy: At submission time, Teracloud® Streams uses the fusion behavior from prior to Version 4.2.0.
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
  • legacy: The estimated load of PEs to be placed is fitted in with existing ldavg numbers of hosts, adjusted for the number of cores in hosts.
  • balancedJob: PEs are distributed across candidate hosts proportionally to the number of cores on the hosts. PEs from previous jobs are ignored.
  • balancedInstance: (default). PEs are distributed across candidate hosts proportionally to the number of cores on the hosts, taking into account PE placements from previous jobs.

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
  • manual: Threads are manually placed by the application developer. All threads come from either operators, explicitly requested threaded ports, or PE input ports.
  • automatic: The SPL runtime decides on thread placement based on runtime information like necessary threads, number of operators that are available in the PE, and number of available logical processors.
  • dynamic: Each operator input port can be executed by any thread. The assignment of threads to input ports can change at runtime as can the number of available threads.
  • dedicated: Each operator input port has a dedicated thread that processes all of the tuples on that input port, regardless of whether or not those operators have the threadedPort configuration.
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.

sameUser: If unused resources are not available, job resources are allowed to be shared by other jobs from the same user that are also specified as sameUser sharing.

sameInstance: If unused resources are not available, job resources are allowed to be shared by other jobs from the same instance that are also specified as sameInstance sharing.

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
  • channelIsolation: Operators within a channel are fused into a PE only with operators from the same channel. Operators outside the parallel region or from other channels in the same region are fused into different PEs. One or more PEs for a channel can be created depending on the fusion constraints.

    You can explicitly collocate an operator in a channel with an operator outside the region or from a different channel in the same region. A separate PE is created if all of the explicitly colocated operators are not members of the same channel.

  • channelExlocation: Operators within a channel are fused with operators from the same channel or with operators from outside the region. Operators from other channels in the same region are not fused into the same PEs. One or more PEs for a channel can be created depending on the fusion constraints.

    You can explicitly collocate an operator in a channel with an operator outside the region or from a different channel in the same region. A separate PE is created if all of the explicitly colocated operators are not members of the same channel.

    If you use this value, you cannot change the width of a parallel region while the job is running. You would need to resubmit the job with the value set to channelIsolation or to noChannelInfluence.

  • noChannelInfluence: (default). Inclusion in this parallelRegion has no impact on the fusion process.
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.

updateoperators: If this name matches the name of an existing group, it will replace it. All current members of the group must be included in the target zone, or an error is reported.

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

updateoperators

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 operation: If this name matches the name of a group that is defined in the application bundle, this group replaces the group in the bundle.

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.

EXCLUSIVE: Hosts that are members of this pool are not allowed to be in any other pools, whether this job or any other jobs. The value for size must be specified.

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:
  • tags
  • membershipMode=Exclusive
  • numberOfResourcesToRequest

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.

false: A PE that contains this operator is not able to be restarted.

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.

false: A PE that contains this operator is not able to be relocated.

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.

false: A PE that contains this operator can be fused with other operators. If you set the value to false, it will not be specified in the preview output.

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.

false: No additional restrictions to what operators this operator can be fused with. If you set the value to false, it will not be specified in the preview output.

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.

false: A PE that contains this operator can be placed on the same host with other PEs. If you set the value to false, it will not be specified in the preview output.

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).

HOST: Clear all current host relational placements from bundle (hostIsolation, hostColocationGroups, hostExlocationGroups).

ALL: Clear partition and host relational placements.

NONE: (default). Bundle relational placements are left as is.

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.

updateoperators: Multiple sections are supported, but only one parallel region can be specified.

AdjustmentSubsection

The following parameters define the adjustment subsection:

AttributeName Type Value Operation
targetParallelRegion (optional) object TargetParallelRegion Parallel region to be targeted. submitjob

updateoperators

numberOfResourcesToBeAdded (optional)

Ignored during the submitjob operation.

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 (*) wildcard character is supported, except when the wildcard character resolves to multiple parallel regions. Ensure that any regular expression you use applies to only one level of a nested parallel region. For more information, see Nested parallel regions.

submitjob

updateoperators

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 noChannelInfluence or to channelIsolation.

submitjob

updateoperators

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
For complex transformation for tagging definitions that go beyond a one-to-one transformation, you can define a convertTagSet:
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 submitjob operations.

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 false, there are no candidate hosts remaining for this placementNode, and placement fails for this node.

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.