@gravitee/gamma-lib-observability 1.29.0 → 1.30.0

package/INTEGRATION.md

@@ -35,8 +35,8 @@ Your module must provide these packages. They are **not** bundled by the library
 | `react-dom`                 | ^19.0.0         |                                                                                                                                                                              |
 | `react-router-dom`          | ^7.0.0          |                                                                                                                                                                              |
 | `@tanstack/react-query`     | ^5.0.0          | Must be a **shared singleton** if using Module Federation                                                                                                                    |
-| `@gravitee/graphene-core`   | ^2.33.0         | Design system primitives (buttons, popovers, tables, icons)                                                                                                                  |
-| `@gravitee/graphene-charts` | ^2.33.0         | Chart components (dashboard widgets, trace waterfall & lineage). Sub-paths `/dashboard-grid` and `/lineage` are used.                                                        |
+| `@gravitee/graphene-core`   | ^2.49.0         | Design system primitives (buttons, popovers, tables, icons)                                                                                                                  |
+| `@gravitee/graphene-charts` | ^2.49.0         | Chart components (dashboard widgets, trace waterfall & lineage). Sub-paths `/dashboard-grid` and `/lineage` are used.                                                        |
 | `react-grid-layout`         | ^2.0.0          | Required by `@gravitee/graphene-charts/dashboard-grid`. The lib does **not** bundle it.                                                                                      |
 | `@xyflow/react`             | ^12.0.0         | **Optional.** Only required to render the trace **Lineage** view; lazy-loaded, so apps that never open it can omit it. See [Tracing — Lineage view](#tracing--lineage-view). |
 | `tailwindcss`               | ^4.0.0          | Optional — only if you compile Tailwind yourself                                                                                                                             |
@@ -115,8 +115,8 @@ shared: {
   'react-dom': { singleton: true, requiredVersion: '^19.0.0' },
   'react-router-dom': { singleton: true, requiredVersion: '^7.0.0' },
   '@tanstack/react-query': { singleton: true, requiredVersion: '^5.0.0' },
-  '@gravitee/graphene-core': { singleton: true, requiredVersion: '^2.16.0' },
-  '@gravitee/graphene-charts': { singleton: true, requiredVersion: '^2.25.0' },
+  '@gravitee/graphene-core': { singleton: true, requiredVersion: '^2.49.0' },
+  '@gravitee/graphene-charts': { singleton: true, requiredVersion: '^2.49.0' },
   'react-grid-layout': { singleton: true, requiredVersion: '^2.0.0' },
 }
 ```
@@ -320,7 +320,7 @@ time bucket.
 }
 ```
 
-- `axisId`: `'left'` (default) or `'right'` — requires `@gravitee/graphene-charts` ≥ 2.38 with dual-axis support.
+- `axisId`: `'left'` (default) or `'right'` — requires `@gravitee/graphene-charts` ≥ 2.49 with dual-axis support.
 - `unit`: optional suffix for tooltips (`1,234 req`, `250 ms`).
 - Omit `axisId` on every series to keep the previous single-axis behaviour.
 
@@ -347,15 +347,11 @@ Context filters are always-on filters silently merged into every data query. Use
 dashboards: {
   enabled: true,
   templates: [apiOverviewTemplate],
-  contextFilters: [
-    { field: 'API_TYPE', label: 'API Type', operator: 'in', value: ['MCP', 'LLM'] },
-  ],
-  scopeFilterField: 'API_TYPE',
+  scopeApiTypes: ['MCP', 'LLM'],
 }
 ```
 
-- `contextFilters` — merged into every `fetchTimeSeries`, `fetchFacets`, `fetchMeasures` call
-- `scopeFilterField` — restricts which filter providers appear in the FilterBar (only those whose `scopes` include the active values)
+`scopeApiTypes` generates `API_TYPE` context filters (merged into every analytics query) and sets `scopeFilterField` to restrict which filter providers appear in the FilterBar. For non-API_TYPE scoping, use `contextFilters` + `scopeFilterField` directly.
 
 ### Cross-section links (Dashboards → Logs)
 
@@ -425,8 +421,7 @@ export const observability = defineObservabilityFeatures({
     dashboards: { enabled: true, templates: myTemplates },
     logs: {
       enabled: true,
-      contextFilters: [{ field: 'ENTRYPOINT', label: 'Entrypoint', operator: 'in', value: ['http-proxy'] }],
-      scopeFilterField: 'ENTRYPOINT',
+      scopeApiTypes: ['HTTP_PROXY'],
       pageSize: 25,
       columnVisibilityStorageKey: 'apim-logs-columns',
     },
@@ -521,15 +516,15 @@ const columns: LogColumnDefinition<ConnectionLog>[] = [
 
 Column variants: `text` (default), `badge`, `status-code`, `duration`, `datetime`, `http-method`.
 
-### Scope filtering via ENTRYPOINT
+### Scope filtering via API_TYPE
 
-The Gravitee v2 logs search API supports filtering by `ENTRYPOINT`. Common entrypoint values by API type:
+Logs scope by `API_TYPE`, the same unified vocabulary used by dashboards:
 
-| API type | Entrypoint values                         |
-| -------- | ----------------------------------------- |
-| MCP      | `['mcp-proxy', 'mcp']`                    |
-| LLM      | `['llm-proxy']`                           |
-| HTTP     | `['http-proxy', 'http-get', 'http-post']` |
+| API type | Filter values    |
+| -------- | ---------------- |
+| MCP      | `['MCP']`        |
+| LLM      | `['LLM']`        |
+| HTTP     | `['HTTP_PROXY']` |
 
 ### Custom logs page (escape hatch)
 
@@ -622,7 +617,7 @@ For full data type reference, see [`USAGE_GUIDE.md` — Widget Integration Level
 
 ## Feature: Traces
 
-Trace support ships a full UI route (`observe/tracing`) with search, filters, and detail views. Tracing endpoints live under the **Gamma API** (not management-v2), so the lib needs a separate base URL:
+Trace support ships a full UI route (`observe/tracing`) with search, filters, and detail views. Tracing endpoints live under the same Gamma API surface as all other observability endpoints:
 
 ```ts
 import type {
@@ -664,18 +659,19 @@ The capability key `observability.traces.read` is already wired.
 
 ### tracesBaseUrl
 
-Tracing endpoints use the Gamma API prefix (`/gamma/organizations/{orgId}/environments/{envId}`) instead of management-v2. Pass `tracesBaseUrl` to `<observability.Routes>`:
+Since `baseUrl` is now Gamma-scoped, `tracesBaseUrl` is redundant — it falls back to `baseUrl` when omitted. It is kept for backward compatibility:
 
 ```tsx
-import { buildObservabilityBaseUrl, buildTracesBaseUrl } from '@gravitee/gamma-lib-observability';
+import { buildObservabilityBaseUrl } from '@gravitee/gamma-lib-observability';
 
-const baseUrl = buildObservabilityBaseUrl(managementBaseURL, environmentId);
-const tracesBaseUrl = buildTracesBaseUrl(gammaBaseURL, organizationId, environmentId);
+const baseUrl = buildObservabilityBaseUrl(gammaBaseURL, organizationId, environmentId);
 
-<observability.Routes baseUrl={baseUrl} tracesBaseUrl={tracesBaseUrl} http={httpConfig} />;
+<observability.Routes baseUrl={baseUrl} http={httpConfig} />;
 ```
 
-`buildTracesBaseUrl` follows the same pattern as `buildObservabilityBaseUrl`:
+Both `buildObservabilityBaseUrl` and `buildTracesBaseUrl` now produce identical Gamma-scoped URLs. `tracesBaseUrl` is optional and falls back to `baseUrl`.
+
+`buildTracesBaseUrl` is kept as a backward-compatible alias:
 
 ```ts
 import { buildTracesBaseUrl } from '@gravitee/gamma-lib-observability';
@@ -698,7 +694,7 @@ const tracesBaseUrl = buildTracesBaseUrl(bootstrapConfig.gammaBaseURL, organizat
 // → '/gamma/organizations/DEFAULT/environments/DEFAULT'
 ```
 
-When `tracesBaseUrl` is omitted, the lib falls back to `baseUrl` (management-v2 prefix) for backward compatibility during migration.
+When `tracesBaseUrl` is omitted, the lib falls back to `baseUrl`. Both now produce identical Gamma-scoped URLs, so the prop is only needed for backward compatibility.
 
 ---
 
@@ -861,10 +857,10 @@ Guard the mount on the SDK environment being ready, with a fallback for standalo
 
 ```tsx
 import { useModuleEnvironment } from '@gravitee/gamma-modules-sdk';
-import { buildObservabilityBaseUrl, buildTracesBaseUrl } from '@gravitee/gamma-lib-observability';
+import { buildObservabilityBaseUrl } from '@gravitee/gamma-lib-observability';
 
 function ObservabilitySection() {
-  const { environmentId, organizationId, managementBaseURL, gammaBaseURL, isReady } = useModuleEnvironment();
+  const { environmentId, organizationId, gammaBaseURL, isReady } = useModuleEnvironment();
 
   // Standalone dev has no host env to wait for — mount immediately.
   const awaitingHostEnv = import.meta.env.PROD && !isReady;
@@ -872,9 +868,8 @@ function ObservabilitySection() {
     return null; // or a lightweight skeleton
   }
 
-  const baseUrl = buildObservabilityBaseUrl(managementBaseURL, environmentId);
-  const tracesBaseUrl = buildTracesBaseUrl(gammaBaseURL, organizationId, environmentId);
-  return <observability.Routes baseUrl={baseUrl} tracesBaseUrl={tracesBaseUrl} http={httpConfig} /* … */ />;
+  const baseUrl = buildObservabilityBaseUrl(gammaBaseURL, organizationId, environmentId);
+  return <observability.Routes baseUrl={baseUrl} http={httpConfig} /* … */ />;
 }
 ```
 
@@ -891,28 +886,31 @@ Build the observability `baseUrl` from your module's bootstrap config using the
 ```ts
 import { buildObservabilityBaseUrl } from '@gravitee/gamma-lib-observability';
 
-// Production — managementBaseURL is an absolute URL from bootstrap
+// Production — gammaBaseURL is an absolute URL from bootstrap
 const baseUrl = buildObservabilityBaseUrl(
-  bootstrapConfig.managementBaseURL, // e.g. 'https://apim-master-api.cloud.gravitee.io/management'
+  bootstrapConfig.gammaBaseURL, // e.g. 'https://apim-master-api.cloud.gravitee.io/gamma'
+  organizationId, // e.g. 'DEFAULT'
   environmentId, // e.g. 'DEFAULT'
 );
-// → 'https://apim-master-api.cloud.gravitee.io/management/v2/environments/DEFAULT'
+// → 'https://apim-master-api.cloud.gravitee.io/gamma/organizations/DEFAULT/environments/DEFAULT'
 ```
 
-When a local dev proxy forwards `/management/*` requests to the real API, pass `{ useDevProxy: true }` to strip the origin:
+When a local dev proxy forwards `/gamma/*` requests to the real API, pass `{ useDevProxy: true }` to strip the origin:
 
 ```ts
-const baseUrl = buildObservabilityBaseUrl(bootstrapConfig.managementBaseURL, environmentId, { useDevProxy: true });
-// → '/management/v2/environments/DEFAULT'  (origin stripped, browser hits the proxy)
+const baseUrl = buildObservabilityBaseUrl(bootstrapConfig.gammaBaseURL, organizationId, environmentId, {
+  useDevProxy: true,
+});
+// → '/gamma/organizations/DEFAULT/environments/DEFAULT'  (origin stripped, browser hits the proxy)
 ```
 
-The `useDevProxy` option extracts the pathname from an absolute `managementBaseURL` so the browser fetches through the local dev proxy instead of directly hitting the remote API origin. When `managementBaseURL` is already a relative path (e.g. `/management`), the option is a no-op.
+The `useDevProxy` option extracts the pathname from an absolute `gammaBaseURL` so the browser fetches through the local dev proxy instead of directly hitting the remote API origin. When `gammaBaseURL` is already a relative path (e.g. `/gamma`), the option is a no-op.
 
-The library uses `baseUrl` to construct its built-in HTTP adapters: `createHttpDataSource(baseUrl)` for metrics, `createHttpFilterSource(baseUrl)` for filters, and `createHttpLogsSource(baseUrl)` for logs. Tracing adapters (`createHttpTracesSource`, `createHttpTracesFilterSource`) use `tracesBaseUrl` when provided, falling back to `baseUrl`. If you pass custom overrides (`dataSource`, `filterProviders`, `logsDataSource`, `tracesDataSource`), these URLs are still required for any remaining internal HTTP calls.
+The library uses `baseUrl` to construct its built-in HTTP adapters: `createHttpDataSource(baseUrl)` for metrics, `createHttpFilterSource(baseUrl)` for filters, and `createHttpLogsSource(baseUrl)` for logs. All adapters target the unified `/observability/*` surface. If you pass custom overrides (`dataSource`, `filterProviders`, `logsDataSource`, `tracesDataSource`), these URLs are still required for any remaining internal HTTP calls.
 
 ### Authenticated backends (`createHttpDataSource` options)
 
-The built-in `createHttpDataSource(baseUrl, options?)` adapter speaks the Gravitee Management v2 analytics contract (`/analytics/measures`, `/analytics/facets`, `/analytics/time-series`). It accepts an `options` argument for hosts that need to plug their auth flow:
+The built-in `createHttpDataSource(baseUrl, options?)` adapter speaks the Gravitee unified observability analytics contract (`/observability/analytics/measures`, `/observability/analytics/facets`, `/observability/analytics/time-series`). It accepts an `options` argument for hosts that need to plug their auth flow:
 
 ```ts
 import { createHttpDataSource } from '@gravitee/gamma-lib-observability';
@@ -943,7 +941,7 @@ const dataSource = createHttpDataSource(baseUrl, {
 
 ### Built-in logs adapter (`createHttpLogsSource`)
 
-The built-in `createHttpLogsSource(baseUrl, options?)` adapter speaks the Gravitee Management v2 logs contract (`POST /logs/search`). It is automatically used by `ObservabilityRoutes` when `config.features.logs.enabled` is true and no explicit `logsDataSource` prop is provided.
+The built-in `createHttpLogsSource(baseUrl, options?)` adapter speaks the unified Gamma logs contract (`POST /observability/logs/search`). It is automatically used by `ObservabilityRoutes` when `config.features.logs.enabled` is true and no explicit `logsDataSource` prop is provided.
 
 ```ts
 import { createHttpLogsSource } from '@gravitee/gamma-lib-observability';
@@ -951,8 +949,6 @@ import { createHttpLogsSource } from '@gravitee/gamma-lib-observability';
 const logsSource = createHttpLogsSource(baseUrl, {
   credentials: 'include',
   headers: () => ({ 'X-Xsrf-Token': readXsrfTokenFromCookie() }),
-  // Override the search endpoint path (default: '/logs/search')
-  searchPath: '/observability/logs',
 });
 ```
 
@@ -961,11 +957,11 @@ const logsSource = createHttpLogsSource(baseUrl, {
 | `fetch`       | Custom fetch implementation — useful when the host already has an authenticated client |
 | `headers`     | Static `HeadersInit` or a factory called per-request (re-evaluated for every call)     |
 | `credentials` | Forwarded to `fetch` — `'include'` when the host relies on cookies                     |
-| `searchPath`  | Path appended to `baseUrl` for log search. Defaults to `'/logs/search'`                |
+| `searchPath`  | Path appended to `baseUrl` for log search. Defaults to `'/observability/logs/search'`  |
 
 **Wire format**: pagination (`page`, `perPage`) is sent as query params. The POST body contains `{ timeRange: { from, to }, filters: [...] }` where filters use the same wire format as the metrics adapter.
 
-**`getById`**: fetches a single log via the same search endpoint with a `REQUEST_ID` EQ filter. Uses the time range from the last `fetchLogs` call (falls back to a 10-year window if no prior call). This strategy is isolated internally and will be updated if a dedicated `GET /logs/:id` endpoint becomes available.
+**`getById`**: fetches a single log via `GET /observability/logs/{requestId}?apiId={apiId}`. The `apiId` is extracted from the log row at click time via the `logsGetApiId` prop. Returns `null` on 404.
 
 ### Custom data source
 
@@ -1165,17 +1161,11 @@ const trafficTemplate = defineDashboardTemplate({
 
 export const observability = defineObservabilityFeatures({
   basePath: 'observe',
+  scopeApiTypes: ['HTTP_PROXY'],
   features: {
-    dashboards: {
-      enabled: true,
-      templates: [trafficTemplate],
-      contextFilters: [{ field: 'API_TYPE', label: 'API Type', operator: 'in', value: ['HTTP'] }],
-      scopeFilterField: 'API_TYPE',
-    },
+    dashboards: { enabled: true, templates: [trafficTemplate] },
     logs: {
       enabled: true,
-      contextFilters: [{ field: 'ENTRYPOINT', label: 'Entrypoint', operator: 'in', value: ['http-proxy'] }],
-      scopeFilterField: 'ENTRYPOINT',
       pageSize: 25,
       columnVisibilityStorageKey: 'my-module-logs-columns',
     },

package/QUERYING.md

@@ -11,11 +11,11 @@ request field they expose, the defaults the library injects, and copy-pasteable
 
 ## 1. Endpoints
 
-| Endpoint                      | Used by widgets          | Returns                                     |
-| ----------------------------- | ------------------------ | ------------------------------------------- |
-| `POST /analytics/measures`    | `metric`, `metric-group` | aggregated metric values (`MetricResult[]`) |
-| `POST /analytics/facets`      | `doughnut`, `bar`        | grouped buckets (`FacetBucket[]`)           |
-| `POST /analytics/time-series` | `cartesian`              | data points over time (`TimeSeriesGroup[]`) |
+| Endpoint                                    | Used by widgets          | Returns                                     |
+| ------------------------------------------- | ------------------------ | ------------------------------------------- |
+| `POST /observability/analytics/measures`    | `metric`, `metric-group` | aggregated metric values (`MetricResult[]`) |
+| `POST /observability/analytics/facets`      | `doughnut`, `bar`        | grouped buckets (`FacetBucket[]`)           |
+| `POST /observability/analytics/time-series` | `cartesian`              | data points over time (`TimeSeriesGroup[]`) |
 
 ### Capability matrix