1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
//! Tools for inspecting workflow execution while debugging and testing.
//!
//! - [`ExecutionTracer`] records events, commands and state accesses per workflow.
//! - [`CommandInspector`] lists the commands a workflow context has produced.
//! - [`StateSnapshot`] captures workflow state and diffs it against another snapshot.
//!
//! These are diagnostic aids. They sit outside the replay path and do not affect
//! how a workflow executes.
//!
//! # Quick start
//!
//! Give a [`TestEnv`](crate::testing::TestEnv) an enabled tracer, run a workflow, and
//! read what the tracer recorded. Clones of a tracer share their traces:
//!
//! ```rust
//! use orcher_sdk::debugging::ExecutionTracer;
//! use orcher_sdk::prelude::*;
//! use orcher_sdk::testing::TestEnv;
//!
//! # #[tokio::main(flavor = "current_thread")]
//! # async fn main() -> Result<()> {
//! let tracer = ExecutionTracer::new().enable();
//! let mut env = TestEnv::new().with_tracer(tracer.clone());
//! env.register_workflow("greet", |name: String| async move { Ok(format!("Hello, {name}")) });
//!
//! let _: String = env.execute_workflow("greet", "Ada").await?;
//!
//! let trace = &tracer.all_traces()[0];
//! assert_eq!(trace.workflow_type, "greet");
//! assert!(!trace.has_errors());
//! # Ok(())
//! # }
//! ```
//!
//! # Execution tracing
//!
//! A tracer records nothing until it is enabled.
//!
//! ```rust
//! use orcher_sdk::debugging::{ExecutionTracer, TraceLevel};
//!
//! let tracer = ExecutionTracer::new()
//! .with_level(TraceLevel::Debug)
//! .with_events(true)
//! .enable();
//! assert!(tracer.is_enabled());
//! ```
//!
//! # Command inspection
//!
//! List the commands a workflow has generated so far, in order:
//!
//! ```rust
//! use orcher_sdk::debugging::CommandInspector;
//! use orcher_sdk::workflow::{WorkflowContext, WorkflowExecution};
//!
//! # #[tokio::main(flavor = "current_thread")]
//! # async fn main() {
//! let execution = WorkflowExecution::new(
//! "order-1".to_string(),
//! "run-1".to_string(),
//! "checkout".to_string(),
//! "default".to_string(),
//! "orders".to_string(),
//! );
//! let ctx = WorkflowContext::new(execution, false, "1.0.0".to_string());
//!
//! // With no recorded result, scheduling a task suspends the workflow.
//! let charged: orcher_sdk::Result<String> = ctx.execute_task("charge_card", 4_200).await;
//! assert!(charged.is_err());
//!
//! for cmd in CommandInspector::new().inspect(&ctx) {
//! println!("{} at seq {}: {}", cmd.command_type, cmd.sequence, cmd.description());
//! }
//! # }
//! ```
//!
//! # State snapshots
//!
//! Record state values in snapshots and compare them:
//!
//! ```rust
//! use orcher_sdk::debugging::StateSnapshot;
//!
//! let mut before = StateSnapshot::new("order-1").with_label("before");
//! before.set("counter", &1)?;
//!
//! let mut after = StateSnapshot::new("order-1").with_label("after");
//! after.set("counter", &2)?;
//! after.set("status", &"shipped")?;
//!
//! let counter: Option<i32> = after.get("counter")?;
//! assert_eq!(counter, Some(2));
//!
//! let diff = before.diff(&after);
//! assert_eq!(diff.changed_keys(), ["counter"]);
//! assert_eq!(diff.added_keys(), ["status"]);
//! # Ok::<(), orcher_sdk::Error>(())
//! ```
//!
//! # Structured logging
//!
//! Workflows and tasks can log through the `tracing` crate directly:
//!
//! ```rust
//! use tracing::{info, debug, instrument};
//! use orcher_sdk::prelude::*;
//!
//! #[instrument(skip(ctx))]
//! async fn my_workflow(ctx: WorkflowContext, order_id: String) -> Result<String> {
//! info!(order_id = %order_id, "Starting workflow");
//!
//! let result: String = ctx.execute_task("process", order_id).await?;
//! debug!(result = %result, "Task completed");
//!
//! Ok(result)
//! }
//! ```
pub use ;
pub use ;
pub use ;