workflow 5.0.0-beta.16 → 5.0.0-beta.18

package/docs/api-reference/workflow-api/start.mdx

@@ -103,6 +103,8 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 
 <Callout type="info">
 The `deploymentId` option is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+
+In Worlds without atomic, immutable deployments (such as local development or self-hosted Postgres), there is no notion of multiple deployments to resolve between, so `deploymentId: "latest"` has no effect: the SDK logs a warning and the run targets the current deployment. This means a workflow that opts into `"latest"` on Vercel still runs unchanged in local development.
 </Callout>
 
 <Callout type="warn">

package/docs/api-reference/workflow-next/with-workflow.mdx

@@ -31,8 +31,8 @@ export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 If a package in `serverExternalPackages` contains workflow code (`"use step"`,
 `"use workflow"`, or serialization classes), `withWorkflow()` automatically
 removes it from `serverExternalPackages` for the current build and prints a
-warning. This ensures the package still gets transformed by the Workflow
-compiler. Remove that package from `serverExternalPackages` in your
+warning. Workflow still compiles the package so its directives are transformed.
+Remove that package from `serverExternalPackages` in your
 `next.config` to silence the warning.
 </Callout>
 

package/docs/observability/index.mdx

@@ -42,6 +42,19 @@ npx workflow inspect runs --web
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
+To share a link to a specific run without opening a browser, use the `--url`
+flag. It prints the dashboard deep link to stdout and exits (no browser, no
+local server) — useful for scripts, PR comments, or automation. Add `--json` to
+get `{ "url": "..." }`.
+
+```bash
+# Print the deep-link URL for a run (no browser, no server)
+npx workflow inspect run <run_id> --url
+
+# Vercel runs: add the backend (and --env preview for preview deployments)
+npx workflow inspect run <run_id> --backend vercel --url
+```
+
 ## Backends
 
 The Workflow SDK CLI can inspect data from any [World](/docs/deploying). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the
@@ -67,6 +80,9 @@ When deployed to Vercel, workflow data is [encrypted end-to-end](/docs/how-it-wo
 ## More Observability Features
 
 <Cards>
+    <Card href="/docs/observability/tracing" title="Tracing">
+        Distributed tracing with OpenTelemetry for workflow runs, steps, and queue deliveries.
+    </Card>
     <Card href="/docs/observability/attributes" title="Attributes">
         Attach experimental metadata to workflow runs for observability.
     </Card>

package/docs/observability/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Observability",
-  "pages": ["attributes"]
+  "pages": ["tracing", "attributes"]
 }

package/docs/observability/tracing.mdx

