feat(metrics): add UpDownCounter metric instrument type with replay-safe semantics

[gibbonjj]

Summary

• Adds UpDownCounter metric instrument type to the TypeScript SDK, enabling tracking of inflight/active counts with signed deltas
• Bridges through NAPI to the Rust Core SDK's UpDownCounter (i64) — depends on feat(metrics): add UpDownCounter metric instrument type sdk-core#1180
• Replay-safe by design: correctly handles cache eviction and worker restarts without double-counting or negative drift
• Full support across runtime, workflow sandbox, and worker sink layers

Design

UpDownCounter metrics use in-process state (Prometheus IntGaugeVec) that doesn't survive process restarts, but Temporal workflows do — they replay on a new worker and continue executing. A naive callDuringReplay: false causes the metric to go negative (decrement fires on a new process that never saw the increment). A naive callDuringReplay: true causes double-counting on cache eviction (the increment is still in process memory and replay re-increments).

The solution uses a net-value tracking approach:

1. Workflow sandbox: WorkflowMetricUpDownCounter tracks its cumulative net value per tag combination and always emits the absolute net value to the sink — no isReplaying guard. On replay, the sandbox starts fresh and rebuilds the correct net value from the replayed add() calls.

2. Worker sink: callDuringReplay: true. Tracks per-workflow contributions in a Map<key, TrackedContribution>. On each call, computes delta = receivedNetValue - previouslyTrackedNetValue and applies only the delta to the real metric. This makes it idempotent — replaying the same net value produces delta=0.

3. Eviction cleanup: When a workflow is evicted (cache pressure, completion, or shutdown), cleanupWorkflow(runId) undoes all tracked contributions for that workflow. The metric only reflects workflows actively cached on this worker.

Scenario	Replay emits netValue=1	Sink has prior tracking?	Delta applied
Normal execution	First time	No (0)	+1 ✓
Cache eviction, same process	Rebuilt via replay	Yes (1)	0 ✓
Worker restart, new process	Rebuilt via replay	No (0)	+1 ✓

Additional design decisions:

• Singleton per metric name per workflow via WeakMap<Activator>, following OTel conventions (same name = same instrument). Prevents incorrect net-value tracking when multiple instances share a name.
• Memory: ~100-200 bytes per entry, bounded by maxCachedWorkflows. Cleaned up on eviction.

Changes

• Common types (packages/common/src/metrics.ts): MetricUpDownCounter interface, MetricKind updated, NoopMetricMeter, MetricUpDownCounterWithComposedTags
• NAPI bridge (packages/core-bridge/src/metrics.rs): UpDownCounter struct, new_metric_up_down_counter, add_metric_up_down_counter_value (casts f64 → i64), buffered metrics MetricKind::UpDownCounter
• Native declarations (packages/core-bridge/ts/native.ts): TS declarations for bridge functions, BufferedMetricKind updated
• Runtime (packages/worker/src/runtime-metrics.ts): RuntimeMetricUpDownCounter — no non-negative check (unlike Counter)
• Workflow (packages/workflow/src/metrics.ts): WorkflowMetricUpDownCounter with net-value tracking, singleton enforcement, always emits (no replay skip)
• Worker sink (packages/worker/src/workflow/metrics.ts): Per-workflow delta tracking, callDuringReplay: true, cleanupWorkflow() for eviction, MetricSinkWithCleanup return type
• Worker options (packages/worker/src/worker-options.ts): Wires cleanupWorkflowMetrics through CompiledWorkerOptions
• Worker (packages/worker/src/worker.ts): Calls cleanup on both eviction paths (eviction-only activation and eviction-with-jobs)

Usage

const inflight = metricMeter.createUpDownCounter('inflight_requests');
inflight.add(1);   // operation started
inflight.add(-1);  // operation completed

Depends on

• feat(metrics): add UpDownCounter metric instrument type sdk-core#1180

Test plan

• Bridge-level test: add(1) + add(1) + add(-1) → Prometheus shows 1
• Tags composition test with labels
• Workflow metric test across replay boundary (2 workflows: add(1) before checkpoint, add(-1) after → net 0)
• Workflow tags test with withTags() composition
• Buffered metrics test: verifies kind: 'up_down_counter', valueType: 'int', positive and negative values
• Sink unit tests (13 tests): normal inc/dec, multi-workflow tracking, cleanup on eviction, cache eviction + replay, worker restart simulation, different tags, idempotent replay, negative values, full lifecycle

[gibbonjj]

@Sushisource, after merging https://github.com/temporalio/sdk-core/pull/1180...can i get 👀 on this when you get a chance 🙏 . let me know if you agree with this approach and can start implementing the other lang sdks

[chris-olszewski]

@gibbonjj Could you please update the sdk-core submodule to include your changes from temporalio/sdk-core#1180? cd packages/core-bridge/sdk-core && git pull origin master

[gibbonjj]

@gibbonjj Could you please update the sdk-core submodule to include your changes from temporalio/sdk-core#1180? cd packages/core-bridge/sdk-core && git pull origin master

Done

[mjameswh]

Thanks, @gibbonjj. That's certainly a pertinent feature addition.

I have to admit however that I'm concerned by how invasive this PR turns out to be. I'm definitely not comfortable with some of the changes I see, notably how the tracking of workflow's emitted counters is implemented. I also wonder if we might need to similarly track counters emitted by activities.

To make the review process easier on all of us, I'd suggest we break this effort into 2 or 3 distinct PRs:

1. Add support for UpDownCounter to Buffered Metrics.
2. Add support for UpDownCounter to RuntimeMetricMeter, without support on workflow and activities meters (i.e. make the create method optional on the MetricMeter interface).
3. Add support for tracking/automatic cancellation of UpDownCounter, and expose UpDownCounter on workflow and activity context meters.

1 and 2 can maybe be done together if they contain nothing controversial. Step 3 will be a distinct PR, and will likely need a few rounds to get the design straighten.

Does that seem reasonable to you?