Skip to content

Add external storage drivers to worker heartbeat #1130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jmaeagle99 merged 2 commits into from
Mar 17, 2026
Merged

Add external storage drivers to worker heartbeat #1130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd173e6
Add external storage drivers to worker heartbeat
jmaeagle99 Mar 17, 2026
279a7a4
Merge branch 'master' into driver-info
jmaeagle99 Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 108 additions & 4 deletions crates/common/protos/api_upstream/openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2735,7 +2735,7 @@
},
{
"name": "query",
"description": "`query` in ListWorkers is used to filter workers based on worker status info.\nThe following worker status attributes are expected are supported as part of the query:\n* WorkerInstanceKey\n* WorkerIdentity\n* HostName\n* TaskQueue\n* DeploymentName\n* BuildId\n* SdkName\n* SdkVersion\n* StartTime\n* LastHeartbeatTime\n* Status\nCurrently metrics are not supported as a part of ListWorkers query.",
"description": "`query` in ListWorkers is used to filter workers based on worker attributes.\nSupported attributes:\n* WorkerInstanceKey\n* WorkerIdentity\n* HostName\n* TaskQueue\n* DeploymentName\n* BuildId\n* SdkName\n* SdkVersion\n* StartTime\n* Status",
"in": "query",
"required": false,
"type": "string"
Expand Down Expand Up @@ -7235,7 +7235,7 @@
},
{
"name": "query",
"description": "`query` in ListWorkers is used to filter workers based on worker status info.\nThe following worker status attributes are expected are supported as part of the query:\n* WorkerInstanceKey\n* WorkerIdentity\n* HostName\n* TaskQueue\n* DeploymentName\n* BuildId\n* SdkName\n* SdkVersion\n* StartTime\n* LastHeartbeatTime\n* Status\nCurrently metrics are not supported as a part of ListWorkers query.",
"description": "`query` in ListWorkers is used to filter workers based on worker attributes.\nSupported attributes:\n* WorkerInstanceKey\n* WorkerIdentity\n* HostName\n* TaskQueue\n* DeploymentName\n* BuildId\n* SdkName\n* SdkVersion\n* StartTime\n* Status",
"in": "query",
"required": false,
"type": "string"
Expand Down Expand Up @@ -12040,6 +12040,15 @@
}
}
},
"v1DeclinedTargetVersionUpgrade": {
"type": "object",
"properties": {
"deploymentVersion": {
"$ref": "#/definitions/v1WorkerDeploymentVersion"
}
},
"description": "Wrapper for a target deployment version that the SDK declined to upgrade to.\nSee declined_target_version_upgrade on WorkflowExecutionStartedEventAttributes."
},
"v1DeleteNexusEndpointResponse": {
"type": "object"
},
Expand Down Expand Up @@ -13429,7 +13438,16 @@
"items": {
"type": "object",
"$ref": "#/definitions/v1WorkerInfo"
}
},
"description": "Deprecated: Use workers instead. This field returns full WorkerInfo which\nincludes expensive runtime metrics. We will stop populating this field in the future."
},
"workers": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1WorkerListInfo"
},
"description": "Limited worker information."
},
"nextPageToken": {
"type": "string",
Expand Down Expand Up @@ -15864,6 +15882,15 @@
"v1StopBatchOperationResponse": {
"type": "object"
},
"v1StorageDriverInfo": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the driver, required."
}
}
},
"v1StructuredCalendarSpec": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -16889,6 +16916,14 @@
"$ref": "#/definitions/v1PluginInfo"
},
"description": "Plugins currently in use by this SDK."
},
"drivers": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1StorageDriverInfo"
},
"description": "Storage drivers in use by this SDK."
}
},
"description": "Worker info message, contains information about the worker and its current state.\nAll information is provided by the worker itself."
Expand Down Expand Up @@ -16927,7 +16962,72 @@
"workerHeartbeat": {
"$ref": "#/definitions/v1WorkerHeartbeat"
}
}
},
"description": "Detailed worker information."
},
"v1WorkerListInfo": {
"type": "object",
"properties": {
"workerInstanceKey": {
"type": "string",
"description": "Worker identifier, should be unique for the namespace.\nIt is distinct from worker identity, which is not necessarily namespace-unique."
},
"workerIdentity": {
"type": "string",
"description": "Worker identity, set by the client, may not be unique.\nUsually host_name+(user group name)+process_id, but can be overwritten by the user."
},
"taskQueue": {
"type": "string",
"description": "Task queue this worker is polling for tasks."
},
"deploymentVersion": {
"$ref": "#/definitions/v1WorkerDeploymentVersion"
},
"sdkName": {
"type": "string"
},
"sdkVersion": {
"type": "string"
},
"status": {
"$ref": "#/definitions/v1WorkerStatus",
"description": "Worker status. Defined by SDK."
},
"startTime": {
"type": "string",
"format": "date-time",
"title": "Worker start time.\nIt can be used to determine worker uptime. (current time - start time)"
},
"hostName": {
"type": "string",
"description": "Worker host identifier."
},
"workerGroupingKey": {
"type": "string",
"title": "Worker grouping identifier. A key to group workers that share the same client+namespace+process.\nThis will be used to build the worker command nexus task queue name:\n\"temporal-sys/worker-commands/{worker_grouping_key}\""
},
"processId": {
"type": "string",
"description": "Worker process identifier. This id only needs to be unique\nwithin one host (so using e.g. a unix pid would be appropriate)."
},
"plugins": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1PluginInfo"
},
"description": "Plugins currently in use by this SDK."
},
"drivers": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1StorageDriverInfo"
},
"description": "Storage drivers in use by this SDK."
}
},
"description": "Limited worker information returned in the list response.\nWhen adding fields here, ensure that it is also added to WorkerInfo (as it carries the full worker information)."
},
"v1WorkerPollerInfo": {
"type": "object",
Expand Down Expand Up @@ -17628,6 +17728,10 @@
"eagerExecutionAccepted": {
"type": "boolean",
"description": "A boolean indicating whether the SDK has asked to eagerly execute the first workflow task for this workflow and\neager execution was accepted by the server.\nOnly populated by server with version >= 1.29.0."
},
"declinedTargetVersionUpgrade": {
"$ref": "#/definitions/v1DeclinedTargetVersionUpgrade",
"description": "During a previous run of this workflow, the server may have notified the SDK\nthat the Target Worker Deployment Version changed, but the SDK declined to\nupgrade (e.g., by continuing-as-new with PINNED behavior). This field records\nthe target version that was declined.\n\nThis is a wrapper message to distinguish \"never declined\" (nil wrapper) from\n\"declined an unversioned target\" (non-nil wrapper with nil deployment_version).\n\nUsed internally by the server during continue-as-new and retry.\nShould not be read or interpreted by SDKs."
}
},
"title": "Always the first event in workflow history"
Expand Down
118 changes: 110 additions & 8 deletions crates/common/protos/api_upstream/openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2461,8 +2461,8 @@ paths:
- name: query
in: query
description: |-
`query` in ListWorkers is used to filter workers based on worker status info.
The following worker status attributes are expected are supported as part of the query:
`query` in ListWorkers is used to filter workers based on worker attributes.
Supported attributes:
* WorkerInstanceKey
* WorkerIdentity
* HostName
Expand All @@ -2472,9 +2472,7 @@ paths:
* SdkName
* SdkVersion
* StartTime
* LastHeartbeatTime
* Status
Currently metrics are not supported as a part of ListWorkers query.
schema:
type: string
responses:
Expand Down Expand Up @@ -6496,8 +6494,8 @@ paths:
- name: query
in: query
description: |-
`query` in ListWorkers is used to filter workers based on worker status info.
The following worker status attributes are expected are supported as part of the query:
`query` in ListWorkers is used to filter workers based on worker attributes.
Supported attributes:
* WorkerInstanceKey
* WorkerIdentity
* HostName
Expand All @@ -6507,9 +6505,7 @@ paths:
* SdkName
* SdkVersion
* StartTime
* LastHeartbeatTime
* Status
Currently metrics are not supported as a part of ListWorkers query.
schema:
type: string
responses:
Expand Down Expand Up @@ -9230,6 +9226,14 @@ components:
data:
type: string
format: bytes
DeclinedTargetVersionUpgrade:
type: object
properties:
deploymentVersion:
$ref: '#/components/schemas/WorkerDeploymentVersion'
description: |-
Wrapper for a target deployment version that the SDK declined to upgrade to.
See declined_target_version_upgrade on WorkflowExecutionStartedEventAttributes.
DeleteNexusEndpointResponse:
type: object
properties: {}
Expand Down Expand Up @@ -10550,6 +10554,14 @@ components:
type: array
items:
$ref: '#/components/schemas/WorkerInfo'
description: |-
Deprecated: Use workers instead. This field returns full WorkerInfo which
includes expensive runtime metrics. We will stop populating this field in the future.
workers:
type: array
items:
$ref: '#/components/schemas/WorkerListInfo'
description: Limited worker information.
nextPageToken:
type: string
description: Next page token
Expand Down Expand Up @@ -14042,6 +14054,12 @@ components:
StopBatchOperationResponse:
type: object
properties: {}
StorageDriverInfo:
type: object
properties:
type:
type: string
description: The type of the driver, required.
StructuredCalendarSpec:
type: object
properties:
Expand Down Expand Up @@ -15515,6 +15533,11 @@ components:
items:
$ref: '#/components/schemas/PluginInfo'
description: Plugins currently in use by this SDK.
drivers:
type: array
items:
$ref: '#/components/schemas/StorageDriverInfo'
description: Storage drivers in use by this SDK.
description: |-
Worker info message, contains information about the worker and its current state.
All information is provided by the worker itself.
Expand Down Expand Up @@ -15555,6 +15578,71 @@ components:
properties:
workerHeartbeat:
$ref: '#/components/schemas/WorkerHeartbeat'
description: Detailed worker information.
WorkerListInfo:
type: object
properties:
workerInstanceKey:
type: string
description: |-
Worker identifier, should be unique for the namespace.
It is distinct from worker identity, which is not necessarily namespace-unique.
workerIdentity:
type: string
description: |-
Worker identity, set by the client, may not be unique.
Usually host_name+(user group name)+process_id, but can be overwritten by the user.
taskQueue:
type: string
description: Task queue this worker is polling for tasks.
deploymentVersion:
$ref: '#/components/schemas/WorkerDeploymentVersion'
sdkName:
type: string
sdkVersion:
type: string
status:
enum:
- WORKER_STATUS_UNSPECIFIED
- WORKER_STATUS_RUNNING
- WORKER_STATUS_SHUTTING_DOWN
- WORKER_STATUS_SHUTDOWN
type: string
description: Worker status. Defined by SDK.
format: enum
startTime:
type: string
description: |-
Worker start time.
It can be used to determine worker uptime. (current time - start time)
format: date-time
hostName:
type: string
description: Worker host identifier.
workerGroupingKey:
type: string
description: |-
Worker grouping identifier. A key to group workers that share the same client+namespace+process.
This will be used to build the worker command nexus task queue name:
"temporal-sys/worker-commands/{worker_grouping_key}"
processId:
type: string
description: |-
Worker process identifier. This id only needs to be unique
within one host (so using e.g. a unix pid would be appropriate).
plugins:
type: array
items:
$ref: '#/components/schemas/PluginInfo'
description: Plugins currently in use by this SDK.
drivers:
type: array
items:
$ref: '#/components/schemas/StorageDriverInfo'
description: Storage drivers in use by this SDK.
description: |-
Limited worker information returned in the list response.
When adding fields here, ensure that it is also added to WorkerInfo (as it carries the full worker information).
WorkerPollerInfo:
type: object
properties:
Expand Down Expand Up @@ -16448,6 +16536,20 @@ components:
A boolean indicating whether the SDK has asked to eagerly execute the first workflow task for this workflow and
eager execution was accepted by the server.
Only populated by server with version >= 1.29.0.
declinedTargetVersionUpgrade:
allOf:
- $ref: '#/components/schemas/DeclinedTargetVersionUpgrade'
description: |-
During a previous run of this workflow, the server may have notified the SDK
that the Target Worker Deployment Version changed, but the SDK declined to
upgrade (e.g., by continuing-as-new with PINNED behavior). This field records
the target version that was declined.