@@ -0,0 +1,106 @@
+---
+title: Tracing
+description: Distributed tracing with OpenTelemetry for workflow runs, steps, and queue deliveries.
+type: guide
+summary: Trace workflow execution end to end with OpenTelemetry.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/observability/attributes
+  - /docs/how-it-works/event-sourcing
+---
+
+The Workflow SDK is instrumented with [OpenTelemetry](https://opentelemetry.io) out of the box. It emits spans for workflow starts, every workflow and step invocation, and the HTTP calls it makes to the workflow backend — and it propagates trace context across queue deliveries so a run remains traceable end to end.
+
+The SDK only depends on the OpenTelemetry **API**, never on an SDK or exporter. If your application does not register an OpenTelemetry SDK, all tracing code is a silent no-op with no overhead and no behavior change.
+
+## Enabling tracing
+
+Register any OpenTelemetry Node SDK in your application. On Vercel with Next.js, the simplest setup is [`@vercel/otel`](https://vercel.com/docs/observability/otel-overview) in `instrumentation.ts`:
+
+```typescript title="instrumentation.ts" lineNumbers
+import { registerOTel } from "@vercel/otel"
+
+export function register() {
+  registerOTel({ serviceName: "my-app" })
+}
+```
+
+No workflow-specific configuration is required. As soon as a tracer provider and propagator are registered, the SDK's spans, context propagation, and span links activate automatically.
+
+## Spans
+
+| Span name | Kind | Emitted when |
+| --- | --- | --- |
+| `workflow.start <name>` | internal | `start()` is called in your application code |
+| `workflow.execute <name>` | consumer (root) | a queue delivery invokes the workflow — replay, orchestration, and inline steps run under it |
+| `step.execute <name>` | internal (inline) / consumer + root (queue-delivered) | a step function executes |
+| `http <method>` | client | the SDK calls the workflow backend (event reads/writes) |
+
+`<name>` is the short function name (for example `processOrder`); the full machine name, including the source module, is available in the `workflow.name` / `step.name` attributes.
+
+## Key attributes
+
+| Attribute | Description |
+| --- | --- |
+| `workflow.run.id` | The run ID (`wrun_...`). Present on every workflow and step span — the primary key for finding all spans of a run. |
+| `workflow.name` | The workflow function name. |
+| `workflow.trace.mode` | The active trace mode (`linked` or `continuous`). |
+| `workflow.trace.propagated` | Whether the invocation received trace context from the queue message. |
+| `workflow.queue.overhead_ms` | Time between the message being enqueued and the handler starting — queue dwell plus any cold start. |
+
+## Trace shape: one trace per invocation
+
+A single workflow run can span hours or days across many separate function invocations: every step completion, `sleep()` wake-up, and retry is a new queue delivery. Stitching all of that into one trace produces giant, slow-loading traces that most tracing backends truncate.
+
+Instead, the SDK creates **one bounded trace per invocation**. Each `workflow.execute` (or background `step.execute`) span starts a new trace root and attaches two **span links**:
+
+- a link to the **enqueue site** — the span that queued the message which triggered this invocation, and
+- a link to the **run origin** — the trace in which `start()` was originally called.
+
+A span link is OpenTelemetry's relationship for "causally related, but in a different trace." It is the standard pattern for asynchronous messaging, where producing and consuming a message can be separated by arbitrary time.
+
+```mermaid
+flowchart LR
+    O["start() request trace"]
+    A["invocation 1"]
+    B["invocation 2"]
+    C["invocation 3 ..."]
+    A -. "link" .-> O
+    B -. "link" .-> O
+    C -. "link" .-> O
+    B -. "link" .-> A
+    C -. "link" .-> B
+
+    style O fill:#a78bfa,stroke:#8b5cf6,color:#000
+```
+
+Each invocation links back to the trace that enqueued it and to the run origin.
+
+To see a whole run, query by attribute rather than by trace ID — for example `workflow.run.id = wrun_...` in your tracing backend — or follow the span links between invocation traces.
+
+## Trace modes
+
+The `WORKFLOW_TRACE_MODE` environment variable controls the shape:
+
+| Mode | Behavior |
+| --- | --- |
+| `linked` (default) | Each invocation is its own trace root with span links to the enqueue site and the run origin. Traces stay small; sampling is decided per invocation. |
+| `continuous` | The run-origin context becomes the **parent** of every invocation, so the entire run shares one trace ID. |
+
+<Callout type="warn">
+This is a behavior change from v4, which always used `continuous`-style tracing. If you have dashboards or queries that assume one trace ID per run, either update them to use `workflow.run.id` and span links, or set `WORKFLOW_TRACE_MODE=continuous` to restore the previous shape. Note that in `linked` mode each invocation root makes its own sampling decision, and the number of root spans increases to one per invocation.
+</Callout>
+
+## Context propagation
+
+When tracing is enabled, the SDK propagates [W3C Trace Context](https://www.w3.org/TR/trace-context/) on its outbound calls:
+
+- **Backend requests** carry `traceparent`, `tracestate`, and `baggage` headers, so backend spans can join your trace.
+- **Queue messages** carry the run-origin trace context in the message payload, and the queue re-delivers the producer's context to the workflow handler, where it becomes the enqueue-site span link.
+- **Baggage** carries `workflow.run_id` and `workflow.name` entries during workflow execution, allowing downstream services you call from steps to tag their own telemetry with the run ID.
+
+<Callout>
+Baggage entries set by your application are propagated as a `baggage` HTTP header on the SDK's backend requests, like any other OpenTelemetry-instrumented HTTP call. Avoid placing sensitive values in baggage.
+</Callout>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.16",
+  "version": "5.0.0-beta.18",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.16",
-    "@workflow/cli": "5.0.0-beta.16",
-    "@workflow/core": "5.0.0-beta.16",
-    "@workflow/errors": "5.0.0-beta.7",
+    "@workflow/astro": "5.0.0-beta.18",
+    "@workflow/cli": "5.0.0-beta.18",
+    "@workflow/core": "5.0.0-beta.18",
+    "@workflow/errors": "5.0.0-beta.8",
     "@workflow/typescript-plugin": "5.0.0-beta.4",
-    "@workflow/utils": "5.0.0-beta.3",
-    "@workflow/next": "5.0.0-beta.16",
-    "@workflow/nest": "5.0.0-beta.16",
-    "@workflow/nitro": "5.0.0-beta.16",
-    "@workflow/nuxt": "5.0.0-beta.16",
-    "@workflow/sveltekit": "5.0.0-beta.16",
-    "@workflow/rollup": "5.0.0-beta.16"
+    "@workflow/utils": "5.0.0-beta.4",
+    "@workflow/next": "5.0.0-beta.18",
+    "@workflow/nest": "5.0.0-beta.18",
+    "@workflow/nitro": "5.0.0-beta.18",
+    "@workflow/nuxt": "5.0.0-beta.18",
+    "@workflow/sveltekit": "5.0.0-beta.18",
+    "@workflow/rollup": "5.0.0-beta.18"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",