@backstage/backend-plugin-api 1.9.1-next.0 → 1.9.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @backstage/backend-plugin-api
 
+## 1.9.1
+
+### Patch Changes
+
+- 90b572e: Adds an alpha `TracingService` to provide a unified interface for emitting trace spans across Backstage plugins.
+- 6209065: Added `context` and `propagation` to the alpha `TracingService`. Plugins can bridge OpenTelemetry context across async boundaries via `tracing.propagation.extract(tracing.context.active(), carrier)` followed by `tracing.context.with(ctx, fn)`, and read propagated baggage via `tracing.propagation.getActiveBaggage()` or `tracing.propagation.getBaggage(ctx)`.
+- Updated dependencies
+  - @backstage/errors@1.3.1
+  - @backstage/plugin-permission-node@0.11.0
+  - @backstage/plugin-auth-node@0.7.1
+  - @backstage/plugin-permission-common@0.9.9
+  - @backstage/cli-common@0.2.2
+  - @backstage/config@1.3.8
+
+## 1.9.1-next.1
+
+### Patch Changes
+
+- 90b572e: Adds an alpha `TracingService` to provide a unified interface for emitting trace spans across Backstage plugins.
+
 ## 1.9.1-next.0
 
 ### Patch Changes

package/dist/alpha/refs.cjs.js

