@platformatic/runtime 3.59.0 → 3.61.0

package/config.d.ts

@@ -254,7 +254,40 @@ export type PlatformaticRuntimeConfig = {
     bufferPoolSize?: number | string;
     defaultHighWaterMark?: number | string;
   };
-  healthProbes?: boolean | string;
+  healthProbes?:
+    | boolean
+    | string
+    | {
+        enabled?: boolean | string;
+        hostname?: string;
+        port?: number | string;
+        readiness?:
+          | boolean
+          | {
+              endpoint?: string;
+              success?: {
+                statusCode?: number;
+                body?: string;
+              };
+              fail?: {
+                statusCode?: number;
+                body?: string;
+              };
+            };
+        liveness?:
+          | boolean
+          | {
+              endpoint?: string;
+              success?: {
+                statusCode?: number;
+                body?: string;
+              };
+              fail?: {
+                statusCode?: number;
+                body?: string;
+              };
+            };
+      };
   undici?: {
     agentOptions?: {
       [k: string]: unknown;
@@ -413,6 +446,10 @@ export type PlatformaticRuntimeConfig = {
                 body?: string;
               };
             };
+        /**
+         * @deprecated
+         * Deprecated. Health probe timeout configuration is no longer used.
+         */
         healthChecksTimeouts?: number | string;
         plugins?: string[];
         timeout?: number | string;
@@ -447,6 +484,29 @@ export type PlatformaticRuntimeConfig = {
            */
           serviceVersion?: string;
         };
+        /**
+         * Configuration for forwarding user OpenTelemetry metrics to an OTLP endpoint
+         */
+        opentelemetry?: {
+          /**
+           * Enable or disable OpenTelemetry metrics forwarding
+           */
+          enabled?: boolean | string;
+          /**
+           * OTLP metrics endpoint URL (e.g., http://collector:4318/v1/metrics)
+           */
+          endpoint: string;
+          /**
+           * Interval in milliseconds between metric forwards
+           */
+          interval?: number | string;
+          /**
+           * Additional HTTP headers for authentication
+           */
+          headers?: {
+            [k: string]: string;
+          };
+        };
         /**
          * Custom labels to add to HTTP metrics (http_request_all_duration_seconds). Each label extracts its value from an HTTP request header.
          */

package/index.js

@@ -87,7 +87,7 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
   })
 }
 
