From 00921c7a3a27a34360c572e485d9e50dc93503a6 Mon Sep 17 00:00:00 2001 From: Dustin Cote Date: Tue, 24 Feb 2026 12:34:49 -0500 Subject: [PATCH 1/2] Add plain English description of exported data to History Export docs Addresses customer confusion where the docs only linked to a proto schema with no description of what's actually in the export files. Co-Authored-By: Claude Opus 4.6 --- docs/cloud/export.mdx | 109 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/docs/cloud/export.mdx b/docs/cloud/export.mdx index a21b4f0b08..0b3eb68489 100644 --- a/docs/cloud/export.mdx +++ b/docs/cloud/export.mdx @@ -29,6 +29,115 @@ Exports run hourly, beginning 10 minutes after the hour. Allow up to 24 hours for a closed Workflow to appear in the exported file. Delivery is guaranteed at least once. +## What's in the exported data {#exported-data} + +Each exported file contains one or more complete Workflow Execution histories serialized as protocol buffers using the [`WorkflowExecutions`](https://github.com/temporalio/api/blob/master/temporal/api/export/v1/message.proto) proto. + +Each history is an ordered sequence of events that records everything that happened during a Workflow Execution: + +- **Workflow configuration** - Input data, timeouts, Task Queue, retry policies, search attributes, and memo +- **Activity lifecycle** - Each Activity scheduled, started, completed (or failed/timed out), including inputs and results +- **Timers and sleeps** - Timer starts and fires +- **Signals and Updates** - External signals received and Update requests handled +- **Child Workflows** - Child Workflow starts and completions +- **Workflow result** - How the Workflow ended (completed, failed, timed out, terminated, canceled, or continued-as-new) + +Search attributes in the export use your **user-defined names** (for example, `customerId`), not internal column names. + +The export format is **protobuf binary**. +You must deserialize using the [proto schema](https://github.com/temporalio/api/blob/master/temporal/api/export/v1/message.proto) before the data is human-readable. + +The following is a simplified JSON representation of what one Workflow Execution looks like after deserialization. +This example shows a Workflow that started, ran one Activity, and completed: + +```json +{ + "items": [ + { + "history": { + "events": [ + { + "eventId": "1", + "eventTime": "2025-02-24T18:00:00Z", + "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_STARTED", + "workflowExecutionStartedEventAttributes": { + "workflowType": { "name": "OrderWorkflow" }, + "taskQueue": { "name": "order-processing" }, + "input": { "payloads": ["...serialized input..."] }, + "workflowExecutionTimeout": "3600s", + "searchAttributes": { + "indexedFields": { + "customerId": { "data": "\"customer-42\"" }, + "orderType": { "data": "\"standard\"" } + } + } + } + }, + { + "eventId": "2", + "eventTime": "2025-02-24T18:00:00Z", + "eventType": "EVENT_TYPE_WORKFLOW_TASK_SCHEDULED" + }, + { + "eventId": "3", + "eventTime": "2025-02-24T18:00:01Z", + "eventType": "EVENT_TYPE_WORKFLOW_TASK_COMPLETED" + }, + { + "eventId": "4", + "eventTime": "2025-02-24T18:00:01Z", + "eventType": "EVENT_TYPE_ACTIVITY_TASK_SCHEDULED", + "activityTaskScheduledEventAttributes": { + "activityType": { "name": "ChargeCustomer" }, + "taskQueue": { "name": "order-processing" }, + "input": { "payloads": ["...serialized input..."] }, + "scheduleToCloseTimeout": "300s", + "startToCloseTimeout": "60s" + } + }, + { + "eventId": "5", + "eventTime": "2025-02-24T18:00:02Z", + "eventType": "EVENT_TYPE_ACTIVITY_TASK_STARTED" + }, + { + "eventId": "6", + "eventTime": "2025-02-24T18:00:03Z", + "eventType": "EVENT_TYPE_ACTIVITY_TASK_COMPLETED", + "activityTaskCompletedEventAttributes": { + "result": { "payloads": ["...serialized result..."] }, + "scheduledEventId": "4", + "startedEventId": "5" + } + }, + { + "eventId": "7", + "eventTime": "2025-02-24T18:00:03Z", + "eventType": "EVENT_TYPE_WORKFLOW_TASK_SCHEDULED" + }, + { + "eventId": "8", + "eventTime": "2025-02-24T18:00:03Z", + "eventType": "EVENT_TYPE_WORKFLOW_TASK_COMPLETED" + }, + { + "eventId": "9", + "eventTime": "2025-02-24T18:00:03Z", + "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED", + "workflowExecutionCompletedEventAttributes": { + "result": { "payloads": ["...serialized result..."] } + } + } + ] + } + } + ] +} +``` + +The outer `items` array can contain multiple Workflow Executions per file. +`WORKFLOW_TASK_SCHEDULED` and `WORKFLOW_TASK_COMPLETED` events are internal bookkeeping - most analytics pipelines skip them. +Only the key fields are shown above. Actual events include additional fields like `version`, `taskId`, and `workerVersion`. ## Prerequisites {#prerequisites} From 5c70c6145e2dc97a19fa4e931746a23bc5b7bdd5 Mon Sep 17 00:00:00 2001 From: Dustin Cote Date: Tue, 24 Feb 2026 12:45:30 -0500 Subject: [PATCH 2/2] cleanup example json --- docs/cloud/export.mdx | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/cloud/export.mdx b/docs/cloud/export.mdx index 0b3eb68489..9cbedfd6cb 100644 --- a/docs/cloud/export.mdx +++ b/docs/cloud/export.mdx @@ -37,7 +37,7 @@ Each history is an ordered sequence of events that records everything that happe - **Workflow configuration** - Input data, timeouts, Task Queue, retry policies, search attributes, and memo - **Activity lifecycle** - Each Activity scheduled, started, completed (or failed/timed out), including inputs and results -- **Timers and sleeps** - Timer starts and fires +- **Timers** - Timer starts and fires - **Signals and Updates** - External signals received and Update requests handled - **Child Workflows** - Child Workflow starts and completions - **Workflow result** - How the Workflow ended (completed, failed, timed out, terminated, canceled, or continued-as-new) @@ -81,11 +81,6 @@ This example shows a Workflow that started, ran one Activity, and completed: { "eventId": "3", "eventTime": "2025-02-24T18:00:01Z", - "eventType": "EVENT_TYPE_WORKFLOW_TASK_COMPLETED" - }, - { - "eventId": "4", - "eventTime": "2025-02-24T18:00:01Z", "eventType": "EVENT_TYPE_ACTIVITY_TASK_SCHEDULED", "activityTaskScheduledEventAttributes": { "activityType": { "name": "ChargeCustomer" }, @@ -96,32 +91,25 @@ This example shows a Workflow that started, ran one Activity, and completed: } }, { - "eventId": "5", + "eventId": "4", "eventTime": "2025-02-24T18:00:02Z", "eventType": "EVENT_TYPE_ACTIVITY_TASK_STARTED" }, { - "eventId": "6", + "eventId": "5", "eventTime": "2025-02-24T18:00:03Z", "eventType": "EVENT_TYPE_ACTIVITY_TASK_COMPLETED", "activityTaskCompletedEventAttributes": { - "result": { "payloads": ["...serialized result..."] }, - "scheduledEventId": "4", - "startedEventId": "5" + "result": { "payloads": ["...serialized result..."] } } }, { - "eventId": "7", - "eventTime": "2025-02-24T18:00:03Z", - "eventType": "EVENT_TYPE_WORKFLOW_TASK_SCHEDULED" - }, - { - "eventId": "8", + "eventId": "6", "eventTime": "2025-02-24T18:00:03Z", "eventType": "EVENT_TYPE_WORKFLOW_TASK_COMPLETED" }, { - "eventId": "9", + "eventId": "7", "eventTime": "2025-02-24T18:00:03Z", "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED", "workflowExecutionCompletedEventAttributes": { @@ -136,7 +124,6 @@ This example shows a Workflow that started, ran one Activity, and completed: ``` The outer `items` array can contain multiple Workflow Executions per file. -`WORKFLOW_TASK_SCHEDULED` and `WORKFLOW_TASK_COMPLETED` events are internal bookkeeping - most analytics pipelines skip them. Only the key fields are shown above. Actual events include additional fields like `version`, `taskId`, and `workerVersion`. ## Prerequisites {#prerequisites}