feat(core): emit faas.instance span attribute for compute instance identity

Synthesize a per-warm-instance id (cinst_<ulid>) once at module load and emit it as the OTEL faas.instance attribute on the flow and step route spans. Vercel exposes no native per-instance id under Fluid compute, so this lets traces distinguish which compute instance handled each request. Purely additive telemetry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Alex Langenfeld <alex.langenfeld@vercel.com>

Author: alangenfeld

.changeset/faas-instance-span-attr.md

@@ -0,0 +1,5 @@
+---
+'@workflow/core': minor
+---
+
+Emit a `faas.instance` OTEL span attribute (a synthesized per-warm-instance id) on the flow and step route spans, so traces can distinguish which compute instance handled each request.

packages/core/src/runtime.ts

@@ -52,6 +52,7 @@ import {
   handleReplayBudgetExhausted,
   ReplayBudget,
 } from './runtime/replay-budget.js';
+import { COMPUTE_INSTANCE_ID } from './runtime/compute-instance.js';
 import { runIdCreatedAt } from './runtime/run-id-time.js';
 import { executeStep } from './runtime/step-executor.js';
 import { computeStepLatencyTracking } from './runtime/step-latency.js';
@@ -2442,6 +2443,7 @@ export function workflowEntrypoint(
         kind: spanKind,
         attributes: {
           ...Attribute.WorkflowRouteType('flow'),
+          ...Attribute.FaasInstance(COMPUTE_INSTANCE_ID),
           ...Attribute.WorkflowRouteHandlerCached(handlerCached),
           ...Attribute.WorkflowRouteInvocationCount(invocationCount),
           ...Attribute.WorkflowRouteEntrypointAgeMs(

packages/core/src/runtime/compute-instance.ts

@@ -0,0 +1,32 @@
+import { ulid } from 'ulid';
+
+/**
+ * Identifier for the compute instance (the warm serverless instance /
+ * microVM) that this module was loaded into.
+ *
+ * Vercel exposes no native per-instance id under Fluid compute — all
+ * `AWS_LAMBDA_*` env vars (including `AWS_LAMBDA_LOG_STREAM_NAME`) are
+ * blocked — so we synthesize our own once at module load. The value is
+ * therefore:
+ *
+ * - **stable for the life of the warm instance**, and
+ * - **shared across every invocation that instance handles**, including the
+ *   concurrent invocations Fluid compute packs onto a single instance.
+ *
+ * Distinct warm instances (and every cold start) get distinct ids. Both the
+ * flow and step route entrypoints import this module, so any bundles
+ * co-resident on one instance report the same id.
+ *
+ * The value is a prefixed ULID (`cinst_<ulid>`), matching the id convention
+ * used elsewhere (`wrun_`, `step_`, `hook_`, …). Using a ULID means the
+ * timestamp component encodes the instance's birth time, so ids sort
+ * lexicographically by creation — useful for ordering/aging instances and
+ * spotting cold starts in observability tooling.
+ *
+ * Surfaced two ways:
+ * - as a span attribute, and
+ * - persisted on `step_started` events as `computeInstanceId`, so tooling can
+ *   tell which step attempts ran on the same instance vs different instances,
+ *   and within an instance which ran in the same invocation vs different ones.
+ */
+export const COMPUTE_INSTANCE_ID = `cinst_${ulid()}`;

packages/core/src/runtime/step-handler.ts

@@ -62,6 +62,7 @@ import {
   queueMessage,
   withHealthCheck,
 } from './helpers.js';
+import { COMPUTE_INSTANCE_ID } from './compute-instance.js';
 import { safeWaitUntil } from './wait-until.js';
 import { getWorld, getWorldHandlers, type WorldHandlers } from './world.js';
 
@@ -243,6 +244,7 @@ function createStepHandler(namespace?: string) {
             span?.setAttributes({
               ...Attribute.StepName(stepName),
               ...Attribute.StepAttempt(metadata.attempt),
+              ...Attribute.FaasInstance(COMPUTE_INSTANCE_ID),
               // Standard OTEL messaging conventions
               ...Attribute.MessagingSystem('vercel-queue'),
               ...Attribute.MessagingDestinationName(metadata.queueName),

packages/core/src/telemetry/semantic-conventions.ts

@@ -175,6 +175,18 @@ export const WorkflowRouteModuleBodyInitMs = SemanticConvention<number>(
   'workflow.route.module_body_init_ms'
 );
 
+/**
+ * Identifier for the compute instance (warm serverless instance / microVM)
+ * handling this route — the synthesized `COMPUTE_INSTANCE_ID`, stable for the
+ * instance's lifetime and shared across every invocation it serves.
+ *
+ * Uses the OpenTelemetry `faas.instance` convention: "the execution
+ * environment ID as a string, potentially reused for other invocations to the
+ * same function/version." See
+ * https://opentelemetry.io/docs/specs/semconv/attributes-registry/faas/
+ */
+export const FaasInstance = SemanticConvention<string>('faas.instance');
+
 // Step attributes
 
 /** Name of the step function being executed */