@@ -15,9 +15,13 @@ const rootSystemMetadataServiceRef = backendPluginApi.createServiceRef({
 const metricsServiceRef = backendPluginApi.createServiceRef({
   id: "alpha.core.metrics"
 });
+const tracingServiceRef = backendPluginApi.createServiceRef({
+  id: "alpha.core.tracing"
+});
 
 exports.actionsRegistryServiceRef = actionsRegistryServiceRef;
 exports.actionsServiceRef = actionsServiceRef;
 exports.metricsServiceRef = metricsServiceRef;
 exports.rootSystemMetadataServiceRef = rootSystemMetadataServiceRef;
+exports.tracingServiceRef = tracingServiceRef;
 //# sourceMappingURL=refs.cjs.js.map

package/dist/alpha/refs.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"refs.cjs.js","sources":["../../src/alpha/refs.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createServiceRef } from '@backstage/backend-plugin-api';\n\n/**\n * Service for calling distributed actions\n *\n * See {@link ActionsService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsServiceRef = createServiceRef<\n  import('./ActionsService').ActionsService\n>({\n  id: 'alpha.core.actions',\n});\n\n/**\n * Service for registering and managing distributed actions.\n *\n * See {@link ActionsRegistryService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions-registry | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsRegistryServiceRef = createServiceRef<\n  import('./ActionsRegistryService').ActionsRegistryService\n>({\n  id: 'alpha.core.actionsRegistry',\n});\n\n/**\n * Read information about your current Backstage deployment.\n * @alpha\n */\nexport const rootSystemMetadataServiceRef = createServiceRef<\n  import('./RootSystemMetadataService').RootSystemMetadataService\n>({\n  id: 'alpha.core.rootSystemMetadata',\n  scope: 'root',\n});\n\n/**\n * Service for managing metrics.\n *\n * @alpha\n */\nexport const metricsServiceRef = createServiceRef<\n  import('./MetricsService').MetricsService\n>({\n  id: 'alpha.core.metrics',\n});\n"],"names":["createServiceRef"],"mappings":";;;;AA2BO,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAWM,MAAM,4BAA4BA,iCAAA,CAEvC;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAMM,MAAM,+BAA+BA,iCAAA,CAE1C;AAAA,EACA,EAAA,EAAI,+BAAA;AAAA,EACJ,KAAA,EAAO;AACT,CAAC;AAOM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;;;;;;;"}
+{"version":3,"file":"refs.cjs.js","sources":["../../src/alpha/refs.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createServiceRef } from '@backstage/backend-plugin-api';\n\n/**\n * Service for calling distributed actions\n *\n * See {@link ActionsService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsServiceRef = createServiceRef<\n  import('./ActionsService').ActionsService\n>({\n  id: 'alpha.core.actions',\n});\n\n/**\n * Service for registering and managing distributed actions.\n *\n * See {@link ActionsRegistryService}\n * and {@link https://backstage.io/docs/backend-system/core-services/actions-registry | the service docs}\n * for more information.\n *\n * @alpha\n */\nexport const actionsRegistryServiceRef = createServiceRef<\n  import('./ActionsRegistryService').ActionsRegistryService\n>({\n  id: 'alpha.core.actionsRegistry',\n});\n\n/**\n * Read information about your current Backstage deployment.\n * @alpha\n */\nexport const rootSystemMetadataServiceRef = createServiceRef<\n  import('./RootSystemMetadataService').RootSystemMetadataService\n>({\n  id: 'alpha.core.rootSystemMetadata',\n  scope: 'root',\n});\n\n/**\n * Service for managing metrics.\n *\n * @alpha\n */\nexport const metricsServiceRef = createServiceRef<\n  import('./MetricsService').MetricsService\n>({\n  id: 'alpha.core.metrics',\n});\n\n/**\n * Service for managing trace spans.\n *\n * See `TracingService` for the API surface.\n *\n * @alpha\n */\nexport const tracingServiceRef = createServiceRef<\n  import('./TracingService').TracingService\n>({\n  id: 'alpha.core.tracing',\n});\n"],"names":["createServiceRef"],"mappings":";;;;AA2BO,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAWM,MAAM,4BAA4BA,iCAAA,CAEvC;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AAMM,MAAM,+BAA+BA,iCAAA,CAE1C;AAAA,EACA,EAAA,EAAI,+BAAA;AAAA,EACJ,KAAA,EAAO;AACT,CAAC;AAOM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;AASM,MAAM,oBAAoBA,iCAAA,CAE/B;AAAA,EACA,EAAA,EAAI;AACN,CAAC;;;;;;;;"}

package/dist/alpha.cjs.js

@@ -8,4 +8,5 @@ exports.actionsRegistryServiceRef = refs.actionsRegistryServiceRef;
 exports.actionsServiceRef = refs.actionsServiceRef;
 exports.metricsServiceRef = refs.metricsServiceRef;
 exports.rootSystemMetadataServiceRef = refs.rootSystemMetadataServiceRef;
+exports.tracingServiceRef = refs.tracingServiceRef;
 //# sourceMappingURL=alpha.cjs.js.map

package/dist/alpha.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"alpha.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}
+{"version":3,"file":"alpha.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/dist/alpha.d.ts

@@ -4,6 +4,7 @@ import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
 import { LoggerService, BackstageCredentials } from '@backstage/backend-plugin-api';
 import { JsonObject, JsonValue } from '@backstage/types';
 import { JSONSchema7 } from 'json-schema';
+import { Request } from 'express';
 
 /** @public */
 interface RootSystemMetadataServicePluginInfo {
@@ -288,6 +289,161 @@ interface MetricsService {
     createObservableGauge<TAttributes extends MetricAttributes = MetricAttributes>(name: string, opts?: MetricOptions): MetricsServiceObservableGauge<TAttributes>;
 }
 
+/**
+ * Attribute values that can be attached to spans.
+ *
+ * @alpha
+ */
+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
+ */
+interface TracingServiceAttributes {
+    [key: string]: TracingServiceAttributeValue | undefined;
+}
+/**
+ * The kind of operation a span represents.
+ *
+ * @alpha
+ */
+type TracingServiceSpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+/**
+ * The status of a span.
+ *
+ * @alpha
+ */
+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
+ */
+interface TracingServiceSpan {
+    setAttribute(key: string, value: TracingServiceAttributeValue): void;
+    setStatus(status: TracingServiceSpanStatus): void;
+}
+/**
+ * Options for `startActiveSpan`.
+ *
+ * @alpha
+ */
+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
+ */
+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>): Promise<T>;
+    /**
+     * Runs `fn` inside a new active span configured by `options`. The
+     * span is finished when `fn` resolves or throws.
+     */
+    startActiveSpan<T>(name: string, options: TracingServiceSpanOptions, fn: (span: TracingServiceSpan) => T | Promise<T>): Promise<T>;
+    /**
+     * Read the active tracing context, or run work within a specific
+     * one.
+     */
+    readonly context: TracingServiceContextAPI;
+    /**
+     * Extract a caller's tracing context from an inbound carrier, and
+     * read baggage from a context. Use these to bridge context across
+     * boundaries where automatic propagation is lost — for example,
+     * when a request arrives over a transport that does not
+     * automatically attach the caller's context.
+     */
+    readonly propagation: TracingServicePropagationAPI;
+}
+/**
+ * Read the active tracing context, or run work within a specific one.
+ * The context carries the active span and propagation fields (trace
+ * parent, baggage) for the current unit of work, and is automatically
+ * inherited by spans created via `startActiveSpan`.
+ *
+ * @alpha
+ */
+interface TracingServiceContextAPI {
+    /** Returns the currently active context. */
+    active(): TracingServiceContext;
+    /** Runs `fn` with the supplied context set as the active context. */
+    with<T>(context: TracingServiceContext, fn: () => T | Promise<T>): Promise<T>;
+}
+/**
+ * Extract a caller's trace parent and baggage from an inbound carrier
+ * (typically HTTP headers), or read baggage from a context. Use these
+ * to bridge context across boundaries where automatic propagation is
+ * lost.
+ *
+ * @alpha
+ */
+interface TracingServicePropagationAPI {
+    /**
+     * Returns a new context with propagation fields (trace parent,
+     * baggage, ...) read from the supplied carrier merged into it.
+     */
+    extract(context: TracingServiceContext, carrier: Record<string, string | string[] | undefined>): TracingServiceContext;
+    /**
+     * Returns the baggage attached to the supplied context, or
+     * `undefined` when none is present.
+     */
+    getBaggage(context: TracingServiceContext): TracingServiceBaggage | undefined;
+    /**
+     * Returns the baggage attached to the currently active context, or
+     * `undefined` when none is present. Equivalent to
+     * `getBaggage(context.active())`.
+     */
+    getActiveBaggage(): TracingServiceBaggage | undefined;
+}
+/**
+ * Opaque handle representing a tracing context. Consumers receive
+ * these from {@link TracingServiceContextAPI.active} or
+ * {@link TracingServicePropagationAPI.extract} and pass them back into
+ * the API; the type carries no inspectable fields.
+ *
+ * @alpha
+ */
+interface TracingServiceContext {
+    readonly $$type: '@backstage/TracingServiceContext';
+}
+/**
+ * A read-only view of propagated baggage entries.
+ *
+ * @alpha
+ */
+interface TracingServiceBaggage {
+    getAllEntries(): Array<[string, TracingServiceBaggageEntry]>;
+}
+/**
+ * A single baggage entry.
+ *
+ * @alpha
+ */
+interface TracingServiceBaggageEntry {
+    value: string;
+}
+
 /**
  * Service for calling distributed actions
  *
@@ -319,6 +475,14 @@ declare const rootSystemMetadataServiceRef: _backstage_backend_plugin_api.Servic
  * @alpha
  */
 declare const metricsServiceRef: _backstage_backend_plugin_api.ServiceRef<MetricsService, "plugin", "singleton">;
+/**
+ * Service for managing trace spans.
+ *
+ * See `TracingService` for the API surface.
+ *
+ * @alpha
+ */
+declare const tracingServiceRef: _backstage_backend_plugin_api.ServiceRef<TracingService, "plugin", "singleton">;
 
-export { actionsRegistryServiceRef, actionsServiceRef, metricsServiceRef, rootSystemMetadataServiceRef };
-export type { ActionsRegistryActionContext, ActionsRegistryActionExample, ActionsRegistryActionOptions, ActionsRegistryService, ActionsService, ActionsServiceAction, MetricAdvice, MetricAttributeValue, MetricAttributes, MetricOptions, MetricsService, MetricsServiceCounter, MetricsServiceGauge, MetricsServiceHistogram, MetricsServiceObservable, MetricsServiceObservableCallback, MetricsServiceObservableCounter, MetricsServiceObservableGauge, MetricsServiceObservableResult, MetricsServiceObservableUpDownCounter, MetricsServiceUpDownCounter, RootSystemMetadataService, RootSystemMetadataServicePluginInfo };
+export { actionsRegistryServiceRef, actionsServiceRef, metricsServiceRef, rootSystemMetadataServiceRef, tracingServiceRef };
+export type { ActionsRegistryActionContext, ActionsRegistryActionExample, ActionsRegistryActionOptions, ActionsRegistryService, ActionsService, ActionsServiceAction, MetricAdvice, MetricAttributeValue, MetricAttributes, MetricOptions, MetricsService, MetricsServiceCounter, MetricsServiceGauge, MetricsServiceHistogram, MetricsServiceObservable, MetricsServiceObservableCallback, MetricsServiceObservableCounter, MetricsServiceObservableGauge, MetricsServiceObservableResult, MetricsServiceObservableUpDownCounter, MetricsServiceUpDownCounter, RootSystemMetadataService, RootSystemMetadataServicePluginInfo, TracingService, TracingServiceAttributeValue, TracingServiceAttributes, TracingServiceBaggage, TracingServiceBaggageEntry, TracingServiceContext, TracingServiceContextAPI, TracingServicePropagationAPI, TracingServiceSpan, TracingServiceSpanKind, TracingServiceSpanOptions, TracingServiceSpanStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "1.9.1-next.0",
+  "version": "1.9.1",
   "description": "Core API used by Backstage backend plugins",
   "backstage": {
     "role": "node-library"
@@ -65,13 +65,13 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/cli-common": "0.2.2-next.0",
-    "@backstage/config": "1.3.8-next.0",
-    "@backstage/errors": "1.3.1-next.0",
-    "@backstage/plugin-auth-node": "0.7.1-next.0",
-    "@backstage/plugin-permission-common": "0.9.9-next.0",
-    "@backstage/plugin-permission-node": "0.10.13-next.0",
-    "@backstage/types": "1.2.2",
+    "@backstage/cli-common": "^0.2.2",
+    "@backstage/config": "^1.3.8",
+    "@backstage/errors": "^1.3.1",
+    "@backstage/plugin-auth-node": "^0.7.1",
+    "@backstage/plugin-permission-common": "^0.9.9",
+    "@backstage/plugin-permission-node": "^0.11.0",
+    "@backstage/types": "^1.2.2",
     "@types/express": "^4.17.6",
     "@types/json-schema": "^7.0.6",
     "@types/luxon": "^3.0.0",
@@ -81,8 +81,8 @@
     "zod": "^3.25.76 || ^4.0.0"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "1.11.3-next.0",
-    "@backstage/cli": "0.36.2-next.0"
+    "@backstage/backend-test-utils": "^1.11.3",
+    "@backstage/cli": "^0.36.2"
   },
   "configSchema": "config.d.ts"
 }