Interface VirtualContext

Execution context available inside Virtual callbacks via Virtual.getContext(). Populated automatically by the AsyncLocalStorage wrapper in Virtual.connect().

Example

await Virtual.cron({
  topic: 'billing.daily',
  connection,
  args: [],
  options: { id: 'billing-run', interval: '0 0 * * *' },
  callback: async () => {
    const ctx = Virtual.getContext();
    // ctx.workflowId  === 'billing-run'
    // ctx.topic        === 'billing.daily'
    // ctx.guid         === unique per invocation
  },
});
interface VirtualContext {
    attempt: number;
    dimension: string;
    guid: string;
    spanId: string;
    topic: string;
    traceId: string;
    workflowId: string;
    workflowName: string;
}

Properties

attempt dimension guid spanId topic traceId workflowId workflowName

Properties

attempt

attempt: number

Current retry attempt (1-based). 1 on the first try, incremented on each retry per the RetryPolicy.

dimension

dimension: string

Dimensional address for this execution within the workflow's DAG. Encodes the cycle iteration and parallel branch position.

guid

guid: string

Globally unique identifier for the stream message that triggered this callback. A new GUID is minted for every invocation, including retries and cycle iterations, so it serves as an idempotency key for exactly-once processing.

spanId

spanId: string

OpenTelemetry span ID propagated from the parent activity. Empty string when tracing is not configured.

topic

topic: string

The worker topic that routed this invocation. Matches the topic passed to Virtual.cron() or Virtual.connect().

traceId

traceId: string

OpenTelemetry trace ID propagated from the originating workflow. Empty string when tracing is not configured.

workflowId

workflowId: string

Workflow / job ID. For cron callbacks this is the id from options.id. For Virtual.exec calls this is the auto-generated or user-supplied job identifier.

workflowName

workflowName: string

Internal workflow name (the graph subscription topic, e.g. hmsh.cron or hmsh.call).

Settings

Member Visibility

On This Page

Properties