@kbn/cleanup-before-exit: Package to install cleanup handlers (elastic#238561)

Adds a package to install cleanup handlers. We have `Cleanup` in
`@kbn/dev-cli-runner`, but it uses an outdated version of exit-hook
which doesn't support async cleanup handlers. The newer version requires
ESM support. Rather than installing another 3rd party lib, I've opted
for creating an internal package, also to support blocking
process.exit() calls.

## Why

In certain scenarios, we'll want to flush data before the process exits.
In some cases, such as when running Playwright, some code will call
`process.exit` which doesn't allow for cleanup. This means we are not
able to export all tracing data which breaks some of our debugging
flows.

## How

Listeners are added to process for SIGINT, SIGTERM and beforeExit.
Additionally, process.exit is overridden. In all cases, registered
cleanup handlers are immediately called and given time to complete,
before either allowing the process to exit naturally, or calling
process.exit().

## Notes

Tests and README were written with GPT-5 Codex.

---------

Co-authored-by: kibanamachine <[email protected]>

Author: 2 people

.github/CODEOWNERS

@@ -454,6 +454,7 @@ src/platform/packages/shared/kbn-cbor @elastic/kibana-operations
 src/platform/packages/shared/kbn-cell-actions @elastic/security-threat-hunting-investigations
 src/platform/packages/shared/kbn-chart-icons @elastic/kibana-visualizations
 src/platform/packages/shared/kbn-charts-theme @elastic/kibana-visualizations
+src/platform/packages/shared/kbn-cleanup-before-exit @elastic/observability-ui
 src/platform/packages/shared/kbn-coloring @elastic/kibana-visualizations
 src/platform/packages/shared/kbn-config @elastic/kibana-core
 src/platform/packages/shared/kbn-config-schema @elastic/kibana-core

package.json

@@ -229,6 +229,7 @@
     "@kbn/chart-icons": "link:src/platform/packages/shared/kbn-chart-icons",
     "@kbn/charts-plugin": "link:src/platform/plugins/shared/charts",
     "@kbn/charts-theme": "link:src/platform/packages/shared/kbn-charts-theme",
+    "@kbn/cleanup-before-exit": "link:src/platform/packages/shared/kbn-cleanup-before-exit",
     "@kbn/cloud": "link:src/platform/packages/shared/cloud",
     "@kbn/cloud-chat-plugin": "link:x-pack/platform/plugins/private/cloud_integrations/cloud_chat",
     "@kbn/cloud-data-migration-plugin": "link:x-pack/platform/plugins/private/cloud_integrations/cloud_data_migration",

src/platform/packages/private/opentelemetry/kbn-metrics/kibana.jsonc

@@ -1,5 +1,5 @@
 {
-  "type": "shared-common",
+  "type": "shared-server",
   "id": "@kbn/metrics",
   "owner": [
     "@elastic/kibana-core",

src/platform/packages/private/opentelemetry/kbn-metrics/src/init_metrics.ts

@@ -7,14 +7,15 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-import { castArray, once } from 'lodash';
+import { castArray } from 'lodash';
 import { Metadata } from '@grpc/grpc-js';
 import { OTLPMetricExporter as OTLPMetricExporterGrpc } from '@opentelemetry/exporter-metrics-otlp-grpc';
 import { OTLPMetricExporter as OTLPMetricExporterHttp } from '@opentelemetry/exporter-metrics-otlp-http';
 import type { resources } from '@elastic/opentelemetry-node/sdk';
 import { api, metrics } from '@elastic/opentelemetry-node/sdk';
 import type { MetricsConfig, MonitoringCollectionConfig } from '@kbn/metrics-config';
 import { fromExternalVariant } from '@kbn/std';
+import { cleanupBeforeExit } from '@kbn/cleanup-before-exit';
 import { PrometheusExporter } from './prometheus_exporter';
 
 /**
@@ -132,9 +133,5 @@ export function initMetrics(initMetricsOptions: InitMetricsOptions) {
 
   api.metrics.setGlobalMeterProvider(meterProvider);
 
-  const shutdown = once(() => meterProvider.shutdown());
-  process.on('SIGTERM', shutdown);
-  process.on('SIGINT', shutdown);
-  process.on('beforeExit', shutdown);
-  process.on('uncaughtExceptionMonitor', shutdown);
+  cleanupBeforeExit(() => meterProvider.shutdown());
 }

src/platform/packages/private/opentelemetry/kbn-metrics/tsconfig.json

@@ -17,5 +17,6 @@
     "@kbn/metrics-config",
     "@kbn/std",
     "@kbn/core-http-server",
+    "@kbn/cleanup-before-exit",
   ]
 }

src/platform/packages/shared/kbn-cleanup-before-exit/README.md

@@ -0,0 +1,25 @@
+# @kbn/cleanup-before-exit
+
+Utilities for registering asynchronous cleanup tasks that should run before a Node.js process exits.
+
+## Usage
+
+```ts
+import { cleanupBeforeExit } from '@kbn/cleanup-before-exit';
+
+cleanupBeforeExit(
+  async () => {
+    await closeServices();
+  },
+  { blockExit: true, timeout: 10_000 }
+);
+```
+
+## Options
+
+| Option      | Default | Description                                                                                               |
+| ----------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `blockExit` | `false` | When `true`, overrides `process.exit` so the process waits for the handler to settle.                     |
+| `timeout`   | `5000`  | Milliseconds to wait before the handler is considered timed out; the timeout error is logged and ignored. |
+
+Handlers are guaranteed to only run once, all run in parallel, and any rejections are logged via OpenTelemetry `diag`.

src/platform/packages/shared/kbn-cleanup-before-exit/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export { cleanupBeforeExit } from './src/cleanup_before_exit';

src/platform/packages/shared/kbn-cleanup-before-exit/jest.config.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+module.exports = {
+  preset: '@kbn/test/jest_node',
+  rootDir: '../../../../..',
+  roots: ['<rootDir>/src/platform/packages/shared/kbn-cleanup-before-exit'],
+};

src/platform/packages/shared/kbn-cleanup-before-exit/kibana.jsonc

@@ -0,0 +1,7 @@
+{
+  "type": "shared-server",
+  "id": "@kbn/cleanup-before-exit",
+  "owner": "@elastic/observability-ui",
+  "group": "platform",
+  "visibility": "shared"
+}

src/platform/packages/shared/kbn-cleanup-before-exit/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@kbn/cleanup-before-exit",
+  "private": true,
+  "version": "1.0.0",
+  "license": "Elastic License 2.0 OR AGPL-3.0-only OR SSPL-1.0"
+}