feat(metrics): Implement MetricsService (#32977)

* feat: add MetricsService alpha release

Introduces MetricsService as a new @alpha core service wrapping
@opentelemetry/api. Includes migration of existing catalog metrics
to use the new service.

Signed-off-by: benjdlambert <ben@blam.sh>

* chore: duplicate otel types, add plugin-scoped factory and tests

Signed-off-by: benjdlambert <ben@blam.sh>

* chore: update BEP-0012 metrics service design

Signed-off-by: Kurt King <kurtaking@gmail.com>

* chore: address PR feedback from freben and rugvip

Rename instrument types with MetricsService prefix for namespace
clarity, move config to backend.metrics.plugin.{pluginId}, add
config.d.ts schema, and improve factory test assertions.

Signed-off-by: benjdlambert <ben@blam.sh>

---------

Signed-off-by: benjdlambert <ben@blam.sh>
Signed-off-by: Kurt King <kurtaking@gmail.com>
Co-authored-by: Kurt King <kurtaking@gmail.com>

packages/backend-test-utils/report-alpha.api.md

@@ -12,6 +12,7 @@ import { BackstageCredentials } from '@backstage/backend-plugin-api';
 import { JsonObject } from '@backstage/types';
 import { JsonValue } from '@backstage/types';
 import { LoggerService } from '@backstage/backend-plugin-api';
+import { MetricsService } from '@backstage/backend-plugin-api/alpha';
 import { ServiceFactory } from '@backstage/backend-plugin-api';
 
 // @alpha (undocumented)
@@ -43,6 +44,16 @@ export namespace actionsServiceMock {
     ) => ServiceMock<ActionsService>;
 }
 
+// @alpha (undocumented)
+export namespace metricsServiceMock {
+  const // (undocumented)
+    factory: () => ServiceFactory<MetricsService, 'plugin', 'singleton'>;
+  const // (undocumented)
+    mock: (
+      partialImpl?: Partial<MetricsService> | undefined,
+    ) => ServiceMock<MetricsService>;
+}
+
 // @alpha
 export class MockActionsRegistry
   implements ActionsRegistryService, ActionsService

packages/backend-test-utils/src/alpha/services/MetricsServiceMock.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createServiceMock } from './alphaCreateServiceMock';
+import {
+  MetricsService,
+  metricsServiceRef,
+} from '@backstage/backend-plugin-api/alpha';
+import { metricsServiceFactory } from '@backstage/backend-defaults/alpha';
+
+/**
+ * @alpha
+ */
+export namespace metricsServiceMock {
+  export const factory = () => metricsServiceFactory;
+
+  export const mock = createServiceMock<MetricsService>(
+    metricsServiceRef,
+    () => ({
+      createCounter: jest.fn().mockImplementation(() => ({
+        add: jest.fn(),
+      })),
+      createUpDownCounter: jest.fn().mockImplementation(() => ({
+        add: jest.fn(),
+      })),
+      createHistogram: jest.fn().mockImplementation(() => ({
+        record: jest.fn(),
+      })),
+      createGauge: jest.fn().mockImplementation(() => ({
+        record: jest.fn(),
+      })),
+      createObservableCounter: jest.fn().mockImplementation(() => ({
+        addCallback: jest.fn(),
+        removeCallback: jest.fn(),
+      })),
+      createObservableUpDownCounter: jest.fn().mockImplementation(() => ({
+        addCallback: jest.fn(),
+        removeCallback: jest.fn(),
+      })),
+      createObservableGauge: jest.fn().mockImplementation(() => ({
+        addCallback: jest.fn(),
+        removeCallback: jest.fn(),
+      })),
+    }),
+  );
+}

packages/backend-test-utils/src/alpha/services/index.ts

@@ -17,4 +17,5 @@
 export { actionsRegistryServiceMock } from './ActionsRegistryServiceMock';
 export { MockActionsRegistry } from './MockActionsRegistry';
 export { actionsServiceMock } from './ActionsServiceMock';
+export { metricsServiceMock } from './MetricsServiceMock';
 export { type ServiceMock } from './alphaCreateServiceMock';

packages/backend-test-utils/src/wiring/TestBackend.ts

@@ -43,6 +43,7 @@ import { HostDiscovery } from '@backstage/backend-defaults/discovery';
 import {
   actionsRegistryServiceMock,
   actionsServiceMock,
+  metricsServiceMock,
 } from '../alpha/services';
 
 /** @public */
@@ -92,6 +93,7 @@ export const defaultServiceFactories = [
   // Alpha services
   actionsRegistryServiceMock.factory(),
   actionsServiceMock.factory(),
+  metricsServiceMock.factory(),
 ];
 
 /**