Interface: CompiledWorkerOptions
worker.CompiledWorkerOptions
WorkerOptions where the attributes the Worker requires are required and time units are converted from ms formatted strings to numbers.
Hierarchyâ
-
Omit
<WorkerOptionsWithDefaults
,"serverOptions"
|"interceptors"
|"activities"
|"tuner"
>âŗ
CompiledWorkerOptions
Propertiesâ
activitiesâ
âĸ activities: Map
<string
, ActivityFunction
<any
[], any
>>
buildIdâ
âĸ Optional
buildId: string
A string that should be unique to the exact worker code/binary being executed.
This is used to uniquely identify the worker's code for a handful of purposes, including the
worker versioning feature if you have opted into that with
WorkerOptions.useVersioning. It will also populate the binaryChecksum
field
on older servers.
âšī¸ Required if useVersioning is true
.
â ī¸ NOTE: When used with versioning, you must pass this build ID to updateBuildIdCompatibility. Otherwise, this Worker will not pick up any tasks.
Default
@temporalio/worker
package name and version + checksum of workflow bundle's code
Inherited fromâ
Omit.buildId
bundlerOptionsâ
âĸ Optional
bundlerOptions: Object
Type declarationâ
Name | Type | Description |
---|---|---|
ignoreModules? | string [] | List of modules to be excluded from the Workflows bundle. Use this option when your Workflow code references an import that cannot be used in isolation, e.g. a Node.js built-in module. Modules listed here MUST not be used at runtime. > NOTE: This is an advanced option that should be used with care. |
webpackConfigHook? | (config : Configuration ) => Configuration | Before Workflow code is bundled with Webpack, webpackConfigHook is called with the Webpack configuration object so you can modify it. |
Inherited fromâ
Omit.bundlerOptions
connectionâ
âĸ Optional
connection: NativeConnection
A connected NativeConnection instance.
If not provided, the worker will default to connect insecurely to localhost:7233
.
Inherited fromâ
Omit.connection
dataConverterâ
âĸ Optional
dataConverter: DataConverter
Provide a custom DataConverter.
When bundling workflows ahead of time, make sure to provide custom payload and failure
converter paths as options to bundleWorkflowCode
.
Inherited fromâ
Omit.dataConverter
debugModeâ
âĸ debugMode: boolean
If true
Worker runs Workflows in the same thread allowing debugger to
attach to Workflow instances.
Workflow execution time will not be limited by the Worker in debugMode
.
Default
false unless the TEMPORAL_DEBUG
environment variable is set.
Inherited fromâ
Omit.debugMode
defaultHeartbeatThrottleIntervalâ
âĸ defaultHeartbeatThrottleInterval: Duration | undefined & Duration
Default interval for throttling activity heartbeats in case
ActivityOptions.heartbeat_timeout
is unset.
When the timeout is set in the ActivityOptions
, throttling is set to
heartbeat_timeout * 0.8
.
Format
number of milliseconds or ms-formatted string
Default
30 seconds
Inherited fromâ
Omit.defaultHeartbeatThrottleInterval
defaultHeartbeatThrottleIntervalMsâ
âĸ defaultHeartbeatThrottleIntervalMs: number
enableNonLocalActivitiesâ
âĸ enableNonLocalActivities: boolean
Whether or not to poll on the Activity task queue.
If disabled and activities are registered on the Worker, it will run only local Activities. This setting is ignored if no activity is registed on the Worker.
Default
true
Inherited fromâ
Omit.enableNonLocalActivities
enableSDKTracingâ
âĸ Optional
enableSDKTracing: boolean
Deprecated
SDK tracing is no longer supported. This option is ignored.
Inherited fromâ
Omit.enableSDKTracing
identityâ
âĸ identity: string
A human-readable string that can identify your worker
Note that in most production environments, the identity
value set by default may be unhelpful for traceability
purposes. It is highly recommended that you set this value to something that will allow you to efficiently identify
that particular Worker container/process/logs in your infrastructure (ex: the task ID allocated to this container
by your orchestrator).
Default
${process.pid}@${os.hostname()}
Inherited fromâ
Omit.identity
interceptorsâ
âĸ interceptors: Required
<Pick
<WorkerInterceptors
, "activity"
| "workflowModules"
>>
isolateExecutionTimeoutâ
âĸ isolateExecutionTimeout: Duration
Time to wait for result when calling a Workflow isolate function.
Format
number of milliseconds or ms-formatted string
This value is not exposed at the moment.
Default
5s
Inherited fromâ
Omit.isolateExecutionTimeout
isolateExecutionTimeoutMsâ
âĸ isolateExecutionTimeoutMs: number
loadedDataConverterâ
âĸ loadedDataConverter: LoadedDataConverter
maxActivitiesPerSecondâ
âĸ Optional
maxActivitiesPerSecond: number
Limits the number of Activities per second that this Worker will process. (Does not limit the number of Local Activities.) The Worker will not poll for new Activities if by doing so it might receive and execute an Activity which would cause it to exceed this limit. Must be a positive number.
If unset, no rate limiting will be applied to Worker's Activities. (tctl task-queue describe
will display the
absence of a limit as 100,000.)
Inherited fromâ
Omit.maxActivitiesPerSecond
maxCachedWorkflowsâ
âĸ maxCachedWorkflows: number
The number of Workflow isolates to keep in cached in memory
Cached Workflows continue execution from their last stopping point. If the Worker is asked to run an uncached Workflow, it will need to fetch and replay the entire Workflow history.
When reuseV8Context
is disabledâ
The major factors contributing to a Workflow Execution's memory weight are:
- its input arguments;
- allocations made and retained by the Workflow itself;
- allocations made and retained by all loaded librairies (including the Node JS builtin context);
- the size of all Payloads sent or received by the Workflow (see Core SDK issue #363).
Most users are able to fil at least 250 Workflows per GB of available memory. In some performance test, we managed to fit 750 Workflows per GB. Your millage may vary.
When reuseV8Context
is enabledâ
The major factors contributing to a Workflow Execution's memory weight are:
- its input arguments;
- allocations made and retained by the Workflow itself;
- the size of all Payloads sent or received by the Workflow (see Core SDK issue #363).
Since most objects are shared/reused across Workflows, the per-Workflow memory footprint is much smaller. Most users are able to fit at least 600 Workflows per GB of available memory. In one reference performance test, memory usage grew by approximately 1 MB per cached Workflow (that is including memory used for activity executions of these Workflows). Your millage may vary.
Default
if reuseV8Context = true
, then max(floor(max(maxHeapMemory - 200MB, 0) * (600WF / 1024MB)), 10)
.
Otherwise max(floor(max(maxHeapMemory - 400MB, 0) * (250WF / 1024MB)), 10)
Inherited fromâ
Omit.maxCachedWorkflows
maxConcurrentActivityTaskExecutionsâ
âĸ Optional
maxConcurrentActivityTaskExecutions: number
Maximum number of Activity tasks to execute concurrently. Adjust this to improve Worker resource consumption.
Mutually exclusive with the tuner option.
Default
100 if no {@link tuner} is set
Inherited fromâ
Omit.maxConcurrentActivityTaskExecutions
maxConcurrentActivityTaskPollsâ
âĸ maxConcurrentActivityTaskPolls: number
Maximum number of Activity tasks to poll concurrently.
Increase this setting if your Worker is failing to fill in all of its
maxConcurrentActivityTaskExecutions
slots despite a backlog of Activity
Tasks in the Task Queue (ie. due to network latency). Can't be higher than
maxConcurrentActivityTaskExecutions
.
Default
min(10, maxConcurrentActivityTaskExecutions)
Inherited fromâ
Omit.maxConcurrentActivityTaskPolls
maxConcurrentLocalActivityExecutionsâ
âĸ Optional
maxConcurrentLocalActivityExecutions: number
Maximum number of Activity tasks to execute concurrently. Adjust this to improve Worker resource consumption.
Mutually exclusive with the tuner option.
Default
100 if no {@link tuner} is set
Inherited fromâ
Omit.maxConcurrentLocalActivityExecutions
maxConcurrentWorkflowTaskExecutionsâ
âĸ Optional
maxConcurrentWorkflowTaskExecutions: number
Maximum number of Workflow Tasks to execute concurrently.
In general, a Workflow Worker's performance is mostly network bound (due to communication latency with the Temporal server). Accepting multiple Workflow Tasks concurrently helps compensate for network latency, until the point where the Worker gets CPU bound.
Increasing this number will have no impact if Workflow Task pollers can't fill available execution slots fast
enough. Therefore, when adjusting this value, you may want to similarly adjust maxConcurrentWorkflowTaskPolls
.
See WorkerOptions.maxConcurrentWorkflowTaskPolls for more information.
Also, setting this value too high might cause Workflow Task timeouts due to the fact that the Worker is not able to complete processing accepted Workflow Tasks fast enough. Increasing the number of Workflow threads (see WorkerOptions.workflowThreadPoolSize) may help in that case.
General guidelines:
- High latency to Temporal Server => Increase this number
- Very short Workflow Tasks (no lengthy Local Activities) => increase this number
- Very long/heavy Workflow Histories => decrease this number
- Low CPU usage despite backlog of Workflow Tasks => increase this number
- High number of Workflow Task timeouts => decrease this number
In some performance test against Temporal Cloud, running with a single Workflow thread and the Reuse V8 Context
option enabled, we reached peak performance with a maxConcurrentWorkflowTaskExecutions
of 120
, and
maxConcurrentWorkflowTaskPolls
of 60
(worker machine: Apple M2 Max; ping of 74 ms to Temporal Cloud;
load test scenario: "activityCancellation10kIters", which has short histories, running a single activity).
Your millage may vary.
Can't be lower than 2 if maxCachedWorkflows
is non-zero.
Mutually exclusive with the tuner option.
Default
40 if no {@link tuner} is set
Inherited fromâ
Omit.maxConcurrentWorkflowTaskExecutions
maxConcurrentWorkflowTaskPollsâ
âĸ maxConcurrentWorkflowTaskPolls: number
Maximum number of Workflow Tasks to poll concurrently.
In general, a Workflow Worker's performance is mostly network bound (due to communication latency with the Temporal server). Polling multiple Workflow Tasks concurrently helps compensate for this latency, by ensuring that the Worker is not starved waiting for the server to return new Workflow Tasks to execute.
This setting is highly related with WorkerOptions.maxConcurrentWorkflowTaskExecutions. In various
performance tests, we generally got optimal performance by setting this value to about half of
maxConcurrentWorkflowTaskExecutions
. Your millage may vary.
Setting this value higher than needed may have negative impact on the server's performance. Consequently, the server may impose a limit on the total number of concurrent Workflow Task pollers.
General guidelines:
- By default, set this value to half of
maxConcurrentWorkflowTaskExecutions
. - Increase if actual number of Workflow Tasks being processed concurrently is lower than
maxConcurrentWorkflowTaskExecutions
despite a backlog of Workflow Tasks in the Task Queue. - Keep this value low for Task Queues which have very few concurrent Workflow Executions.
Can't be higher than maxConcurrentWorkflowTaskExecutions
, and can't be lower than 2.
Default
min(10, maxConcurrentWorkflowTaskExecutions)
Inherited fromâ
Omit.maxConcurrentWorkflowTaskPolls
maxHeartbeatThrottleIntervalâ
âĸ maxHeartbeatThrottleInterval: Duration | undefined & Duration
Longest interval for throttling activity heartbeats
Format
number of milliseconds or ms-formatted string
Default
60 seconds
Inherited fromâ
Omit.maxHeartbeatThrottleInterval
maxHeartbeatThrottleIntervalMsâ
âĸ maxHeartbeatThrottleIntervalMs: number
maxTaskQueueActivitiesPerSecondâ
âĸ Optional
maxTaskQueueActivitiesPerSecond: number
Sets the maximum number of activities per second the task queue will dispatch, controlled server-side. Note that this only takes effect upon an activity poll request. If multiple workers on the same queue have different values set, they will thrash with the last poller winning.
If unset, no rate limiting will be applied to the task queue.
Inherited fromâ
Omit.maxTaskQueueActivitiesPerSecond
namespaceâ
âĸ namespace: string
The namespace this worker will connect to
Default
"default"
Inherited fromâ
Omit.namespace
nonStickyToStickyPollRatioâ
âĸ nonStickyToStickyPollRatio: number
maxConcurrentWorkflowTaskPolls
* this number = the number of max pollers that will
be allowed for the nonsticky queue when sticky tasks are enabled. If both defaults are used,
the sticky queue will allow 8 max pollers while the nonsticky queue will allow 2. The
minimum for either poller is 1, so if maxConcurrentWorkflowTaskPolls
is 1 and sticky queues are
enabled, there will be 2 concurrent polls.
â ī¸ This API is experimental and may be removed in the future if the poll scaling algorithm changes.
This API is experimental and may be removed in the future if the poll scaling algorithm changes.
Default
0.2
Inherited fromâ
Omit.nonStickyToStickyPollRatio
reuseV8Contextâ
âĸ reuseV8Context: boolean
Toggle whether to reuse a single V8 context for the workflow sandbox.
Context reuse significantly decreases the amount of resources taken up by workflows. From running basic stress tests we've observed 2/3 reduction in memory usage and 1/3 to 1/2 in CPU usage with this feature turned on.
NOTE: We strongly recommend enabling the Reuse V8 Context execution model, and there is currently no known reason
not to use it. Support for the legacy execution model may get removed at some point in the future. Please report
any issue that requires you to disable reuseV8Context
.
Default
true
Inherited fromâ
Omit.reuseV8Context
showStackTraceSourcesâ
âĸ showStackTraceSources: boolean
Whether or not to send the sources in enhanced stack trace query responses
Default
false
Inherited fromâ
Omit.showStackTraceSources
shutdownForceTimeâ
âĸ Optional
shutdownForceTime: Duration
Time to wait before giving up on graceful shutdown and forcefully terminating the worker.
After this duration, the worker will throw GracefulShutdownPeriodExpiredError and any running activities and workflows will not be cleaned up. It is recommended to exit the process after this error is thrown.
Use this option if you must guarantee that the worker eventually shuts down.
Format
number of milliseconds or ms-formatted string
Inherited fromâ
Omit.shutdownForceTime
shutdownForceTimeMsâ
âĸ Optional
shutdownForceTimeMs: number
shutdownGraceTimeâ
âĸ shutdownGraceTime: Duration | undefined & Duration
Time to wait for pending tasks to drain after shutdown was requested.
In-flight activities will be cancelled after this period and their current attempt will be resolved as failed if
they confirm cancellation (by throwing a CancelledFailure or AbortError
).
Format
number of milliseconds or ms-formatted string
Default
0
Inherited fromâ
Omit.shutdownGraceTime