Observability Utilities

Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.

The workflow/observability module provides utilities for working with workflow data in observability and debugging tools. It includes functions to hydrate serialized step I/O, parse machine-readable names into display-friendly formats, and decrypt encrypted workflow data.

Import

import { 
  hydrateResourceIO, 
  observabilityRevivers, 
  parseStepName, 
  parseWorkflowName, 
  parseClassName, 
} from "workflow/observability";

Data Hydration

hydrateResourceIO()

Deserialize step or run data that was serialized using the devalue format. Required to display step input/output in your UI.

import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; 

const step = await world.steps.get(runId, stepId);
const hydrated = hydrateResourceIO(step, observabilityRevivers); 
console.log(hydrated.input, hydrated.output);

Parameters:

Parameter	Type	Description
`resource`	`Step \| WorkflowRun`	The step or run with serialized data
`revivers`	`Revivers`	Reviver functions for deserialization. Use `observabilityRevivers` for standard use.

Returns: The resource with hydrated input and output fields.

observabilityRevivers

A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).

Name Parsing

Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return { shortName: string, moduleSpecifier: string } | null.

parseStepName()

import { parseStepName } from "workflow/observability"; 

const parsed = parseStepName("step//./src/workflows/order//processPayment"); 
// parsed?.shortName → "processPayment"
// parsed?.moduleSpecifier → "./src/workflows/order"

parseWorkflowName()

import { parseWorkflowName } from "workflow/observability"; 

const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); 
// parsed?.shortName → "processOrder"

parseClassName()

import { parseClassName } from "workflow/observability"; 

const parsed = parseClassName("class//./src/models//User"); 
// parsed?.shortName → "User"

Encryption

For workflows with encrypted step data, decrypt before hydrating.

getEncryptionKeyForRun()

Retrieve the encryption key used for a specific workflow run.

import { getEncryptionKeyForRun } from "workflow/observability"; 

const key = await getEncryptionKeyForRun(runId);

Parameters:

Parameter	Type	Description
`runId`	`string`	The workflow run ID

Returns: Encryption key for the run

hydrateResourceIOWithKey()

Hydrate step or run data using a decryption key. Use this instead of hydrateResourceIO() when data is encrypted.

import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; 

const key = await getEncryptionKeyForRun(runId); 
const hydrated = hydrateResourceIOWithKey(step, key);

Parameters:

Parameter	Type	Description
`resource`	`Step \| WorkflowRun`	The step or run with encrypted serialized data
`key`	`EncryptionKey`	The encryption key from `getEncryptionKeyForRun()`

Returns: The resource with decrypted and hydrated input and output fields.

Examples

Parse Display Names for a Run's Steps

import { getWorld } from "workflow/runtime";
import { parseStepName, parseWorkflowName } from "workflow/observability"; 

const world = await getWorld();
const run = await world.runs.get(runId, { resolveData: "none" });
console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); 

const steps = await world.steps.list({ runId, resolveData: "none" });
for (const step of steps.data) {
  const parsed = parseStepName(step.stepName); 
  console.log(`  ${parsed?.shortName}: ${step.status}`); 
}

Storage — Query runs, steps, hooks, and events
Serialization — How workflow data is serialized

Observability Utilities

On this page