feat: add Delivery Insights (DORA metrics) page to the sidebar

.changeset/delivery-insights-dora-ui.md

@@ -0,0 +1,37 @@
+---
+'@openchoreo/backstage-plugin-openchoreo-observability': minor
+'@openchoreo/backstage-plugin-openchoreo-observability-backend': minor
+'@openchoreo/openchoreo-client-node': minor
+'@openchoreo/backstage-portal-app': minor
+---
+
+Add a **Delivery Insights** sidebar page showing the four DORA metrics, scoped
+by breadcrumb (Namespace → Project → Component). It sits alongside Cost
+Insights in the sidebar rather than on entity pages, since the audience is
+delivery leadership looking across an organisation rather than a developer
+working on one component.
+
+- **Metrics**: Deployment Frequency, Lead Time for Changes, Change Failure Rate
+  and MTTR as KPI tiles with DORA classification, delta vs the previous equal
+  window, and sparklines; a trend chart per metric at daily/weekly/monthly
+  granularity (lead time shows p50/p75/p95).
+- **Drill-down**: a one-level-down breakdown table (namespace → projects,
+  project → components, component → environments) sorted by deployment
+  frequency, where each row carries its own metrics and an overall DORA rating
+  (the scope's weakest tier). Project/component rows narrow the page scope;
+  environment rows apply the environment filter.
+- **Per-environment cards** for the current scope, plus an environment filter
+  and a "how these metrics are calculated" footnote.
+- **Bookmarkable views**: scope, range, granularity and environment all live in
+  the URL, so a particular view can be shared or saved.
+- **Data layer**: `ObservabilityClient` gains `getDoraMetrics` /
+  `getDoraDeployments` against the observer's
+  `POST /api/v1alpha1/insights/dora/query` and
+  `.../insights/dora/deployments/query`, called directly like the other
+  observability APIs.
+- **URL resolution** gains namespace-level support: `/resolve-urls` now works
+  without an `environmentName` by resolving through the namespace's
+  environments (new `resolveForNamespace` in the client-node observability URL
+  resolver), which is what the org-wide scope needs.
+- The namespace/project/component breadcrumb is now a shared `ScopeBreadcrumb`
+  component used by both Delivery Insights and Cost Insights.

packages/openchoreo-client-node/src/observability-url-resolver.test.ts

@@ -0,0 +1,85 @@
+import { ObservabilityUrlResolver } from './observability-url-resolver';
+import { createOpenChoreoApiClient } from './factory';
+
+jest.mock('./factory', () => ({
+  createOpenChoreoApiClient: jest.fn(),
+}));
+
+const mockedCreateClient = createOpenChoreoApiClient as jest.MockedFunction<
+  typeof createOpenChoreoApiClient
+>;
+
+function ok(data: unknown) {
+  return { data, error: undefined, response: { ok: true, status: 200 } };
+}
+
+describe('ObservabilityUrlResolver.resolveForNamespace', () => {
+  beforeEach(() => {
+    mockedCreateClient.mockReset();
+  });
+
+  it('resolves through the namespace environments and caches the result', async () => {
+    const get = jest
+      .fn()
+      .mockResolvedValueOnce(ok({ items: [{ metadata: { name: 'dev' } }] }))
+      .mockResolvedValueOnce(ok({ spec: { dataPlaneRef: undefined } }))
+      .mockResolvedValueOnce(ok({ spec: { observabilityPlaneRef: undefined } }))
+      .mockResolvedValueOnce(
+        ok({ spec: { observerURL: 'https://observer.example.com' } }),
+      );
+    mockedCreateClient.mockReturnValue({ GET: get } as any);
+
+    const resolver = new ObservabilityUrlResolver({
+      baseUrl: 'https://api.example.com',
+    });
+
+    const first = await resolver.resolveForNamespace('org-1', 'user-a-token');
+    expect(first.observerUrl).toBe('https://observer.example.com');
+    expect(get).toHaveBeenCalledTimes(4);
+
+    // Second call for the *same* token should hit the cache: no new HTTP calls.
+    const second = await resolver.resolveForNamespace('org-1', 'user-a-token');
+    expect(second).toEqual(first);
+    expect(get).toHaveBeenCalledTimes(4);
+  });
+
+  it('does not leak a cached result across callers with different tokens', async () => {
+    // resolveForNamespace creates its own client for listing environments,
+    // then resolveForEnvironment creates another one internally — route each
+    // by token rather than assuming a fixed call count/order.
+    const getA = jest
+      .fn()
+      .mockResolvedValueOnce(ok({ items: [{ metadata: { name: 'dev' } }] }))
+      .mockResolvedValueOnce(ok({ spec: { dataPlaneRef: undefined } }))
+      .mockResolvedValueOnce(ok({ spec: { observabilityPlaneRef: undefined } }))
+      .mockResolvedValueOnce(
+        ok({ spec: { observerURL: 'https://observer.example.com' } }),
+      );
+
+    // User B has no visible environments in the same namespace (e.g. RBAC
+    // scopes them out) and must not receive user A's cached URL.
+    const getB = jest.fn().mockResolvedValue(ok({ items: [] }));
+
+    mockedCreateClient.mockImplementation(
+      config => ({ GET: config.token === 'user-a-token' ? getA : getB } as any),
+    );
+
+    const resolver = new ObservabilityUrlResolver({
+      baseUrl: 'https://api.example.com',
+    });
+
+    const forUserA = await resolver.resolveForNamespace(
+      'org-1',
+      'user-a-token',
+    );
+    expect(forUserA.observerUrl).toBe('https://observer.example.com');
+
+    await expect(
+      resolver.resolveForNamespace('org-1', 'user-b-token'),
+    ).rejects.toThrow(/No environments found in namespace 'org-1'/);
+
+    // User B's request must have gone through its own client, not reused
+    // user A's cached result.
+    expect(getB).toHaveBeenCalledTimes(1);
+  });
+});

packages/openchoreo-client-node/src/observability-url-resolver.ts

@@ -139,6 +139,86 @@ export class ObservabilityUrlResolver {
     return result;
   }
 
+  /**
+   * Resolve observability URLs for a namespace without a specific environment —
+   * used by scopes that aggregate across environments (e.g. the Insights pages at
+   * namespace/project level). Lists the namespace's environments and returns the
+   * first one that resolves to an observability plane.
+   *
+   * This assumes every environment in a namespace reports to the same
+   * observability plane, which is how a namespace is expected to be configured.
+   * If a namespace ever spans several planes, a namespace-wide query resolves to
+   * whichever plane its first environment uses and would therefore only see that
+   * plane's data; aggregating across planes would need a different shape than a
+   * single resolved URL.
+   */
+  async resolveForNamespace(
+    namespaceName: string,
+    token?: string,
+  ): Promise<ObservabilityUrlsResult> {
+    // Keyed by token because which environments this caller can list decides
+    // which plane is chosen (see below). Note this only partitions the
+    // namespace-level entry — `resolveForEnvironment` keeps its own
+    // longstanding cache keyed by namespace/environment alone, so a plane URL
+    // it has already cached is shared across callers.
+    const cacheKey = `ns:${namespaceName}:${token ?? ''}`;
+    const cached = this.getFromCache(cacheKey);
+    if (cached) return cached;
+
+    const client = this.createClient(token);
+
+    const {
+      data: envList,
+      error: envListError,
+      response: envListResp,
+    } = await client.GET('/api/v1/namespaces/{namespaceName}/environments', {
+      params: { path: { namespaceName } },
+    });
+    if (envListError || !envListResp.ok) {
+      throw new Error(
+        `Failed to list environments in namespace '${namespaceName}': ${envListResp.status} ${envListResp.statusText}`,
+      );
+    }
+
+    const items: Array<{ metadata?: { name?: string } }> =
+      (envList as any)?.items ?? [];
+    const envNames = items
+      .map(item => item?.metadata?.name)
+      .filter((name): name is string => Boolean(name));
+    if (envNames.length === 0) {
+      throw new Error(
+        `No environments found in namespace '${namespaceName}' to resolve observability URLs through`,
+      );
+    }
+
+    let lastError: Error | undefined;
+    for (const envName of envNames) {
+      try {
+        const result = await this.resolveForEnvironment(
+          namespaceName,
+          envName,
+          token,
+        );
+        if (result.observerUrl) {
+          this.putInCache(cacheKey, result);
+          return result;
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        this.logger?.debug(
+          `Failed to resolve observability URLs via environment '${envName}' in namespace '${namespaceName}': ${lastError.message}`,
+        );
+      }
+    }
+
+    throw (
+      lastError ??
+      new Error(
+        `No environment in namespace '${namespaceName}' resolved to an observability plane`,
+      )
+    );
+  }
+
   /**
    * Resolve observability URLs for build logs.
    *

packages/portal-app/src/components/Root/Root.tsx

@@ -39,6 +39,7 @@ import { identityApiRef, useApi } from '@backstage/core-plugin-api';
 import CategoryIcon from '@material-ui/icons/Category';
 import BubbleChartIcon from '@material-ui/icons/BubbleChart';
 import MonetizationOnIcon from '@material-ui/icons/MonetizationOn';
+import SpeedIcon from '@material-ui/icons/Speed';
 import { AssistantDrawerProvider } from '@openchoreo/backstage-plugin-openchoreo-portal-assistant';
 // This app composes some OpenChoreo entity tabs itself via legacy
 // `EntityLayout.Route` JSX (see EntityPage.tsx), so they render OUTSIDE the
@@ -232,6 +233,11 @@ export const Root = ({ children }: PropsWithChildren<{}>) => {
                   to="platform-overview"
                   text="Platform"
                 />
+                <SidebarItem
+                  icon={SpeedIcon}
+                  to="delivery-insights"
+                  text="Delivery Insights"
+                />
                 <SidebarItem
                   icon={MonetizationOnIcon}
                   to="cost-insights"

packages/portal-app/src/createPortalApp.tsx

@@ -20,7 +20,10 @@ import { HomePage } from './components/Home';
 import { CustomGraphNode } from '@openchoreo/backstage-plugin-react';
 import { PageLoader } from '@openchoreo/backstage-design-system';
 import { PlatformOverviewPage } from './components/platformOverview';
-import { CostInsightsPage } from '@openchoreo/backstage-plugin-openchoreo-observability';
+import {
+  CostInsightsPage,
+  DeliveryInsightsPage,
+} from '@openchoreo/backstage-plugin-openchoreo-observability';
 
 import { AlertDisplay, OAuthRequestDialog } from '@backstage/core-components';
 import { createApp } from '@backstage/frontend-defaults';
@@ -167,6 +170,7 @@ const routes = (
     />
     <Route path="/platform-overview" element={<PlatformOverviewPage />} />
     <Route path="/cost-insights" element={<CostInsightsPage />} />
+    <Route path="/delivery-insights" element={<DeliveryInsightsPage />} />
     {/*
       Standalone full-window exec terminal, opened in a new browser tab from the
       resource drawer. The page renders a fixed viewport overlay over the app

plugins/openchoreo-observability-backend/src/router.test.ts

@@ -61,15 +61,33 @@ describe('createRouter', () => {
     });
   });
 
-  it('should return 400 when resolve-urls is missing parameters', async () => {
+  it('should return 400 when resolve-urls is missing namespaceName', async () => {
     const response = await request(app).get('/resolve-urls').query({});
 
     expect(response.status).toBe(400);
     expect(response.body).toMatchObject({
-      error: 'namespaceName and environmentName are required',
+      error: 'namespaceName is required',
     });
   });
 
+  it('should resolve observer URLs at namespace level when environmentName is omitted', async () => {
+    observabilityService.resolveUrls.mockResolvedValue({
+      observerUrl: 'https://observer.example.com',
+      rcaAgentUrl: 'https://rca.example.com',
+    });
+
+    const response = await request(app)
+      .get('/resolve-urls')
+      .query({ namespaceName: 'org-1' });
+
+    expect(response.status).toBe(200);
+    expect(observabilityService.resolveUrls).toHaveBeenCalledWith(
+      'org-1',
+      '',
+      undefined,
+    );
+  });
+
   it('should not allow unauthenticated requests to resolve-urls', async () => {
     const response = await request(app)
       .get('/resolve-urls')

plugins/openchoreo-observability-backend/src/router.ts

@@ -32,17 +32,17 @@ export async function createRouter({
     if (authEnabled) {
       await httpAuth.credentials(req, { allow: ['user'] });
     }
+    // environmentName is optional: when absent, URLs resolve at namespace level
+    // (used by cross-environment scopes such as the Insights pages).
     const { namespaceName, environmentName } = req.query;
-    if (!namespaceName || !environmentName) {
-      return res
-        .status(400)
-        .json({ error: 'namespaceName and environmentName are required' });
+    if (!namespaceName) {
+      return res.status(400).json({ error: 'namespaceName is required' });
     }
     const userToken = getUserTokenFromRequest(req);
     try {
       const urls = await observabilityService.resolveUrls(
         namespaceName as string,
-        environmentName as string,
+        (environmentName as string | undefined) ?? '',
         userToken,
       );
       return res.status(200).json(urls);

plugins/openchoreo-observability-backend/src/services/ObservabilityService.ts

@@ -38,6 +38,10 @@ export class ObservabilityService {
   /**
    * Resolves the observer, RCA agent, and FinOps agent URLs for a given namespace and environment.
    * Used by the frontend to make direct calls to observer/RCA/FinOps APIs.
+   *
+   * When `environmentName` is empty, resolves at namespace level (first environment
+   * that reaches an observability plane) — used by cross-environment scopes such as
+   * the Insights pages.
    */
   async resolveUrls(
     namespaceName: string,
@@ -48,6 +52,9 @@ export class ObservabilityService {
     rcaAgentUrl?: string;
     finopsAgentUrl?: string;
   }> {
+    if (!environmentName) {
+      return this.resolver.resolveForNamespace(namespaceName, userToken);
+    }
     return this.resolver.resolveForEnvironment(
       namespaceName,
       environmentName,