@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/diagnostics/message-flow.js

@@ -9,7 +9,10 @@ const api_1 = require("@opentelemetry/api");
 const api_logs_1 = require("@opentelemetry/api-logs");
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const dispatch_error_details_1 = require("./dispatch-error-details");
 const flow_context_1 = require("./flow-context");
+const MESSAGE_FLOW_EVENT_ID = 'zlink.message_flow';
+const DISPATCH_ERROR_EVENT_ID = 'zlink.dispatch_error';
 exports.DEFAULT_ZLINK_DIAGNOSTICS = {
     messageFlow: 'errors',
     sampleRate: 1,
@@ -17,7 +20,6 @@ exports.DEFAULT_ZLINK_DIAGNOSTICS = {
 };
 const telemetryLogger = api_logs_1.logs.getLogger('@zlink-systems/framework');
 const telemetryTracer = api_1.trace.getTracer('@zlink-systems/framework');
-const ERROR_MESSAGE_MAX_LENGTH = 512;
 let diagnosticsGeneration = 0n;
 function effectiveMessageFlow(ctx) {
     return ctx.liveMode.mode;
@@ -162,12 +164,12 @@ class ZLinkMessageFlowTracer {
     }
     publishToLogger(record) {
         try {
-            const severityNumber = record.eventId === 'zlink.dispatch_error' ? api_logs_1.SeverityNumber.ERROR : api_logs_1.SeverityNumber.INFO;
+            const severityNumber = record.eventId === DISPATCH_ERROR_EVENT_ID ? api_logs_1.SeverityNumber.ERROR : api_logs_1.SeverityNumber.INFO;
             telemetryLogger.emit({
                 eventName: record.eventId,
                 timestamp: record.timestamp,
                 severityNumber,
-                severityText: record.eventId === 'zlink.dispatch_error' ? 'ERROR' : 'INFO',
+                severityText: record.eventId === DISPATCH_ERROR_EVENT_ID ? 'ERROR' : 'INFO',
                 body: structuredLogBody(record),
                 attributes: structuredLogAttributes(record)
             });
@@ -181,7 +183,7 @@ class ZLinkMessageFlowTracer {
             const span = telemetryTracer.startSpan(record.eventId, {
                 attributes: traceAttributes(record)
             });
-            if (record.eventId === 'zlink.dispatch_error') {
+            if (record.eventId === DISPATCH_ERROR_EVENT_ID) {
                 span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: record.reason });
             }
             span.end();
@@ -201,22 +203,11 @@ class ZLinkMessageFlowTracer {
     }
 }
 exports.ZLinkMessageFlowTracer = ZLinkMessageFlowTracer;
-/**
- * Spec 27 §3 defines the flow_origin value set as lowercase
- * (`inbound|timer|application|lifecycle`); every language emits these exact
- * strings so records remain comparable across runtimes (spec 26 §3.1).
- */
-const FLOW_ORIGIN_TELEMETRY_VALUES = {
-    Inbound: 'inbound',
-    Timer: 'timer',
-    Application: 'application',
-    Lifecycle: 'lifecycle'
-};
 function toTelemetryRecord(flow, messageSizeBytes, durationSeconds) {
     return {
         eventId: flow.outcome === ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Error
-            ? 'zlink.dispatch_error'
-            : 'zlink.message_flow',
+            ? DISPATCH_ERROR_EVENT_ID
+            : MESSAGE_FLOW_EVENT_ID,
         timestamp: new Date(),
         phase: messageFlowPhase(flow.outcome),
         outcome: flow.result ?? messageFlowOutcome(flow.outcome),
@@ -234,7 +225,7 @@ function toTelemetryRecord(flow, messageSizeBytes, durationSeconds) {
         targetRid: flow.targetRid,
         serverRid: flow.serverRid,
         flowId: flow.flowId,
-        flowOrigin: flow.flowOrigin === undefined ? undefined : FLOW_ORIGIN_TELEMETRY_VALUES[flow.flowOrigin],
+        flowOrigin: flow.flowOrigin === undefined ? undefined : flow_context_1.FLOW_ORIGIN_VALUES[flow.flowOrigin],
         spotId: flow.spotId,
         instanceSpotType: flow.instanceSpotType,
         activationState: flow.activationState,
@@ -429,7 +420,7 @@ function hashFlowId(flowId) {
     return hash >>> 0;
 }
 function boundedText(value) {
-    return value === undefined ? undefined : value.slice(0, ERROR_MESSAGE_MAX_LENGTH);
+    return value === undefined ? undefined : value.slice(0, dispatch_error_details_1.ERROR_MESSAGE_MAX_LENGTH);
 }
 function toSnakeCase(value) {
     return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);

package/dist/runtime/diagnostics/runtime-metrics.d.ts

@@ -1,4 +1,6 @@
-import type { ZLinkHostCapacityStatus, ZLinkMeterProvider, ZLinkMetricAttributes } from '../../contracts';
+import { type ZLinkHostCapacityStatus, type ZLinkMeterProvider, type ZLinkMetricAttributes } from '../../contracts';
+export declare const MILLISECONDS_PER_SECOND = 1000;
+export declare const NANOSECONDS_PER_SECOND = 1000000000;
 export interface ZLinkRuntimeMetricCapacity {
     readonly active: number;
     readonly reserved: number;
@@ -48,41 +50,102 @@ export interface ZLinkRuntimeMetricOperation {
 export interface ZLinkRelocationMetricOperation extends ZLinkRuntimeMetricOperation {
     recordBytes(bytes: number): void;
 }
+export declare const METRIC_NAMES: Readonly<{
+    readonly StreamConnectionsOpened: "zlink.stream.connections.opened";
+    readonly StreamConnectionsClosed: "zlink.stream.connections.closed";
+    readonly MeshNodeChannelSelectionFailures: "zlink.mesh_node.channel.selection_failures";
+    readonly MeshNodeRequestTimeouts: "zlink.mesh_node.request.timeouts";
+    readonly MeshNodeMessagesDropped: "zlink.mesh_node.messages.dropped";
+    readonly RelocationStarted: "zlink.relocation.started";
+    readonly RelocationCompleted: "zlink.relocation.completed";
+    readonly RelocationCutoverTimeout: "zlink.relocation.cutover_timeout";
+    readonly InstanceSpotActivations: "zlink.instance_spot.activations";
+    readonly InstanceSpotClaimConflicts: "zlink.instance_spot.claim.conflicts";
+    readonly InstanceSpotTakeovers: "zlink.instance_spot.takeovers";
+    readonly LocationStoreErrors: "zlink.location.store.errors";
+    readonly LocationOwnerLeaseRenewFailures: "zlink.location.owner_lease.renew.failures";
+    readonly ObservabilityEventsOverflow: "zlink.observability.events.overflow";
+    readonly HostRelocationBlocked: "zlink.host.relocation.blocked";
+    readonly HostShutdownForced: "zlink.host.shutdown.forced";
+    readonly StreamConnectionsActive: "zlink.stream.connections.active";
+    readonly SpotCount: "zlink.spot.count";
+    readonly ActorCount: "zlink.actor.count";
+    readonly MeshNodeRequestsInflight: "zlink.mesh_node.requests.inflight";
+    readonly MeshNodeRequestDuration: "zlink.mesh_node.request.duration";
+    readonly RelocationDuration: "zlink.relocation.duration";
+    readonly RelocationBytes: "zlink.relocation.bytes";
+    readonly RelocationInterruption: "zlink.relocation.interruption";
+    readonly RelocationTargetResume: "zlink.relocation.target_resume";
+    readonly RelocationRouteConvergence: "zlink.relocation.route_convergence";
+    readonly InstanceSpotActivationDuration: "zlink.instance_spot.activation.duration";
+    readonly LocationOwnerLeaseRenewLateness: "zlink.location.owner_lease.renew.lateness";
+    readonly HostRelocationDuration: "zlink.host.relocation.duration";
+    readonly HostShutdownDuration: "zlink.host.shutdown.duration";
+    readonly MeshNodePeersConfigured: "zlink.mesh_node.peers.configured";
+    readonly MeshNodePeersConnected: "zlink.mesh_node.peers.connected";
+    readonly MeshNodePeersReady: "zlink.mesh_node.peers.ready";
+    readonly MeshNodeChannelsReadyMembers: "zlink.mesh_node.channels.ready_members";
+    readonly ObjectCapacityActive: "zlink.object.capacity.active";
+    readonly ObjectCapacityReserved: "zlink.object.capacity.reserved";
+    readonly ObjectCapacityLimit: "zlink.object.capacity.limit";
+    readonly SpotTypeCapacityActive: "zlink.spot.type.capacity.active";
+    readonly SpotTypeCapacityReserved: "zlink.spot.type.capacity.reserved";
+    readonly SpotTypeCapacityLimit: "zlink.spot.type.capacity.limit";
+    readonly ObjectActivationActive: "zlink.object.activation.active";
+    readonly ObjectActivationLimit: "zlink.object.activation.limit";
+    readonly InstanceSpotPendingMessages: "zlink.instance_spot.pending.messages";
+    readonly InstanceSpotPendingBytes: "zlink.instance_spot.pending.bytes";
+    readonly HostState: "zlink.host.state";
+    readonly HostCoreHwmEffectiveBudget: "zlink.host.core_hwm.effective_budget";
+    readonly HostCoreHwmApplied: "zlink.host.core_hwm.applied";
+    readonly HostCoreHwmAccounted: "zlink.host.core_hwm.accounted";
+    readonly HostCoreHwmCompletionAccounted: "zlink.host.core_hwm.completion_accounted";
+    readonly HostCoreHwmBlockedRatio: "zlink.host.core_hwm.blocked_ratio";
+    readonly HostApplicationJobQueueLimit: "zlink.host.application_job_queue.limit";
+    readonly HostApplicationJobQueueJobs: "zlink.host.application_job_queue.jobs";
+    readonly HostApplicationJobQueueCapacityWaiters: "zlink.host.application_job_queue.capacity_waiters";
+    readonly HostApplicationJobQueuePressureState: "zlink.host.application_job_queue.pressure_state";
+    readonly HostApplicationJobQueuePauseDuration: "zlink.host.application_job_queue.pause_duration";
+    readonly HostApplicationJobQueueCapacityWaits: "zlink.host.application_job_queue.capacity_waits";
+    readonly HostApplicationJobQueueCapacityWaitDuration: "zlink.host.application_job_queue.capacity_wait_duration";
+    readonly HostApplicationJobQueuePressureTransitions: "zlink.host.application_job_queue.pressure_transitions";
+    readonly HostApplicationJobQueueFlowStateConfigFailures: "zlink.host.application_job_queue.flow_state_config_failures";
+}>;
 declare const COUNTERS: Readonly<{
-    readonly 'zlink.stream.connections.opened': "{connection}";
-    readonly 'zlink.stream.connections.closed': "{connection}";
-    readonly 'zlink.mesh_node.channel.selection_failures': "{failure}";
-    readonly 'zlink.mesh_node.request.timeouts': "{request}";
-    readonly 'zlink.mesh_node.messages.dropped': "{message}";
-    readonly 'zlink.relocation.started': "{relocation}";
-    readonly 'zlink.relocation.completed': "{relocation}";
-    readonly 'zlink.relocation.cutover_timeout': "{fallback}";
-    readonly 'zlink.instance_spot.activations': "{activation}";
-    readonly 'zlink.instance_spot.claim.conflicts': "{claim}";
-    readonly 'zlink.instance_spot.takeovers': "{takeover}";
-    readonly 'zlink.location.store.errors': "{error}";
-    readonly 'zlink.location.owner_lease.renew.failures': "{failure}";
-    readonly 'zlink.observability.events.overflow': "{event}";
-    readonly 'zlink.host.relocation.blocked': "{operation}";
-    readonly 'zlink.host.shutdown.forced': "{operation}";
+    readonly "zlink.stream.connections.opened": "{connection}";
+    readonly "zlink.stream.connections.closed": "{connection}";
+    readonly "zlink.mesh_node.channel.selection_failures": "{failure}";
+    readonly "zlink.mesh_node.request.timeouts": "{request}";
+    readonly "zlink.mesh_node.messages.dropped": "{message}";
+    readonly "zlink.relocation.started": "{relocation}";
+    readonly "zlink.relocation.completed": "{relocation}";
+    readonly "zlink.relocation.cutover_timeout": "{fallback}";
+    readonly "zlink.instance_spot.activations": "{activation}";
+    readonly "zlink.instance_spot.claim.conflicts": "{claim}";
+    readonly "zlink.instance_spot.takeovers": "{takeover}";
+    readonly "zlink.location.store.errors": "{error}";
+    readonly "zlink.location.owner_lease.renew.failures": "{failure}";
+    readonly "zlink.observability.events.overflow": "{event}";
+    readonly "zlink.host.relocation.blocked": "{operation}";
+    readonly "zlink.host.shutdown.forced": "{operation}";
 }>;
 declare const UP_DOWN_COUNTERS: Readonly<{
-    readonly 'zlink.stream.connections.active': "{connection}";
-    readonly 'zlink.spot.count': "{spot}";
-    readonly 'zlink.actor.count': "{actor}";
-    readonly 'zlink.mesh_node.requests.inflight': "{request}";
+    readonly "zlink.stream.connections.active": "{connection}";
+    readonly "zlink.spot.count": "{spot}";
+    readonly "zlink.actor.count": "{actor}";
+    readonly "zlink.mesh_node.requests.inflight": "{request}";
 }>;
 declare const HISTOGRAMS: Readonly<{
-    readonly 'zlink.mesh_node.request.duration': "s";
-    readonly 'zlink.relocation.duration': "s";
-    readonly 'zlink.relocation.bytes': "By";
-    readonly 'zlink.relocation.interruption': "s";
-    readonly 'zlink.relocation.target_resume': "s";
-    readonly 'zlink.relocation.route_convergence': "s";
-    readonly 'zlink.instance_spot.activation.duration': "s";
-    readonly 'zlink.location.owner_lease.renew.lateness': "s";
-    readonly 'zlink.host.relocation.duration': "s";
-    readonly 'zlink.host.shutdown.duration': "s";
+    readonly "zlink.mesh_node.request.duration": "s";
+    readonly "zlink.relocation.duration": "s";
+    readonly "zlink.relocation.bytes": "By";
+    readonly "zlink.relocation.interruption": "s";
+    readonly "zlink.relocation.target_resume": "s";
+    readonly "zlink.relocation.route_convergence": "s";
+    readonly "zlink.instance_spot.activation.duration": "s";
+    readonly "zlink.location.owner_lease.renew.lateness": "s";
+    readonly "zlink.host.relocation.duration": "s";
+    readonly "zlink.host.shutdown.duration": "s";
 }>;
 type CounterName = keyof typeof COUNTERS;
 type UpDownName = keyof typeof UP_DOWN_COUNTERS;