Add alpha TracingService API

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

.changeset/backend-tracing-and-stuff.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-plugin-api': patch
+---
+
+Adds an alpha `TracingService` to provide a unified interface for emitting trace spans across Backstage plugins.

packages/backend-plugin-api/report-alpha.api.md

@@ -10,6 +10,7 @@ import { JsonObject } from '@backstage/types';
 import { JSONSchema7 } from 'json-schema';
 import { JsonValue } from '@backstage/types';
 import { LoggerService } from '@backstage/backend-plugin-api';
+import type { Request as Request_2 } from 'express';
 import { ServiceRef } from '@backstage/backend-plugin-api';
 import { z } from 'zod/v3';
 
@@ -289,5 +290,68 @@ export const rootSystemMetadataServiceRef: ServiceRef<
   'singleton'
 >;
 
+// @alpha
+export interface TracingService {
+  startActiveSpan<T>(
+    name: string,
+    fn: (span: TracingServiceSpan) => T | Promise<T>,
+    options?: TracingServiceSpanOptions,
+  ): Promise<T>;
+}
+
+// @alpha
+export interface TracingServiceAttributes {
+  // (undocumented)
+  [key: string]: TracingServiceAttributeValue | undefined;
+}
+
+// @alpha
+export type TracingServiceAttributeValue =
+  | string
+  | number
+  | boolean
+  | Array<null | undefined | string>
+  | Array<null | undefined | number>
+  | Array<null | undefined | boolean>;
+
+// @alpha
+export const tracingServiceRef: ServiceRef<
+  TracingService,
+  'plugin',
+  'singleton'
+>;
+
+// @alpha
+export interface TracingServiceSpan {
+  // (undocumented)
+  setAttribute(key: string, value: TracingServiceAttributeValue): void;
+  // (undocumented)
+  setStatus(status: TracingServiceSpanStatus): void;
+}
+
+// @alpha
+export type TracingServiceSpanKind =
+  | 'internal'
+  | 'server'
+  | 'client'
+  | 'producer'
+  | 'consumer';
+
+// @alpha
+export interface TracingServiceSpanOptions {
+  attributes?: TracingServiceAttributes;
+  credentials?: BackstageCredentials;
+  kind?: TracingServiceSpanKind;
+  request?: Request_2<any, any, any, any, any>;
+}
+
+// @alpha
+export interface TracingServiceSpanStatus {
+  // (undocumented)
+  code: 'unset' | 'ok' | 'error';
+  // (undocumented)
+  message?: string;
+}
+
 // (No @packageDocumentation comment for this package)
 ```

packages/backend-plugin-api/src/alpha/TracingService.ts

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2026 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 type { Request } from 'express';
+import { BackstageCredentials } from '@backstage/backend-plugin-api';
+
+/**
+ * Attribute values that can be attached to spans.
+ *
+ * @alpha
+ */
+export type TracingServiceAttributeValue =
+  | string
+  | number
+  | boolean
+  | Array<null | undefined | string>
+  | Array<null | undefined | number>
+  | Array<null | undefined | boolean>;
+
+/**
+ * A set of key-value pairs that can be attached to spans.
+ *
+ * @alpha
+ */
+export interface TracingServiceAttributes {
+  [key: string]: TracingServiceAttributeValue | undefined;
+}
+
+/**
+ * The kind of operation a span represents.
+ *
+ * @alpha
+ */
+export type TracingServiceSpanKind =
+  | 'internal'
+  | 'server'
+  | 'client'
+  | 'producer'
+  | 'consumer';
+
+/**
+ * The status of a span.
+ *
+ * @alpha
+ */
+export interface TracingServiceSpanStatus {
+  code: 'unset' | 'ok' | 'error';
+  message?: string;
+}
+
+/**
+ * A trace span. Provided to `startActiveSpan` so
+ * additional attributes or status can be set from within the callback.
+ *
+ * @alpha
+ */
+export interface TracingServiceSpan {
+  setAttribute(key: string, value: TracingServiceAttributeValue): void;
+  setStatus(status: TracingServiceSpanStatus): void;
+}
+
+/**
+ * Options for `startActiveSpan`.
+ *
+ * @alpha
+ */
+export interface TracingServiceSpanOptions {
+  /** Attributes to attach to the span. */
+  attributes?: TracingServiceAttributes;
+  /** The kind of span. */
+  kind?: TracingServiceSpanKind;
+  /**
+   * Authenticated principal source for span enrichment. Preferred when
+   * both `credentials` and `request` are supplied.
+   */
+  credentials?: BackstageCredentials;
+  /** HTTP request to extract credentials from for span enrichment. */
+  request?: Request<any, any, any, any, any>;
+}
+
+/**
+ * A service for emitting trace spans from a backend plugin.
+ *
+ * @alpha
+ */
+export interface TracingService {
+  /**
+   * Runs `fn` inside a new active span. The span is finished when `fn`
+   * resolves or throws.
+   */
+  startActiveSpan<T>(
+    name: string,
+    fn: (span: TracingServiceSpan) => T | Promise<T>,
+    options?: TracingServiceSpanOptions,
+  ): Promise<T>;
+}

packages/backend-plugin-api/src/alpha/index.ts

@@ -46,9 +46,20 @@ export type {
   MetricsServiceObservableUpDownCounter,
 } from './MetricsService';
 
+export type {
+  TracingService,
+  TracingServiceAttributeValue,
+  TracingServiceAttributes,
+  TracingServiceSpan,
+  TracingServiceSpanKind,
+  TracingServiceSpanOptions,
+  TracingServiceSpanStatus,
+} from './TracingService';
+
 export {
   actionsRegistryServiceRef,
   actionsServiceRef,
   metricsServiceRef,
   rootSystemMetadataServiceRef,
+  tracingServiceRef,
 } from './refs';

packages/backend-plugin-api/src/alpha/refs.ts

@@ -67,3 +67,16 @@ export const metricsServiceRef = createServiceRef<
 >({
   id: 'alpha.core.metrics',
 });
+
+/**
+ * Service for managing trace spans.
+ *
+ * See {@link TracingService} for the API surface.
+ *
+ * @alpha
+ */
+export const tracingServiceRef = createServiceRef<
+  import('./TracingService').TracingService
+>({
+  id: 'alpha.core.tracing',
+});