@platformatic/runtime 4.0.0-alpha.1 → 4.0.0-alpha.2

package/index.d.ts

@@ -7,10 +7,15 @@ import { JSONSchemaType } from 'ajv'
 import * as colorette from 'colorette'
 import { EventEmitter } from 'node:events'
 import { Logger } from 'pino'
-import { PlatformaticRuntimeConfig } from './config.js'
+import { MetricsOptions, PlatformaticRuntimeConfig } from './config.js'
 
 export type RuntimeConfiguration = Configuration<PlatformaticRuntimeConfig>
 
+export interface MetricsConfigUpdateResult {
+  success: boolean
+  config: MetricsOptions
+}
+
 export type ApplicationCommandContext = {
   colorette: typeof colorette
   parseArgs: typeof parseArgs
@@ -40,6 +45,8 @@ export namespace errors {
   export const AddressInUseError: (port: number, firstApplication: string, secondApplication: string) => FastifyError
   export const WorkerAddressInUseError: (port: number, application: string) => FastifyError
   export const RuntimeExitedError: () => FastifyError
+  export const MetricsDisabledError: () => FastifyError
+  export const FailedToUpdateMetricsConfigError: (worker: string, reason: string) => FastifyError
   export const UnknownRuntimeAPICommandError: (command: string) => FastifyError
   export const ApplicationNotFoundError: (id: string) => FastifyError
   export const ApplicationNotStartedError: (id: string) => FastifyError
@@ -419,6 +426,7 @@ export declare class Runtime extends EventEmitter {
   getApplicationOpenapiSchema (id: string): Promise<unknown>
   getApplicationGraphqlSchema (id: string): Promise<unknown>
   getMetrics (format?: string): Promise<{ metrics: unknown }>
+  updateMetricsConfig (metricsConfig: Partial<MetricsOptions>): Promise<MetricsConfigUpdateResult>
   /**
    * Returns the current shared context. Synchronous on the main thread.
    * Do not mutate it in place — use `updateSharedContext()` so changes are

package/lib/errors.js

@@ -81,6 +81,11 @@ export const FailedToRetrieveMetricsError = createError(
   `${ERROR_PREFIX}_FAILED_TO_RETRIEVE_METRICS`,
   'Failed to retrieve metrics for application with id "%s": %s'
 )
+export const FailedToUpdateMetricsConfigError = createError(
+  `${ERROR_PREFIX}_FAILED_TO_UPDATE_METRICS_CONFIG`,
+  'Failed to update metrics configuration on worker "%s": %s'
+)
+export const MetricsDisabledError = createError(`${ERROR_PREFIX}_METRICS_DISABLED`, 'Metrics are disabled.', 501)
 export const FailedToRetrieveHealthError = createError(
   `${ERROR_PREFIX}_FAILED_TO_RETRIEVE_HEALTH`,
   'Failed to retrieve health for application with id "%s": %s'

package/lib/management-api.js

@@ -3,11 +3,13 @@ import fastifyWebsocket from '@fastify/websocket'
 import {
   applications as applicationSchema,
   createDirectory,
+  createValidator,
   createSharedTemporaryDirectory,
   kMetadata,
   safeRemove,
   validate
 } from '@platformatic/foundation'
+import { schemaComponents } from '@platformatic/foundation/schema'
 import fastify from 'fastify'
 import { chmod } from 'node:fs/promises'
 import { platform, tmpdir } from 'node:os'
@@ -16,6 +18,7 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { createWebSocketStream } from 'ws'
 import { prepareAddedApplications } from './config.js'
 import { readMemory } from './memory.js'
+import { MetricsDisabledError } from './errors.js'
 
 const PLATFORMATIC_TMP_DIR = join(tmpdir(), 'platformatic', 'runtimes')
 
@@ -303,19 +306,31 @@ export async function managementApiPlugin (app, opts) {
     return reply
   })
 
+  const metricsSchema = schemaComponents.runtimeProperties.metrics.anyOf[1]
+  app.patch('/metrics', {
+    schema: {
+      body: {
+        ...metricsSchema,
+        minProperties: 1,
+        properties: { ...metricsSchema.properties, enabled: { type: 'boolean' } }
+      }
+    },
+    // A patch must not inject defaults, coerce values, or silently discard unknown options.
+    validatorCompiler: ({ schema }) => createValidator(schema, {
+      useDefaults: false,
+      coerceTypes: false,
+      removeAdditional: false
+    }, { root: runtime.getRuntimeConfig(true)[kMetadata].root })
+  }, async req => runtime.updateMetricsConfig(req.body))
+
   app.get('/metrics', quiet, async (req, reply) => {
     // The live read: this needs one boolean, and the public getter builds a frozen snapshot of the
     // whole configuration -- which is the right shape to hand a consumer and the wrong one to pay
     // for on a scrape.
     const config = runtime.getRuntimeConfig(true)
 
-    if (config.metrics?.enabled === false) {
-      reply.code(501)
-      return {
-        statusCode: 501,
-        error: 'Not Implemented',
-        message: 'Metrics are disabled.'
-      }
+    if (config.metrics === false || config.metrics?.enabled === false) {
+      throw new MetricsDisabledError()
     }
 
     const accepts = req.accepts()

package/lib/runtime.js

@@ -13,11 +13,13 @@ import {
 import { getExecutable } from '@platformatic/globals'
 import { ITC } from '@platformatic/itc'
 import {
+  clearRegistry,
   collectProcessMetrics,
   client as metricsClient,
   openTelemetryITCMessage
 } from '@platformatic/metrics'
 import fastify from 'fastify'
+import { randomUUID } from 'node:crypto'
 import { EventEmitter, once } from 'node:events'
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -25,11 +27,11 @@ import { STATUS_CODES } from 'node:http'
 import { createRequire } from 'node:module'
 import { availableParallelism } from 'node:os'
 import { basename, dirname, isAbsolute, join } from 'node:path'
-import { randomUUID } from 'node:crypto'
 import { Readable } from 'node:stream'
 import { finished } from 'node:stream/promises'
 import { setImmediate as immediate, setTimeout as sleep } from 'node:timers/promises'
 import { pathToFileURL } from 'node:url'
+import { isDeepStrictEqual } from 'node:util'
 import { Worker } from 'node:worker_threads'
 import SonicBoom from 'sonic-boom'
 import { Agent, request, interceptors as undiciInterceptors } from 'undici'
@@ -37,7 +39,6 @@ import { createCoordinator, createInterceptor } from 'undici-thread-interceptor'
 import { pprofCapturePreloadPath } from './config.js'
 import {
   AddressInUseError,
-  WorkerAddressInUseError,
   ApplicationAlreadyStartedError,
   ApplicationNotFoundError,
   ApplicationNotStartedError,
@@ -48,16 +49,19 @@ import {
   FailedToLoadExtensionError,
   FailedToStartExtensionError,
   FailedToStopExtensionError,
+  FailedToUpdateMetricsConfigError,
   InvalidArgumentError,
   InvalidExtensionError,
   LastProfileTimeoutError,
   MessagingError,
   MetricFamilyCollisionError,
+  MetricsDisabledError,
   MissingPprofCapture,
   MixedServingStateError,
   ReservedITCHandlerNameError,
   RuntimeAbortedError,
   RuntimeExtensionBuildAlreadyCalledError,
+  WorkerAddressInUseError,
   WorkerNotFoundError
 } from './errors.js'
 import { abstractLogger, createLogger } from './logger.js'
@@ -65,12 +69,12 @@ import { startManagementApi } from './management-api.js'
 import { createManagementHandlers } from './management-handlers.js'
 import { OpenTelemetryMetricsForwarder } from './opentelemetry-metrics.js'
 import { createChannelCreationHook, createTargetPermissionHook } from './policies.js'
+import { PredictiveWorkersScaler } from './predictive-worker-scaler.js'
 import { startHealthProbesServer, startPrometheusServer } from './prom-server.js'
 import { startScheduler } from './scheduler.js'
 import { createSharedStore } from './shared-http-cache.js'
 import { topologicalLevels, topologicalSort } from './utils.js'
 import { version } from './version.js'
-import { PredictiveWorkersScaler } from './predictive-worker-scaler.js'
 import { HealthSignalsQueue } from './worker/health-signals.js'
 import { sendMultipleViaITC, sendViaITC, waitEventFromITC } from './worker/itc.js'
 import { RoundRobinMap } from './worker/round-robin-map.js'
@@ -81,20 +85,20 @@ import {
   kHealthCheckTimer,
   kId,
   kIsSubprocessHost,
-  kSubprocessPid,
   kITC,
   kLastHealthCheckELU,
   kStderrMarker,
+  kSubprocessPid,
   kWorkerExitCode,
   kWorkerHealthSignals,
   kWorkerId,
   kWorkerPortOffset,
-  kWorkerServerOptions,
-  kWorkerUrl,
   kWorkersBroadcast,
+  kWorkerServerOptions,
   kWorkerStartAborted,
   kWorkerStartTime,
-  kWorkerStatus
+  kWorkerStatus,
+  kWorkerUrl
 } from './worker/symbols.js'
 
 const kWorkerFile = join(import.meta.dirname, 'worker/main.js')
@@ -268,6 +272,8 @@ export class Runtime extends EventEmitter {
   #healthProbesServer
   #metricsServersInitialized
   #metricsServersStartPromise
+  #metricsConfigUpdatePromise
+  #metricsConfigUpdateFailed
   #opentelemetryMetricsForwarder
   #inspectorServer
   #metricsLabelName
@@ -353,6 +359,9 @@ export class Runtime extends EventEmitter {
     this.#extensions = []
     this.#metricsServersInitialized = false
     this.#metricsServersStartPromise = null
+    this.#metricsConfigUpdatePromise = Promise.resolve()
+    this.#metricsConfigUpdateFailed = false
+    this.#processMetricsRegistry = null
     this.#extensionsWantHealthMetrics = false
     this.#extensionReadinessChecks = new Map()
     this.#extensionLivenessChecks = new Map()
@@ -406,7 +415,9 @@ export class Runtime extends EventEmitter {
       this.#managementApi = await startManagementApi(this, config.managementApi)
     }
 
-    await this.#startOpenTelemetryMetricsForwarder(config.metrics?.opentelemetry)
+    if (config.metrics && config.metrics.enabled !== false) {
+      await this.#startOpenTelemetryMetricsForwarder(config.metrics.opentelemetry)
+    }
 
     this.#createWorkersBroadcastChannel()
 
@@ -611,7 +622,7 @@ export class Runtime extends EventEmitter {
 
     // Clean up process metrics registry
     if (this.#processMetricsRegistry) {
-      this.#processMetricsRegistry.clear()
+      clearRegistry(this.#processMetricsRegistry)
       this.#processMetricsRegistry = null
     }
 
@@ -1406,7 +1417,8 @@ export class Runtime extends EventEmitter {
   }
 
   /**
-   * Updates the metrics configuration at runtime without restarting the runtime or workers.
+   * Merges top-level metrics options without restarting the runtime or workers.
+   * Nested objects are replaced when supplied. Identical successful updates are no-ops.
    *
    * This method allows you to:
    * - Enable or disable metrics collection
@@ -1425,51 +1437,103 @@ export class Runtime extends EventEmitter {
    * await runtime.updateMetricsConfig({ enabled: false })
    */
   async updateMetricsConfig (metricsConfig) {
-    if (this.#prometheusServer) {
-      await this.#prometheusServer.close()
-      this.#prometheusServer = null
-    }
+    // Serialize changes because they share listeners and worker registries.
+    const previousUpdate = this.#metricsConfigUpdatePromise
+    const { promise, resolve } = Promise.withResolvers()
+    this.#metricsConfigUpdatePromise = promise
+    await previousUpdate
 
-    if (this.#healthProbesServer) {
-      await this.#healthProbesServer.close()
-      this.#healthProbesServer = null
-    }
+    try {
+      const currentConfig = this.#config.metrics
+      const previousConfig = typeof currentConfig === 'boolean' ? { enabled: currentConfig } : (currentConfig ?? {})
+      metricsConfig = { ...previousConfig, ...metricsConfig }
 
-    this.#metricsServersInitialized = false
+      // An omitted enabled option already means enabled for an object configuration.
+      const previousOptions = { ...previousConfig, enabled: previousConfig.enabled !== false }
+      const nextOptions = { ...metricsConfig, enabled: metricsConfig.enabled !== false }
+      if (!this.#metricsConfigUpdateFailed && isDeepStrictEqual(previousOptions, nextOptions)) {
+        this.#config.metrics = metricsConfig
+        return { success: true, config: structuredClone(metricsConfig) }
+      }
 
-    if (this.#opentelemetryMetricsForwarder) {
-      await this.#opentelemetryMetricsForwarder.close()
-      this.#opentelemetryMetricsForwarder = null
-    }
+      // Failed updates can be retried even when the main-thread configuration already changed.
+      this.#metricsConfigUpdateFailed = true
 
-    this.#config.metrics = metricsConfig
-    this.#metricsLabelName = metricsConfig?.applicationLabel || 'applicationId'
+      if (this.#metricsServersStartPromise) {
+        await this.#metricsServersStartPromise
+      }
 
-    // Allow extension health routes to be re-applied on the restarted servers.
-    for (const entry of this.#extensionHealthRoutes) {
-      entry.applied = false
-    }
+      if (this.#prometheusServer) {
+        await this.#prometheusServer.close()
+        this.#prometheusServer = null
+      }
 
-    await this.#ensureMetricsServersStarted()
+      if (this.#healthProbesServer) {
+        await this.#healthProbesServer.close()
+        this.#healthProbesServer = null
+      }
 
-    await this.#startOpenTelemetryMetricsForwarder(metricsConfig?.opentelemetry)
+      this.#metricsServersInitialized = false
 
-    const promises = []
-    for (const worker of this.#workers.values()) {
-      if (worker[kWorkerStatus] === 'started') {
-        promises.push(sendViaITC(worker, 'updateMetricsConfig', metricsConfig))
+      if (this.#opentelemetryMetricsForwarder) {
+        await this.#opentelemetryMetricsForwarder.close()
+        this.#opentelemetryMetricsForwarder = null
       }
-    }
 
-    const results = await Promise.allSettled(promises)
-    for (const result of results) {
-      if (result.status === 'rejected') {
-        this.logger.error({ err: result.reason }, 'Cannot update metrics config on worker')
+      this.#config.metrics = metricsConfig
+      this.#metricsLabelName = metricsConfig?.applicationLabel || 'applicationId'
+
+      if (metricsConfig.enabled === false) {
+        if (this.#processMetricsRegistry) {
+          clearRegistry(this.#processMetricsRegistry)
+          this.#processMetricsRegistry = null
+        }
+      } else if (!this.#processMetricsRegistry) {
+        this.#processMetricsRegistry = new metricsClient.Registry()
+        collectProcessMetrics(this.#processMetricsRegistry)
       }
-    }
 
-    this.logger.info({ metricsConfig }, 'Metrics configuration updated')
-    return { success: true, config: metricsConfig }
+      // Allow extension health routes to be re-applied on the restarted servers.
+      for (const entry of this.#extensionHealthRoutes) {
+        entry.applied = false
+      }
+
+      await this.#ensureMetricsServersStarted()
+
+      if (metricsConfig.enabled !== false) {
+        await this.#startOpenTelemetryMetricsForwarder(metricsConfig.opentelemetry)
+      }
+
+      const promises = []
+      for (const worker of this.#workers.values()) {
+        if (worker[kWorkerStatus] === 'started') {
+          promises.push(
+            sendViaITC(worker, 'updateMetricsConfig', metricsConfig).catch(err => {
+              throw new FailedToUpdateMetricsConfigError(worker[kFullId], err.message)
+            })
+          )
+        }
+      }
+
+      const results = await Promise.allSettled(promises)
+      for (const result of results) {
+        if (result.status === 'rejected') {
+          this.logger.error({ err: result.reason }, 'Cannot update metrics config on worker')
+        }
+      }
+
+      const failure = results.find(result => result.status === 'rejected')
+      if (failure) {
+        throw failure.reason
+      }
+
+      this.#metricsConfigUpdateFailed = false
+      this.logger.info('Metrics configuration updated')
+      return { success: true, config: structuredClone(metricsConfig) }
+    } finally {
+      // Failed and no-op updates must also release the next queued request.
+      resolve()
+    }
   }
 
   async #ensureMetricsServersStarted () {
@@ -1895,7 +1959,7 @@ export class Runtime extends EventEmitter {
 
   async getMetrics (format = 'json') {
     if (this.#config.metrics === false || this.#config.metrics?.enabled === false) {
-      throw new Error('Metrics are disabled')
+      throw new MetricsDisabledError()
     }
 
     let metrics = null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.2",
   "description": "Platformatic runtime",
   "main": "index.js",
   "type": "module",
@@ -48,13 +48,13 @@
     "typescript": "~6.0.3",
     "undici-oidc-interceptor": "^0.9.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/db": "4.0.0-alpha.1",
-    "@platformatic/gateway": "4.0.0-alpha.1",
-    "@platformatic/node": "4.0.0-alpha.1",
-    "@platformatic/service": "4.0.0-alpha.1",
-    "@platformatic/sql-graphql": "4.0.0-alpha.1",
-    "@platformatic/wattpm-pprof-capture": "4.0.0-alpha.1",
-    "@platformatic/sql-mapper": "4.0.0-alpha.1"
+    "@platformatic/node": "4.0.0-alpha.2",
+    "@platformatic/service": "4.0.0-alpha.2",
+    "@platformatic/sql-graphql": "4.0.0-alpha.2",
+    "@platformatic/db": "4.0.0-alpha.2",
+    "@platformatic/gateway": "4.0.0-alpha.2",
+    "@platformatic/sql-mapper": "4.0.0-alpha.2",
+    "@platformatic/wattpm-pprof-capture": "4.0.0-alpha.2"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -86,13 +86,13 @@
     "undici": "^8.5.0",
     "undici-thread-interceptor": "^2.2.0",
     "ws": "^8.16.0",
-    "@platformatic/basic": "4.0.0-alpha.1",
-    "@platformatic/foundation": "4.0.0-alpha.1",
-    "@platformatic/generators": "4.0.0-alpha.1",
-    "@platformatic/itc": "4.0.0-alpha.1",
-    "@platformatic/metrics": "4.0.0-alpha.1",
-    "@platformatic/globals": "4.0.0-alpha.1",
-    "@platformatic/tracing": "4.0.0-alpha.1"
+    "@platformatic/basic": "4.0.0-alpha.2",
+    "@platformatic/foundation": "4.0.0-alpha.2",
+    "@platformatic/globals": "4.0.0-alpha.2",
+    "@platformatic/itc": "4.0.0-alpha.2",
+    "@platformatic/generators": "4.0.0-alpha.2",
+    "@platformatic/metrics": "4.0.0-alpha.2",
+    "@platformatic/tracing": "4.0.0-alpha.2"
   },
   "engines": {
     "node": ">=24.20.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/4.0.0-alpha.1.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/4.0.0-alpha.2.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",