docs(rivetkit): add actor tracing docs

[eersnington]

this stack is a bit chonky to review so I've scoped down a lot of things.

a rundown of what i'm shipping with this otel stack:

• changes to how ray ID gets passed on within guard service
• traces for actions, http handlers and sqlite operations
• traces for actor-to-actor calls
• linked scheduled actions and queue messages
• actor logs with ray and trace IDs (pino)
• otel sdk warnings and errors through from core to pino
• export to an OTLP backend

not within this stack

• workflows support (will be up next if this looks good cause it's another 800+ loc PR)
• rust sdk support
• websocket traces support (req another migration too to ActionRequest type)
• wasm runtime support
• native effect tracing support

and regarding this pr, i'm hosting the docs here (@NathanFlurry made a lot of changes as per our last call). lmk if you're picky about anything and want more things changed.

https://docs-otel-e2e.eers.dev/actors/docs/general/tracing/

diagrams added

notes for @MasterPtato or anyone puling this to staging.
tracing is feature flagged with the traces endpoint env var. if that's not set, it's disabled.

OTEL_SERVICE_NAME=<val>
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318/v1/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf 
# or grpc

you can technically read the "Quickstart" within the docs and should be able to configure it within the cloud. if anything is unclear in that, lmk, I'll fix things up.

and also this #5729 bumps the internal schema version from 1 to 2 to store ray ID and tracecontext to the schedules and queues table.

[eersnington]

Stack for rivet-dev/actors

• #5734 docs(rivetkit): add actor tracing docs 👈
• #5733 feat(rivetkit): forward otel sdk warnings to the pino logger
• #5732 feat(rivetkit): trace actor to actor calls
• #5730 feat(rivetkit-core): trace queue sends and receives
• #5731 feat(rivetkit-core): trace raw http requests
• #5729 feat(rivetkit-core): trace scheduled invocations
• #5726 feat(rivetkit): send trace context from clients
• #5723 feat(rivetkit): pass trace context to js and logs
• #5727 feat(rivetkit): trace sqlite operations
• #5721 feat(rivetkit): trace actor invocations
• #5728 fix(pegboard-gateway): forward request ray id to actors
• #5724 test(rivetkit): let driver runtimes take extra environment
• #5722 fix(rivetkit): disable services in driver test runtimes
• main

Get stack: forklift get 5734
Push local edits: forklift submit
Merge when ready: forklift merge 5734

_{change mqqwnuwl}

[the-company-company]

🟠 2 medium · 🔵 1 low

_{Reviewed commit 5d35d78.}

[claude]

Review (updated for latest push through commit 4d34551)

This is a substantial, well-executed feature. The trace-context propagation logic (invocation to application span to workflow run/step, ray-id handoff via queue messages, otel.status_code/error.type conventions) is careful and consistently applied across the Rust core, NAPI bridge, and TypeScript layers, and it's backed by a genuinely thorough integration test (actor-telemetry.test.ts, the workflow describe block) plus a query-efficiency test for the new _rivet_wf_kv read, per this repo's SQLite testing policy. The workflow trace-context key ([6, 1, 0x15, 5]) correctly reuses the fdb-tuple encoding of 5, which is reserved in workflow-engine/src/keys.ts's KEY_PREFIX, so Core's direct write can't collide with the workflow engine's own KV keys.

Bug: driver.test.ts will throw with the new ActorWorkflowDriver code path

rivetkit-typescript/packages/rivetkit/src/workflow/driver.ts's #untraced helper (added in this PR) now does:

#untraced<T>(run: () => Promise<T>): Promise<T> {
	return this.#runCtx.internalKeepAwake(
		this.#runCtx.run.runOutsideWorkflowSpan(run),
	);
}

get, set, delete, batchDelete, deletePrefix, deleteRange, list, and batch all route through #untraced, so they now dereference this.#runCtx.run.

src/workflow/driver.test.ts (unmodified by this PR) constructs:

const runCtx = {
	sql,
	internalKeepAwake: async <T>(promise: Promise<T>) => await promise,
};
const driver = new ActorWorkflowDriver(actor as never, runCtx as never);

This mock has no run field at all - the as never cast is what lets it slip past the type checker even though RunContext.run: ActorRun is required. The test "delegates actor state and the whole workflow batch to one atomic runtime call" then calls driver.batch(writes) with a non-empty writes array, which will hit #untraced -> this.#runCtx.run.runOutsideWorkflowSpan -> TypeError: Cannot read properties of undefined (reading 'runOutsideWorkflowSpan').

Before this PR, batch() called internalKeepAwake directly on the write promise and never touched runCtx.run, so the test passed. This looks like a genuine regression that CI should catch; the fix is to add run: { runOutsideWorkflowSpan: (body) => body(), startWorkflowSpan: async () => ({ ... }) } (or at least runOutsideWorkflowSpan) to the test's runCtx mock.

Minor / non-blocking observations

• docs-internal/engine/rivetkit-telemetry.md and docs/content/docs/general/tracing.mdx are thorough and the "Gaps"/"Known limitations" sections are honest about what isn't covered yet (WebSocket handlers, .connect() actions starting new traces, wasm). Good practice, nothing to fix.
• WorkflowRunOutcome::is_error() treats Evicted as non-error (otel.status_code = OK), same as Sleeping. That matches the "known limitation" framing (mid-flight interruption isn't a workflow failure), but worth double-checking that's the intended semantics for dashboards/alerting built on this span, since "evicted" sounds alarm-worthy at first glance.
• runOutsideWorkflowSpan's reliance on AsyncLocalStorage.exit() in NapiCoreRuntime.runOutsideActorInvocationContext to keep workflow-history KV writes out of the run's trace is a subtle mechanism (context is captured per-async-resource at creation time, not at the call site). It's exercised by the new driver test ("puts a queue send made inside a step in that step's trace" et al.), so it's not unverified, but it's worth a short inline comment given how easy this pattern is to get subtly wrong in a future refactor.

No security concerns: the new correlation data (ray IDs, W3C trace headers) is documented as "correlation, not identity or authorization," and the data-policy section explicitly excludes SQL text/bindings, actor state, and raw error messages from spans.

[the-company-company]

✅ No issues found

_{Reviewed commit 6c2a881.}

[the-company-company]

🟠 1 medium-severity finding

_{Reviewed commit d18e8f9.}

[the-company-company]

✅ No issues found

_{Reviewed commit 45ae99c.}