-export async function loadApplicationsCommands (executableName = '') {
+export async function loadApplicationsCommands (executableName = '', configurationFile = null) {
   const applications = {}
   const commands = {}
   const help = {}
@@ -97,7 +97,7 @@ export async function loadApplicationsCommands (executableName = '') {
     const file = await findRuntimeConfigurationFile(
       abstractLogger,
       process.cwd(),
-      null,
+      configurationFile,
       false,
       false,
       true,

package/lib/errors.js

@@ -39,7 +39,7 @@ export const ApplicationNotFoundError = createError(
 )
 export const WorkerNotFoundError = createError(
   `${ERROR_PREFIX}_WORKER_NOT_FOUND`,
-  'Worker %s of application %s not found. Available applications are: %s'
+  'Worker %s of application %s not found. Available workers are: %s'
 )
 export const ApplicationNotStartedError = createError(
   `${ERROR_PREFIX}_APPLICATION_NOT_STARTED`,

package/lib/management-api.js

@@ -3,11 +3,13 @@ import fastifyWebsocket from '@fastify/websocket'
 import {
   applications as applicationSchema,
   createDirectory,
+  createSharedTemporaryDirectory,
   kMetadata,
   safeRemove,
   validate
 } from '@platformatic/foundation'
 import fastify from 'fastify'
+import { chmod } from 'node:fs/promises'
 import { platform, tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
@@ -343,7 +345,14 @@ export async function startManagementApi (runtime, config) {
 
   const runtimePIDDir = join(PLATFORMATIC_TMP_DIR, runtimePID.toString())
   if (platform() !== 'win32') {
-    await createDirectory(customSocket ? dirname(customSocket) : runtimePIDDir, typeof customSocket !== 'string')
+    if (customSocket) {
+      await createDirectory(dirname(customSocket))
+    } else {
+      await createSharedTemporaryDirectory('platformatic', 'runtimes')
+      await createDirectory(runtimePIDDir, true)
+      // The socket must only be accessible by the current user
+      await chmod(runtimePIDDir, 0o700)
+    }
   }
 
   let socketPath = null

package/lib/opentelemetry-metrics.js

@@ -0,0 +1,93 @@
+export class OpenTelemetryMetricsForwarder {
+  #config
+  #exporter
+  #logger
+  #queue
+  #timer
+  #flushing
+
+  constructor (config, logger) {
+    this.#config = config
+    this.#logger = logger
+    this.#queue = []
+    this.#timer = null
+    this.#flushing = false
+  }
+
+  async start () {
+    if (!this.#config || this.#config.enabled === false || this.#config.enabled === 'false' || !this.#config.endpoint) {
+      return false
+    }
+
+    const { OTLPMetricExporter } = await import('@opentelemetry/exporter-metrics-otlp-proto')
+    this.#exporter = new OTLPMetricExporter({
+      url: this.#config.endpoint,
+      headers: this.#config.headers
+    })
+
+    const interval = this.#config.interval ?? 60000
+    this.#timer = setInterval(() => {
+      this.flush().catch(error => {
+        this.#logger.error({ err: error }, 'OpenTelemetry metrics export failed.')
+      })
+    }, interval)
+    this.#timer.unref()
+
+    return true
+  }
+
+  collect (resourceMetrics) {
+    if (!this.#exporter) {
+      return
+    }
+
+    this.#queue.push(resourceMetrics)
+  }
+
+  async flush () {
+    if (!this.#exporter || this.#flushing || this.#queue.length === 0) {
+      return
+    }
+
+    this.#flushing = true
+    const batch = this.#queue.splice(0)
+
+    try {
+      await Promise.all(batch.map(resourceMetrics => this.#export(resourceMetrics)))
+    } finally {
+      this.#flushing = false
+    }
+  }
+
+  async close () {
+    if (this.#timer) {
+      clearInterval(this.#timer)
+      this.#timer = null
+    }
+
+    try {
+      await this.flush()
+    } catch (error) {
+      this.#logger.error({ err: error }, 'OpenTelemetry metrics export failed.')
+    }
+
+    if (this.#exporter) {
+      await this.#exporter.shutdown()
+      this.#exporter = null
+    }
+  }
+
+  #export (resourceMetrics) {
+    const { promise, resolve, reject } = Promise.withResolvers()
+
+    this.#exporter.export(resourceMetrics, result => {
+      if (result.code === 0) {
+        resolve()
+      } else {
+        reject(result.error ?? new Error('OpenTelemetry metrics export failed.'))
+      }
+    })
+
+    return promise
+  }
+}

package/lib/prom-server.js

@@ -76,13 +76,59 @@ async function checkLiveness (runtime) {
   return { response, status }
 }
 
-export async function startPrometheusServer (runtime, opts, healthProbes) {
-  const metricsEnabled = opts.enabled !== false
-  const healthProbesEnabled = healthProbes !== false
+function isHealthProbesServerEnabled (healthProbes) {
+  return typeof healthProbes === 'object' && healthProbes !== null
+}
+
+function isHealthProbesEnabled (healthProbes) {
+  return healthProbes !== false && healthProbes?.enabled !== false
+}
+
+function resolveServerAddress (opts, fallback) {
+  opts = typeof opts === 'object' && opts !== null ? opts : {}
+  fallback = typeof fallback === 'object' && fallback !== null ? fallback : {}
+
+  return {
+    host: opts.hostname ?? fallback.hostname ?? DEFAULT_HOSTNAME,
+    port: opts.port ?? fallback.port ?? DEFAULT_PORT
+  }
+}
+
+function useSharedServer (metricsOpts, healthProbes) {
+  if (!isHealthProbesServerEnabled(healthProbes)) {
+    return true
+  }
+
+  const metricsAddress = resolveServerAddress(metricsOpts)
+  const healthProbesAddress = resolveServerAddress(healthProbes, metricsOpts)
+
+  return metricsAddress.host === healthProbesAddress.host && String(metricsAddress.port) === String(healthProbesAddress.port)
+}
+
+function resolveHealthProbesOptions (metricsOpts, healthProbes) {
+  metricsOpts = typeof metricsOpts === 'object' && metricsOpts !== null ? metricsOpts : {}
+
+  if (!isHealthProbesServerEnabled(healthProbes)) {
+    return metricsOpts
+  }
+
+  const { host, port } = resolveServerAddress(healthProbes, metricsOpts)
+  return {
+    ...healthProbes,
+    hostname: host,
+    port,
+    readiness: healthProbes.readiness ?? metricsOpts.readiness,
+    liveness: healthProbes.liveness ?? metricsOpts.liveness
+  }
+}
+
+async function startServer (runtime, opts, metricsEnabled, healthProbesEnabled) {
+  opts = typeof opts === 'object' && opts !== null ? opts : {}
 
   if (!metricsEnabled && !healthProbesEnabled) {
     return
   }
+
   const host = opts.hostname ?? DEFAULT_HOSTNAME
   const port = opts.port ?? DEFAULT_PORT
   const metricsEndpoint = opts.endpoint ?? DEFAULT_METRICS_ENDPOINT
@@ -238,3 +284,19 @@ export async function startPrometheusServer (runtime, opts, healthProbes) {
   await promServer.listen({ port, host })
   return promServer
 }
+
+export async function startPrometheusServer (runtime, opts, healthProbes) {
+  const metricsEnabled = opts !== false && opts?.enabled !== false
+  const healthProbesEnabled = isHealthProbesEnabled(healthProbes) && useSharedServer(opts, healthProbes)
+  const serverOpts = healthProbesEnabled && isHealthProbesServerEnabled(healthProbes) ? resolveHealthProbesOptions(opts, healthProbes) : opts
+
+  return startServer(runtime, serverOpts, metricsEnabled, healthProbesEnabled)
+}
+
+export async function startHealthProbesServer (runtime, metricsOpts, healthProbes) {
+  if (!isHealthProbesEnabled(healthProbes) || useSharedServer(metricsOpts, healthProbes)) {
+    return
+  }
+
+  return startServer(runtime, resolveHealthProbesOptions(metricsOpts, healthProbes), false, true)
+}

package/lib/runtime.js

@@ -11,7 +11,11 @@ import {
 } from '@platformatic/foundation'
 import { getExecutable } from '@platformatic/globals'
 import { ITC } from '@platformatic/itc'
-import { collectProcessMetrics, client as metricsClient } from '@platformatic/metrics'
+import {
+  collectProcessMetrics,
+  client as metricsClient,
+  openTelemetryITCMessage
+} from '@platformatic/metrics'
 import fastify from 'fastify'
 import { EventEmitter, once } from 'node:events'
 import { existsSync } from 'node:fs'
@@ -45,8 +49,9 @@ import {
 import { abstractLogger, createLogger } from './logger.js'
 import { startManagementApi } from './management-api.js'
 import { createManagementHandlers } from './management-handlers.js'
+import { OpenTelemetryMetricsForwarder } from './opentelemetry-metrics.js'
 import { createChannelCreationHook } from './policies.js'
-import { startPrometheusServer } from './prom-server.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'
@@ -135,6 +140,8 @@ export class Runtime extends EventEmitter {
 
   #managementApi
   #prometheusServer
+  #healthProbesServer
+  #opentelemetryMetricsForwarder
   #inspectorServer
   #metricsLabelName
 
@@ -238,12 +245,17 @@ export class Runtime extends EventEmitter {
     if (config.metrics) {
       // Use the configured application label name for metrics (defaults to 'applicationId')
       this.#metricsLabelName = config.metrics.applicationLabel || 'applicationId'
-      this.#prometheusServer = await startPrometheusServer(this, config.metrics, config.healthProbes)
     } else {
       // Default to applicationId if metrics are not configured
       this.#metricsLabelName = 'applicationId'
     }
 
+    if (config.metrics || (typeof config.healthProbes === 'object' && config.healthProbes !== null)) {
+      this.#prometheusServer = await startPrometheusServer(this, config.metrics ?? false, config.healthProbes)
+    }
+
+    this.#healthProbesServer = await startHealthProbesServer(this, config.metrics, config.healthProbes)
+
     // Initialize process-level metrics registry in the main thread if metrics or management API is enabled
     // These metrics are the same across all workers and only need to be collected once
     // We need this for management API as it can request metrics even without explicit metrics config
@@ -258,6 +270,8 @@ export class Runtime extends EventEmitter {
     this.#loggerDestination = destination
     this.#loggerContext = context
 
+    await this.#startOpenTelemetryMetricsForwarder(config.metrics?.opentelemetry)
+
     this.#createWorkersBroadcastChannel()
 
     if (this.#config.workers.dynamic) {
@@ -407,6 +421,15 @@ export class Runtime extends EventEmitter {
       await this.#prometheusServer.close()
     }
 
+    if (this.#healthProbesServer) {
+      await this.#healthProbesServer.close()
+    }
+
+    if (this.#opentelemetryMetricsForwarder) {
+      await this.#opentelemetryMetricsForwarder.close()
+      this.#opentelemetryMetricsForwarder = null
+    }
+
     // Clean up process metrics registry
     if (this.#processMetricsRegistry) {
       this.#processMetricsRegistry.clear()
@@ -864,12 +887,24 @@ export class Runtime extends EventEmitter {
       this.#prometheusServer = null
     }
 
+    if (this.#healthProbesServer) {
+      await this.#healthProbesServer.close()
+      this.#healthProbesServer = null
+    }
+
+    if (this.#opentelemetryMetricsForwarder) {
+      await this.#opentelemetryMetricsForwarder.close()
+      this.#opentelemetryMetricsForwarder = null
+    }
+
     this.#config.metrics = metricsConfig
     this.#metricsLabelName = metricsConfig?.applicationLabel || 'applicationId'
 
-    if (metricsConfig.enabled !== false || this.#config.healthProbes !== false) {
-      this.#prometheusServer = await startPrometheusServer(this, metricsConfig, this.#config.healthProbes)
-    }
+    this.#prometheusServer = await startPrometheusServer(this, metricsConfig, this.#config.healthProbes)
+
+    this.#healthProbesServer = await startHealthProbesServer(this, metricsConfig, this.#config.healthProbes)
+
+    await this.#startOpenTelemetryMetricsForwarder(metricsConfig?.opentelemetry)
 
     const promises = []
     for (const worker of this.#workers.values()) {
@@ -889,6 +924,17 @@ export class Runtime extends EventEmitter {
     return { success: true, config: metricsConfig }
   }
 
+  async #startOpenTelemetryMetricsForwarder (config) {
+    if (!config?.endpoint || config.enabled === false || config.enabled === 'false') {
+      return
+    }
+
+    const forwarder = new OpenTelemetryMetricsForwarder(config, this.logger)
+    if (await forwarder.start()) {
+      this.#opentelemetryMetricsForwarder = forwarder
+    }
+  }
+
   // TODO: Remove in next major version
   startCollectingMetrics () {
     this.logger.warn(
@@ -2026,6 +2072,10 @@ export class Runtime extends EventEmitter {
       worker[kIsSubprocessHost] = true
     })
 
+    worker[kITC].on(openTelemetryITCMessage, resourceMetrics => {
+      this.#opentelemetryMetricsForwarder?.collect(resourceMetrics)
+    })
+
     worker[kITC].on('request:restart', async () => {
       // Do not restart applications that are not fully started yet or when the runtime is still starting.
       // The gateway sends request:restart when it receives application:added events,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/runtime",
-  "version": "3.59.0",
+  "version": "3.61.0",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -18,6 +18,7 @@
     "@fastify/compress": "^8.0.0",
     "@fastify/express": "^4.0.0",
     "@fastify/formbody": "^8.0.0",
+    "@opentelemetry/sdk-metrics": "^2.8.0",
     "@sentry/node": "^10.58.0",
     "atomic-sleep": "^1.0.0",
     "autocannon": "^8.0.0",
@@ -38,14 +39,14 @@
     "typescript": "^5.5.4",
     "undici-oidc-interceptor": "^0.9.0",
     "why-is-node-running": "^2.2.2",
-    "@platformatic/composer": "3.59.0",
-    "@platformatic/db": "3.59.0",
-    "@platformatic/gateway": "3.59.0",
-    "@platformatic/node": "3.59.0",
-    "@platformatic/service": "3.59.0",
-    "@platformatic/sql-mapper": "3.59.0",
-    "@platformatic/sql-graphql": "3.59.0",
-    "@platformatic/wattpm-pprof-capture": "3.59.0"
+    "@platformatic/composer": "3.61.0",
+    "@platformatic/db": "3.61.0",
+    "@platformatic/gateway": "3.61.0",
+    "@platformatic/node": "3.61.0",
+    "@platformatic/service": "3.61.0",
+    "@platformatic/sql-graphql": "3.61.0",
+    "@platformatic/wattpm-pprof-capture": "3.61.0",
+    "@platformatic/sql-mapper": "3.61.0"
   },
   "dependencies": {
     "@fastify/accepts": "^5.0.0",
@@ -53,6 +54,7 @@
     "@fastify/error": "^4.0.0",
     "@fastify/websocket": "^11.0.0",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.219.0",
     "@platformatic/prom-client": "^1.0.0",
     "@platformatic/undici-cache-memory": "^0.9.0",
     "@watchable/unpromise": "^1.0.2",
@@ -75,13 +77,13 @@
     "undici": "^7.27.2",
     "undici-thread-interceptor": "^1.3.1",
     "ws": "^8.16.0",
-    "@platformatic/basic": "3.59.0",
-    "@platformatic/generators": "3.59.0",
-    "@platformatic/globals": "3.59.0",
-    "@platformatic/metrics": "3.59.0",
-    "@platformatic/foundation": "3.59.0",
-    "@platformatic/telemetry": "3.59.0",
-    "@platformatic/itc": "3.59.0"
+    "@platformatic/basic": "3.61.0",
+    "@platformatic/generators": "3.61.0",
+    "@platformatic/foundation": "3.61.0",
+    "@platformatic/globals": "3.61.0",
+    "@platformatic/itc": "3.61.0",
+    "@platformatic/telemetry": "3.61.0",
+    "@platformatic/metrics": "3.61.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/schema.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.59.0.json",
+  "$id": "https://schemas.platformatic.dev/@platformatic/runtime/3.61.0.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Platformatic Runtime Config",
   "type": "object",
@@ -2211,6 +2211,115 @@
         },
         {
           "type": "string"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "string"
+                }
+              ]
+            },
+            "hostname": {
+              "type": "string"
+            },
+            "port": {
+              "anyOf": [
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "string"
+                }
+              ]
+            },
+            "readiness": {
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "endpoint": {
+                      "type": "string"
+                    },
+                    "success": {
+                      "type": "object",
+                      "properties": {
+                        "statusCode": {
+                          "type": "number"
+                        },
+                        "body": {
+                          "type": "string"
+                        }
+                      },
+                      "additionalProperties": false
+                    },
+                    "fail": {
+                      "type": "object",
+                      "properties": {
+                        "statusCode": {
+                          "type": "number"
+                        },
+                        "body": {
+                          "type": "string"
+                        }
+                      },
+                      "additionalProperties": false
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            },
+            "liveness": {
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "endpoint": {
+                      "type": "string"
+                    },
+                    "success": {
+                      "type": "object",
+                      "properties": {
+                        "statusCode": {
+                          "type": "number"
+                        },
+                        "body": {
+                          "type": "string"
+                        }
+                      },
+                      "additionalProperties": false
+                    },
+                    "fail": {
+                      "type": "object",
+                      "properties": {
+                        "statusCode": {
+                          "type": "number"
+                        },
+                        "body": {
+                          "type": "string"
+                        }
+                      },
+                      "additionalProperties": false
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "additionalProperties": false
         }
       ],
       "default": true
@@ -2687,7 +2796,9 @@
                   "type": "string"
                 }
               ],
-              "default": 5000
+              "default": 5000,
+              "deprecated": true,
+              "description": "Deprecated. Health probe timeout configuration is no longer used."
             },
             "plugins": {
               "type": "array",
@@ -2763,6 +2874,50 @@
               ],
               "additionalProperties": false
             },
+            "opentelemetry": {
+              "type": "object",
+              "description": "Configuration for forwarding user OpenTelemetry metrics to an OTLP endpoint",
+              "properties": {
+                "enabled": {
+                  "anyOf": [
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "type": "string"
+                    }
+                  ],
+                  "description": "Enable or disable OpenTelemetry metrics forwarding"
+                },
+                "endpoint": {
+                  "type": "string",
+                  "description": "OTLP metrics endpoint URL (e.g., http://collector:4318/v1/metrics)"
+                },
+                "interval": {
+                  "anyOf": [
+                    {
+                      "type": "integer"
+                    },
+                    {
+                      "type": "string"
+                    }
+                  ],
+                  "default": 60000,
+                  "description": "Interval in milliseconds between metric forwards"
+                },
+                "headers": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Additional HTTP headers for authentication"
+                }
+              },
+              "required": [
+                "endpoint"
+              ],
+              "additionalProperties": false
+            },
             "httpCustomLabels": {
               "type": "array",
               "description": "Custom labels to add to HTTP metrics (http_request_all_duration_seconds). Each label extracts its value from an HTTP request header.",