[WIP] Workflow History Audit sample

[mjameswh]

What was changed

This adds the Workflow History Audit sample: a set of related tools for investigating potential issues across Workflow Execution Histories.

The project is designed as a starting point, to be adapted and extended for specific applications and investigations.

The sample includes three CLI tools:

1. download.ts selects Workflow Executions using Temporal Visibility, downloads their complete histories, and saves one JSON file per execution to the local filesystem. Payloads are persisted without decoding. Downloads can run concurrently, with a configurable global RPC rate limit—including retries—to control the load on production deployments.
2. analyze.ts processes the saved histories locally through customizable, stateful extractors. Each extractor can collect information throughout a history, then aggregate, reshape, or filter that information before producing its output. Results are written to per-execution analysis files. The included extractors capture execution times and Workflow Task attempts, including worker identity, Build ID, and completion, failure, or timeout status, alongside an application-specific extraction example. Payload decoding happens in memory; only extractor output is written to the analysis files.
3. query.ts searches the local analysis files for executions associated with a particular Workflow Task worker identity or Build ID, optionally restricted to a time interval. This provides an initial investigation tool that users can extend alongside their own extractors.

Separating collection from analysis allows users to revisit the same dataset and refine their investigations without repeatedly fetching histories from the Temporal Service.

Why?

• Workflow Execution Histories provide a detailed audit trail that is valuable for diagnosing production problems after the fact.
• Temporal’s UI makes individual histories easy to explore, but examining executions one by one does not scale to investigations such as:
  • Finding executions that follow a particular execution pattern.
  • Identifying executions associated with a particular worker or code version—for example, to assess exposure after an incident involving a compromised worker.
  • Finding opportunities to optimize workflow behavior.
• Multiple teams have developed similar tools internally, demonstrating their usefulness. However, implementing them requires significant familiarity with history events, payload handling, and SDK behavior. A sample can make this work more accessible and provide a foundation that teams do not have to build from scratch.
• Temporal SDKs could eventually provide APIs that simplify this kind of tooling, but the requirements for those APIs are not yet clear. Introducing these tools as a sample provides immediate value while allowing users to adapt them, share feedback, and help clarify which capabilities should become SDK-supported APIs.