Introduction

A comprehensive debugging solution that enables step-through debugging of Temporal workflows. Unlike traditional debuggers that aren't aware of Temporal's execution model, this debugger provides a seamless development experience by allowing you to set breakpoints, inspect variables, and trace execution flow within your workflow code.

Why This Debugger?

Debugging Temporal workflows has traditionally been challenging. Execution of a workflow is driven by history events rather than direct code execution. Workflow state is managed externally by the Temporal service, and the progress of a workflow depends on interaction between the Temporal server and a thick SDK that knows how to use history events to trigger the actual workflow code execution.

This debugger solves these challenges by leveraging the workflow replayer - it reconstructs workflow execution from Temporal's event history, allowing you to debug exactly what happened during the original execution.

Key Features

Seamless IDE Integration

• Multi-language Support: Works with Go, TypeScript/Node.js, and Python today via adapters
• JetBrains Plugin (Go): Native integration with GoLand using standard debugging controls and a history view
• VS Code Extension: Open a panel, load history, set event breakpoints, and replay with your adapter

Who Is This For?

• Temporal Workflow Developers: Anyone building workflows with Temporal's SDK

Whether you're debugging a complex workflow that's failing in production or just want a better development experience while building new workflows, this debugger provides the tools you need to understand and fix your Temporal workflow code efficiently.

Usage

Installation Options

Pre-requisite for JetBrains only (optional): install tdlv debugger from Github Release. The JetBrains plugin can auto-build tdlv on debug start.

IDE Plugins: Jetbrains (preview, Go support only):

Vscode (Go, Python and JS):

Replayer Adapters for Temporal SDK Languages:

• Go
• Python
• TypeScript

Replay a workflow with the plugin/extension

1. Load workflow history in the IDE

• Open the Temporal Workflow Debugger view in your IDE (JetBrains or VS Code)
• Load a Temporal workflow history file (.json)
• The IDE starts a local server on http://127.0.0.1:54578 that serves:
  • GET /history (workflow history in JSON/bytes)
  • GET /breakpoints (enabled breakpoints as event IDs)
  • POST /current-event (highlight current event in the UI)

2. Run your adapter in IDE mode to replay

• Go

  import (
      "go.temporal.io/sdk/worker"
      replayeradapter "github.com/phuongdnguyen/temporal-workflow-debugger/replayer-adapter-go"
  )
  
  func main() {
      replayeradapter.SetReplayMode(replayeradapter.ReplayModeIde)
      opts := replayeradapter.ReplayOptions{
          WorkerReplayOptions: worker.WorkflowReplayerOptions{},
      }
      if err := replayeradapter.Replay(opts, YourWorkflow); err != nil { panic(err) }
  }

• TypeScript/Node.js

  import { ReplayMode, replay } from '@phuongdnguyen/replayer-adapter-nodejs'
  
  await replay({
    mode: ReplayMode.IDE,
    workerReplayOptions: { workflowsPath: require.resolve('./workflows') }
  }, yourWorkflow)

• Python

  from replayer_adapter_python import *
  
  set_replay_mode(ReplayMode.IDE)
  opts = ReplayOptions()
  replay(opts, YourWorkflowClass)

3. Debug

• Set breakpoints in the IDE history view
• Start your adapter code. It will fetch history/breakpoints from the IDE and pause on hits

Notes and limitations

• Only Workflow code executes during replay. Activities are not executed; their effects are driven by history.
• Breakpoints are event-based. In standalone mode you can also provide explicit event IDs to pause on.

Examples

• See example/go and example/js and example/python for runnable samples and history files.