Execution workflow tracing: a guide to execution-engine library (part 1)
Tags: node, engine, workflow, typescript
Published: 2023-12-12 22:28:14

## Introduction

Welcome to an exploration of the powerful capabilities offered by the [execution-engine](https://www.npmjs.com/package/execution-engine) library.
In this guide, we delve into the art of tracing the execution flow within your TypeScript/JavaScript projects.

Unleash the magic of tracing your codebase and visualize its rhythmic dance.

## Why Trace Your Code Workflow 🕵️‍♂️

Tracing your code offers a visual roadmap to understand, optimize, and debug projects. Here's why tracing matters:

**1. Uncover Function Flow**: Tracing reveals the exact sequence of function executions, simplifying your project's flow comprehension.

**2. Visualize Code Relations**: Generate a visual graph from the trace to easily grasp relationships between different functions.

**3. Capture Details**: Traces include input, output, and error specifics, aiding in issue resolution and data analysis.

**4. Monitor Timing**: Understand the timing and duration of each function execution to identify performance bottlenecks.

**5. Analyze Call Hierarchy**: Explore how functions are called at different levels, revealing entry points and data flow patterns.


## Installation 📦

Ready to experience the benefits? Install the [execution-engine library](https://www.npmjs.com/package/execution-engine) and let's dive into practical examples!

We'll be using version **2.0.1** for these examples.

You can find the library on [npm](https://www.npmjs.com/package/execution-engine) and its source code on [GitHub](https://github.com/tabkram/execution-engine).

### Using npm:

```bash
npm install execution-engine@2.0.1
```

### Using yarn:

```bash
yarn add execution-engine@2.0.1
```

Make sure to check the [npm package page](https://www.npmjs.com/package/execution-engine) for any updates or additional information. If you're interested in exploring the source code or contributing, visit the [GitHub repository](https://github.com/tabkram/execution-engine).

## Examples: Tracing Your Code in Action 🚀

### 1. Basic Usage

**Example Code:**
```typescript
import { ExecutionEngine } from "execution-engine";

const engine = new ExecutionEngine();

// for sync functions:
const res1 = engine.run((param) => `result1 for ${param}`, ['param1']);

// for async functions:
const res2 = await engine.run(async (param) => `result2 for ${param}`, [res1.outputs]);

// Retrieve the trace
const trace = engine.getTrace();
console.log('Trace:', trace);
```

**Trace Output:**
[Link to Example 1 Trace Output](https://github.com/tabkram/execution-engine/blob/v2.0.1/examples/usage.json)

**Trace Graph:**
[Link to Example 1 Trace Graph](https://tabkram.github.io/json-to-graph/?data=https://raw.githubusercontent.com/tabkram/execution-engine/v2.0.1/examples/usage.json)

### 2. Advanced Usage with Decorators

**Example Code:**
```typescript
import { engine, run } from "execution-engine";

@engine({ id: "uniqueEngineId" })
class MyClass extends EngineTask {
  @run()
  myMethod1(param: string) {
    // Method implementation
  }

  @run()
  async myMethod2(param: string) {
    // Async method implementation
  }
}

const myInstance = new MyClass();
myInstance.myMethod2("param1");
await myInstance.myMethod2("param2");

// Retrieve the trace
const trace = myInstance.engine.getTrace();
console.log("Trace:", trace);
```

**Trace Output:**
[Link to Example 2 Trace Output](https://github.com/tabkram/execution-engine/blob/v2.0.1/examples/usage2.json)

**Trace Graph:**
[Link to Example 2 Trace Graph](https://tabkram.github.io/json-to-graph/?data=https://raw.githubusercontent.com/tabkram/execution-engine/v2.0.1/examples/usage2.json)

In these examples, we illustrate two fundamental approaches to utilizing the ExecutionEngine library, enabling you to trace and visualize the execution flow of your code. 
Take the plunge, navigate the traces, and unlock the secrets to your project's dynamic dance moves! 🕺✨

## Customizing Tracing Configuration 🛠️

Customize tracing configurations for executed functions or methods in the `ExecutionEngine` library by using the `traceOptions` parameter. This flexibility is available both when using `.run()` and with the `@run()` decorator. Specify configurations through a simplified format or a comprehensive object, offering flexibility in customization.

### Trace Options

The `traceOptions` parameter can be provided in two formats:

#### Simple Format:

```typescript
{
  id: string;
  label: string;
  parent?: string;
}
```

#### Full Trace Options Object:

```typescript
{
  trace: {
    id: string;
    label: string;
    parent?: string;
  };
  config?: {
    traceExecution?: boolean | Array<keyof NodeExecutionTrace<I, O>> | NodeExecutionTraceExtractor<I, O>;
    parallel?: boolean | string;
    errors?: 'catch' | 'throw';
  };
}
```

### Explanation

- **Simple Format**: Directly specify the `id`, `label`, and optional `parent` properties for basic tracing information.

- **Full Trace Options Object**: For more control, use the complete object format. It includes the `trace` property for trace-related details and the `config` property for additional tracing configurations.

    - **`traceExecution`**: Control what to trace exactly in the execution. Options include a boolean, an array of keys from `NodeExecutionTrace`, or a **custom extractor function**.
  
    - **`parallel`**: Enable or disable parallel execution. Choose a boolean or a string.

    - **`errors`**: Specify the error handling strategy. Choose between `'catch'` to catch errors or `'throw'` to let errors propagate.


## Conclusion

This guide has provided an overview of the `execution-engine` library, shedding light on the intricacies of code tracing. Now, you can dive into more examples [here](https://github.com/tabkram/execution-engine/tree/v2.0.1/examples) and customize your tracing configuration effortlessly for each function or method, gaining precise insights into the execution flow of your code. Happy tracing! 🚀

## Additional Resources
- [Execution Engine GitHub Repository](https://github.com/tabkram/execution-engine)
- [Execution Engine Documentation](https://tabkram.github.io/execution-engine)
- [json-to-graph Online Demo](https://tabkram.github.io/json-to-graph/)