withWorkflow()

Wrap an async function as a traced workflow

Overview

Use withWorkflow(options, fn) to mark an end-to-end run. All nested tasks, agents, and tools are captured under this workflow.

Signature

1withWorkflow<T>(
2 options: {
3 name: string;
4 version?: number;
5 associationProperties?: Record<string, any>;
6 },
7 fn: () => Promise<T>
8): Promise<T>

Basic Usage

1import { RespanTelemetry } from '@respan/tracing';
2
3const respanAi = new RespanTelemetry({
4 apiKey: process.env.RESPAN_API_KEY,
5 appName: 'my-app'
6});
7
8await respanAi.initialize();
9
10const result = await respanAi.withWorkflow(
11 {
12 name: 'data_pipeline',
13 version: 1
14 },
15 async () => {
16 // Your workflow logic here
17 const data = await fetchData();
18 const processed = await processData(data);
19 return processed;
20 }
21);

With Association Properties

1await respanAi.withWorkflow(
2 {
3 name: 'user_request',
4 version: 1,
5 associationProperties: {
6 'user_id': 'user-123',
7 'session_id': 'session-abc',
8 'environment': 'production'
9 }
10 },
11 async () => {
12 // Your workflow logic
13 return await handleUserRequest();
14 }
15);

Nested Tasks

1await respanAi.withWorkflow(
2 { name: 'complete_pipeline' },
3 async () => {
4 const extracted = await respanAi.withTask(
5 { name: 'extract' },
6 async () => {
7 return { records: [1, 2, 3] };
8 }
9 );
10
11 const transformed = await respanAi.withTask(
12 { name: 'transform' },
13 async () => {
14 return extracted.records.map(x => x * 2);
15 }
16 );
17
18 return transformed;
19 }
20);

Parameters

name
stringRequired

Workflow display name for identification in the Respan dashboard

version
number

Version number for tracking workflow iterations

associationProperties
Record<string, any>

Custom metadata to associate with the workflow (user ID, session ID, etc.)

Return Value

Returns a Promise that resolves to the return value of the provided function.

Best Practices

  • Use descriptive workflow names for easy navigation in the dashboard
  • Keep workflows coarse-grained; use tasks for internal steps
  • Add association properties for filtering and grouping in analytics
  • Always call initialize() before using withWorkflow()