This is a wrapper message to distinguish "never declined" (nil wrapper) from
"declined an unversioned target" (non-nil wrapper with nil deployment_version).

Used internally by the server during continue-as-new and retry.
Should not be read or interpreted by SDKs.
description: Always the first event in workflow history
WorkflowExecutionTerminatedEventAttributes:
type: object
Expand Down
18 changes: 18 additions & 0 deletions crates/common/protos/api_upstream/temporal/api/history/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,24 @@ message WorkflowExecutionStartedEventAttributes {
// eager execution was accepted by the server.
// Only populated by server with version >= 1.29.0.
bool eager_execution_accepted = 38;

// During a previous run of this workflow, the server may have notified the SDK
// that the Target Worker Deployment Version changed, but the SDK declined to
// upgrade (e.g., by continuing-as-new with PINNED behavior). This field records
// the target version that was declined.
//
// This is a wrapper message to distinguish "never declined" (nil wrapper) from
// "declined an unversioned target" (non-nil wrapper with nil deployment_version).
//
// Used internally by the server during continue-as-new and retry.
// Should not be read or interpreted by SDKs.
DeclinedTargetVersionUpgrade declined_target_version_upgrade = 40;
}

// Wrapper for a target deployment version that the SDK declined to upgrade to.
// See declined_target_version_upgrade on WorkflowExecutionStartedEventAttributes.
message DeclinedTargetVersionUpgrade {
temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 1;
}

message WorkflowExecutionCompletedEventAttributes {
Expand Down
Loading
Loading