@gravitee/gamma-lib-observability 1.29.0 → 1.30.0

package/USAGE_GUIDE.md

@@ -8,8 +8,8 @@ Your module must provide:
 - `react-dom` ^19.0.0
 - `react-router-dom` ^7.0.0
 - `@tanstack/react-query` ^5.0.0
-- `@gravitee/graphene-core` ^2.16.0
-- `@gravitee/graphene-charts` ^2.0.0
+- `@gravitee/graphene-core` ^2.49.0
+- `@gravitee/graphene-charts` ^2.49.0
 
 > **Important:** Your module root must wrap with `<QueryClientProvider>`. The lib does not instantiate its own `QueryClient`.
 
@@ -21,150 +21,99 @@ yarn add @gravitee/gamma-lib-observability
 
 ## Quick start
 
-### 1. Wrap providers at module root
+Three steps to get a working observability section in your module. The library handles data fetching, filter state, URL persistence, and page rendering internally — no manual provider wiring or custom data sources needed.
 
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import {
-  CapabilityProvider,
-  MetricsDataSourceProvider,
-  LogsDataSourceProvider,
-  TracesDataSourceProvider,
-  DashboardPersistenceProvider,
-} from '@gravitee/gamma-lib-observability';
+### 1. Define features
 
-const queryClient = new QueryClient({
-  defaultOptions: { queries: { staleTime: 30_000 } },
+Declare which observability features your module enables and scope them to your API types via `scopeApiTypes`:
+
+```ts
+import { defineObservabilityFeatures } from '@gravitee/gamma-lib-observability';
+import { myDashboardTemplates } from './templates';
+
+export const observability = defineObservabilityFeatures({
+  scopeApiTypes: ['MCP', 'LLM'],
+  features: {
+    dashboards: { enabled: true, templates: myDashboardTemplates },
+    logs: { enabled: true },
+    tracing: { enabled: true },
+  },
+  nav: { label: 'Observability' },
 });
+```
+
+`scopeApiTypes` generates `API_TYPE` context filters and scoped filter providers for all features. Override per-feature when needed (e.g. logs scoped to `['MCP']` only while dashboards sees `['MCP', 'LLM']`).
+
+### 2. Mount routes
+
+Mount `<observability.Routes>` under your module's route tree. Pass `baseUrl` (built from the Gamma API origin) and `http` for authentication. The library auto-creates all HTTP data sources, filter providers, pages, and log columns internally.
+
+```tsx
+import { buildObservabilityBaseUrl } from '@gravitee/gamma-lib-observability';
+import { observability } from './config/observability';
+
+function AppRoutes() {
+  const baseUrl = buildObservabilityBaseUrl(gammaBaseURL, organizationId, environmentId);
 
-function App() {
   return (
-    <QueryClientProvider client={queryClient}>
-      <CapabilityProvider capabilities={myCapabilities}>
-        <MetricsDataSourceProvider dataSource={myMetricsDataSource}>
-          <LogsDataSourceProvider dataSource={myLogsDataSource}>
-            <TracesDataSourceProvider dataSource={myTracesDataSource}>
-              <DashboardPersistenceProvider persistence={myPersistence}>
-                {/* your routes */}
-              </DashboardPersistenceProvider>
-            </TracesDataSourceProvider>
-          </LogsDataSourceProvider>
-        </MetricsDataSourceProvider>
-      </CapabilityProvider>
-    </QueryClientProvider>
+    <Routes>
+      <Route
+        path="observe/*"
+        element={
+          <observability.Routes
+            baseUrl={baseUrl}
+            http={{ credentials: 'include', headers: () => ({ 'X-Xsrf-Token': readXsrfToken() }) }}
+          />
+        }
+      />
+    </Routes>
   );
 }
 ```
 
-### 2. Define capabilities
+Log columns default to `buildDefaultConnectionLogColumns`, and row identity defaults to `row.requestId` / `row.apiId`. Override via `logsColumns`, `logsGetRowId`, `logsGetApiId` for custom row types (see [Advanced: Custom data sources](#advanced-custom-data-sources)).
 
-```ts
-import type { DashboardCapabilities } from '@gravitee/gamma-lib-observability';
+### 3. Register navigation
 
-const myCapabilities: DashboardCapabilities = {
-  'observability.dashboards.read': true,
-  'observability.dashboards.write': false,
-  'observability.logs.read': true,
-  'observability.traces.read': false,
-};
-```
+Add the lib's nav group to your module's sidenav. Only enabled features appear as items.
 
-The default (when no `CapabilityProvider` is present) is all capabilities set to `false` (secure default).
+```ts
+const NAV_GROUPS = [...existingGroups, observability.navGroup];
+```
 
-### 3. Implement DataSource adapters
+That's it — you now have dashboards, logs, and tracing with scoped filters, URL-persisted state, and authenticated HTTP requests. See the sections below for customization options.
 
-Each module implements the `MetricsDataSource`, `LogsDataSource<TRow>`, and/or `TracesDataSource` interfaces to translate its backend API responses into the expected shapes.
+## Testing
 
-#### Metrics (universal shape)
+The lib exports a testing helper from the `./testing` subpath:
 
-```ts
-import type { MetricsDataSource } from '@gravitee/gamma-lib-observability';
+```tsx
+import { renderWithObservability } from '@gravitee/gamma-lib-observability/testing';
 
-export const myMetricsDataSource: MetricsDataSource = {
-  async fetchTimeSeries(request) {
-    const { metric, timeRange, filters, signal } = request;
-    const response = await fetch(`/api/metrics/timeseries?metric=${metric}`, { signal });
-    return response.json();
-  },
-  async fetchFacets(request) {
-    const { field, timeRange, signal } = request;
-    const response = await fetch(`/api/metrics/facets?field=${field}`, { signal });
-    return response.json();
-  },
-  async fetchMeasures(request) {
-    const { metrics, timeRange, signal } = request;
-    const response = await fetch(`/api/metrics/measures`, {
-      method: 'POST',
-      body: JSON.stringify({ metrics }),
-      signal,
-    });
-    return response.json();
-  },
+const mockMetrics: MetricsDataSource = {
+  fetchTimeSeries: vi.fn().mockResolvedValue([]),
+  fetchFacets: vi.fn().mockResolvedValue([]),
+  fetchMeasures: vi.fn().mockResolvedValue([]),
 };
-```
-
-#### Logs (generic — each module defines its own row type)
 
-```ts
-import type { LogsDataSource } from '@gravitee/gamma-lib-observability';
-
-// 1. Define your log row type
-interface HttpProxyLog {
-  id: string;
-  timestamp: string;
-  method: string;
-  status: number;
-  uri: string;
-  apiId: string;
-  apiName: string;
-  responseTime: number;
-}
-
-// 2. Implement the typed data source
-export const httpLogsDataSource: LogsDataSource<HttpProxyLog> = {
-  async fetchLogs(query) {
-    const response = await fetch('/api/logs', {
-      method: 'POST',
-      body: JSON.stringify({
-        timeRange: query.timeRange,
-        filters: query.filters,
-        search: query.search,
-        page: query.page,
-        perPage: query.perPage,
-      }),
-      signal: query.signal,
-    });
-    const json = await response.json();
-    return {
-      entries: json.data as HttpProxyLog[],
-      totalCount: json.total,
-      page: json.page,
-      pageCount: json.pageCount,
-    };
+const { getByText } = renderWithObservability(<MyComponent />, {
+  dataSources: { metrics: mockMetrics },
+  capabilities: {
+    'observability.dashboards.read': true,
+    'observability.dashboards.write': false,
+    'observability.logs.read': true,
+    'observability.traces.read': false,
   },
-};
+});
 ```
 
-### 4. Use TanStack Query hooks
+The helper wraps the component with `QueryClientProvider`, `CapabilityProvider`, and all DataSource providers you pass.
+
+---
 
-```tsx
-import { useTimeSeriesQuery, useMeasuresQuery } from '@gravitee/gamma-lib-observability';
-
-function RequestRateChart() {
-  const { data, isLoading, error } = useTimeSeriesQuery({
-    metrics: [{ name: 'HTTP_REQUESTS', measures: ['COUNT'] }],
-    timeRange: { type: 'relative', period: '1h' },
-    interval: 60_000,
-    by: ['HTTP_STATUS_CODE_GROUP'],
-  });
-
-  if (isLoading) return <Spinner />;
-  if (error) return <ErrorBanner error={error} />;
-  return <LineChart data={data} />;
-}
-```
+## Hooks reference
 
-Hooks available:
+The library exposes TanStack Query hooks for direct data fetching. In most cases you do not need these — the auto-mounted pages handle data fetching internally. Use them when building custom pages or embedding widgets outside the `observe/*` routes.
 
 | Hook                      | DataSource             | Returns                         |
 | ------------------------- | ---------------------- | ------------------------------- |
@@ -174,10 +123,6 @@ Hooks available:
 | `useLogsQuery<TRow>`      | `LogsDataSource<TRow>` | `LogsQueryResult<TRow>`         |
 | `useLogsPagedQuery<TRow>` | `LogsDataSource<TRow>` | `UseLogsPagedQueryResult<TRow>` |
 
-> For the full analytics request capability (measures / facets / time-series fields, `by`, `sorts`,
-> `ranges`, per-metric filters, defaults, and the widget → request mapping), see
-> [`QUERYING.md`](./QUERYING.md).
-
 All hooks:
 
 - Use `observabilityQueryKeys` for cache key derivation
@@ -185,57 +130,107 @@ All hooks:
 - Default `staleTime: 30_000`. `refetchOnWindowFocus` is **not** set by the library — your host `QueryClient` defaults apply (set it there if you want refetch-on-focus)
 - Accept an `enabled` param and additional TanStack Query options
 
-#### Using `useLogsQuery` with your own row type
+> For the full analytics request capability (measures / facets / time-series fields, `by`, `sorts`,
+> `ranges`, per-metric filters, defaults, and the widget → request mapping), see
+> [`QUERYING.md`](./QUERYING.md).
+
+### Using hooks with your own row type
 
 ```tsx
 import { useLogsQuery } from '@gravitee/gamma-lib-observability';
 
-// The generic parameter ensures data.entries is HttpProxyLog[]
 const { data, isLoading } = useLogsQuery<HttpProxyLog>({
   timeRange: { type: 'relative', period: '1h' },
   filters: [{ field: 'status', label: 'Status', operator: 'in', value: ['500', '502'] }],
 });
 ```
 
-### 5. Query key factory
+### Query key factory
 
 Use `observabilityQueryKeys` when you need to invalidate or prefetch:
 
 ```ts
 import { observabilityQueryKeys } from '@gravitee/gamma-lib-observability';
 
-// Invalidate all observability queries
 queryClient.invalidateQueries({ queryKey: observabilityQueryKeys.all });
-
-// Invalidate a specific dashboard
 queryClient.invalidateQueries({ queryKey: observabilityQueryKeys.dashboard('dash-123') });
 ```
 
-## Testing
+---
 
-The lib exports a testing helper from the `./testing` subpath:
+## Advanced: Custom data sources
 
-```tsx
-import { renderWithObservability } from '@gravitee/gamma-lib-observability/testing';
+In most cases, the built-in HTTP adapters (auto-created from `baseUrl`) handle all data fetching. Implement a custom `DataSource` only when you need custom response mapping, typed row objects, or a non-standard API contract.
 
-const mockMetrics: MetricsDataSource = {
-  fetchTimeSeries: vi.fn().mockResolvedValue([]),
-  fetchFacets: vi.fn().mockResolvedValue([]),
-  fetchMeasures: vi.fn().mockResolvedValue([]),
+### Custom MetricsDataSource
+
+```ts
+import type { MetricsDataSource } from '@gravitee/gamma-lib-observability';
+
+export const myMetricsDataSource: MetricsDataSource = {
+  async fetchTimeSeries(request) {
+    /* ... */
+  },
+  async fetchFacets(request) {
+    /* ... */
+  },
+  async fetchMeasures(request) {
+    /* ... */
+  },
 };
+```
 
-const { getByText } = renderWithObservability(<MyComponent />, {
-  dataSources: { metrics: mockMetrics },
-  capabilities: {
-    'observability.dashboards.read': true,
-    'observability.dashboards.write': false,
-    'observability.logs.read': true,
-    'observability.traces.read': false,
+Pass it as the `dataSource` prop on `<observability.Routes>` to override the built-in adapter.
+
+### Custom LogsDataSource
+
+```ts
+import type { LogsDataSource } from '@gravitee/gamma-lib-observability';
+
+export const myLogsDataSource: LogsDataSource<MyLogRow> = {
+  async fetchLogs(query) {
+    /* ... */
   },
-});
+  async getById(id, apiId, signal) {
+    /* ... */
+  },
+};
 ```
 
-The helper wraps the component with `QueryClientProvider`, `CapabilityProvider`, and all DataSource providers you pass.
+Pass it as the `logsDataSource` prop on `<observability.Routes>`.
+
+### Manual provider wiring
+
+When embedding widgets or hooks **outside** the `observe/*` routes (e.g. a KPI section on an API detail page), you may need to provide data sources manually. Each provider is independent — nest them in any order under `QueryClientProvider`:
+
+```tsx
+<QueryClientProvider client={queryClient}>
+  <CapabilityProvider capabilities={myCapabilities}>
+    <MetricsDataSourceProvider dataSource={myMetricsDataSource}>
+      <LogsDataSourceProvider dataSource={myLogsDataSource}>
+        {/* your custom pages using hooks directly */}
+      </LogsDataSourceProvider>
+    </MetricsDataSourceProvider>
+  </CapabilityProvider>
+</QueryClientProvider>
+```
+
+> **Note:** The nesting is a React Context requirement, not a semantic hierarchy — the providers are independent. `<observability.Routes>` creates these providers internally, so manual wiring is only needed for pages outside the managed route tree.
+
+### Capabilities (RBAC)
+
+```ts
+import type { DashboardCapabilities } from '@gravitee/gamma-lib-observability';
+
+const myCapabilities: DashboardCapabilities = {
+  'observability.dashboards.read': true,
+  'observability.dashboards.write': false,
+  'observability.logs.read': true,
+  'observability.traces.read': false,
+};
+```
+
+When no `CapabilityProvider` is present, all capabilities default to `false` (secure default).
 
 ## Canonical Types
 
@@ -665,41 +660,9 @@ Template properties:
 | `requiredCapabilities` | `CapabilityKey[]` (opt.)          | Template hidden when user lacks any listed capability |
 | `dashboard`            | `Dashboard \| (ctx) => Dashboard` | Static dashboard or factory receiving capabilities    |
 
-### Integration via `defineObservabilityFeatures`
-
-The recommended way to integrate observability into a Gamma module:
-
-```tsx
-import { defineObservabilityFeatures } from '@gravitee/gamma-lib-observability';
-import { apiOverviewTemplate, aiTemplate } from './templates';
-
-const observability = defineObservabilityFeatures({
-  features: {
-    dashboards: {
-      enabled: true,
-      templates: [apiOverviewTemplate, aiTemplate],
-      contextFilters: [{ field: 'API_TYPE', label: 'API Type', operator: 'in', value: ['MCP', 'LLM'] }],
-      scopeFilterField: 'API_TYPE',
-    },
-    logs: {
-      enabled: true,
-      contextFilters: [{ field: 'ENTRYPOINT', label: 'Entrypoint', operator: 'in', value: ['mcp-proxy', 'mcp'] }],
-      scopeFilterField: 'ENTRYPOINT',
-    },
-  },
-  nav: { label: 'Observability' },
-});
-
-// Returns:
-// observability.Routes              — React component to mount under your module's routes
-// observability.navGroup            — Navigation group descriptor for your sidenav
-// observability.routeKeys           — Array of route keys for breadcrumb integration
-// observability.routes              — Record of { path, label } for each enabled feature
-// observability.resolveRouteKey     — (pathname) => composite route key | null
-// observability.breadcrumbSegments  — (activeNavKey) => BreadcrumbSegment[] | null
-```
+### `defineObservabilityFeatures` — API reference
 
-### `ObservabilityFeatures` API reference
+`defineObservabilityFeatures` is the entry point shown in [Quick start](#quick-start) step 1. It returns an `ObservabilityFeatures` object with the following members:
 
 | Member               | Type                                                    | Description                                                                             |
 | -------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
@@ -749,37 +712,19 @@ observability.breadcrumbSegments('llm-router'); // → null
 - Returns `null` when `activeNavKey` is not an observability key.
 - The host maps the segments onto its own breadcrumb renderer (e.g. `buildLinearBreadcrumbs` + `buildModuleNavPath`) and appends any 3rd-level title (dashboard name, log detail) itself.
 
-### Mounting Routes
+### `ObservabilityRoutesProps` reference
 
-```tsx
-import { Route, Routes } from 'react-router-dom';
+See [Quick start](#quick-start) step 2 for the minimal mount. The full prop list is documented in [`INTEGRATION.md`](./INTEGRATION.md). Key props:
 
-function ModuleApp() {
-  return (
-    <CapabilityProvider capabilities={userCapabilities}>
-      <Routes>
-        <Route
-          path="observe/*"
-          element={
-            <observability.Routes
-              baseUrl="/management/v2/environments/DEFAULT"
-              tracesBaseUrl="/gamma/organizations/DEFAULT/environments/DEFAULT"
-              dataSource={myDataSource} // optional: overrides built-in HTTP metrics adapter
-              filterProviders={myProviders} // optional: overrides async filter definition fetch
-              logsDataSource={myLogsDataSource} // optional: overrides built-in HTTP logs adapter
-              logsColumns={myLogColumns} // required for auto-mounted logs page
-              logsOnRowClick={(entry) => navigate(`/logs/${(entry as MyLog).id}`)}
-              logsGetRowId={(row) => (row as MyLog).id}
-            />
-          }
-        />
-      </Routes>
-    </CapabilityProvider>
-  );
-}
-```
+- `baseUrl` (required) — Gamma-scoped URL from `buildObservabilityBaseUrl`
+- `http` — centralized auth config (`credentials`, `headers`)
+- `logsColumns` — column definitions for the auto-mounted logs table
+- `logsGetRowId` / `logsGetApiId` — row identity extractors for log detail
+- `dataSource` / `logsDataSource` / `tracesDataSource` — optional overrides for the built-in HTTP adapters (see [Advanced: Custom data sources](#advanced-custom-data-sources))
+- `filterProviders` — optional override for the async filter definition fetch
+- `logsPage` — escape hatch for a fully custom logs page
 
-When `logsColumns` are provided and the logs feature is enabled, the router auto-mounts `LogsExplorerPage`. If no `logsDataSource` prop is given, the library automatically builds one from `baseUrl` using `createHttpLogsSource` (same authentication as metrics/filters via the `http` prop or `HttpProvider`). If you need full control over the logs page layout, use the `logsPage` escape hatch instead (see below).
+When `logsColumns` are provided and the logs feature is enabled, the router auto-mounts `LogsExplorerPage`. If no `logsDataSource` prop is given, the library automatically builds one from `baseUrl` using `createHttpLogsSource` (same authentication via the `http` prop).
 
 ### Routing Behavior
 
@@ -794,15 +739,7 @@ Filter state (active filters + time range) is persisted in URL query parameters
 
 ### Navigation Group
 
-Use `observability.navGroup` to register items in your module's sidenav:
-
-```tsx
-const { navGroup } = observability;
-// navGroup.label  → 'Observability'
-// navGroup.items  → [{ key: 'observe/dashboards', title: 'Dashboards', icon: ChartLineIcon }]
-```
-
-Breadcrumbs are rendered by the calling module — the library does not own the layout shell — but the lib supplies the breadcrumb **data** (group + feature) via `observability.breadcrumbSegments(activeNavKey)`. See the [`ObservabilityFeatures` API reference](#observabilityfeatures-api-reference) above.
+See [Quick start](#quick-start) step 3. `observability.navGroup` contains `{ label, items }` — only enabled features appear as items. Breadcrumbs are rendered by the calling module; the lib supplies the data via `observability.breadcrumbSegments(activeNavKey)` (see the [API reference](#defineobservabilityfeatures--api-reference) above).
 
 ---
 
@@ -814,13 +751,13 @@ Breadcrumbs are rendered by the calling module — the library does not own the
 
 The simplest integration is via `defineObservabilityFeatures` + route props (see "Mounting Routes" above). The router auto-mounts `LogsExplorerPage` when `logsColumns` are passed to `<observability.Routes />`. The data source is resolved automatically from `baseUrl` via `createHttpLogsSource` — no explicit `logsDataSource` prop is needed unless you want to override the built-in adapter.
 
-### Scope filtering via ENTRYPOINT
+### Scope filtering via API_TYPE
 
-The Gravitee v2 logs search API supports filtering by `ENTRYPOINT` (`IN` operator). The entrypoint values map to API types:
+Logs scope by `API_TYPE`, the same vocabulary used by dashboards. Common values:
 
-- **MCP**: `['mcp-proxy', 'mcp']`
-- **LLM**: `['llm-proxy']`
-- **HTTP**: `['http-proxy', 'http-get', 'http-post']`
+- **MCP**: `['MCP']`
+- **LLM**: `['LLM']`
+- **HTTP**: `['HTTP_PROXY']`
 
 To scope the logs page to a specific API type, set `contextFilters` and `scopeFilterField` in `LogsFeatureConfig`:
 
@@ -828,9 +765,9 @@ To scope the logs page to a specific API type, set `contextFilters` and `scopeFi
 logs: {
   enabled: true,
   contextFilters: [
-    { field: 'ENTRYPOINT', label: 'Entrypoint', operator: 'in', value: ['mcp-proxy', 'mcp'] },
+    { field: 'API_TYPE', label: 'API Type', operator: 'in', value: ['MCP'] },
   ],
-  scopeFilterField: 'ENTRYPOINT',
+  scopeFilterField: 'API_TYPE',
 }
 ```
 
@@ -974,8 +911,8 @@ export const myLogsDataSource: LogsDataSource<MyLog> = {
   async fetchLogs(query) {
     /* ... */
   },
-  async getById(id, signal) {
-    const res = await fetch(`/api/logs/${id}`, { signal });
+  async getById(id, apiId, signal) {
+    const res = await fetch(`/api/logs/${id}?apiId=${apiId}`, { signal });
     if (res.status === 404) return null;
     return res.json();
   },
@@ -1046,14 +983,24 @@ import { LogDetailDrawer } from '@gravitee/gamma-lib-observability';
 
 function LogsPage() {
   const [selectedLogId, setSelectedLogId] = useState<string>();
+  const [selectedApiId, setSelectedApiId] = useState<string>();
 
   return (
     <>
-      <LogTable onRowClick={(row) => setSelectedLogId(row.id)} />
+      <LogTable
+        onRowClick={(row) => {
+          setSelectedLogId(row.id);
+          setSelectedApiId(row.apiId);
+        }}
+      />
       <LogDetailDrawer
         config={logDetailConfig}
         logId={selectedLogId}
-        onClose={() => setSelectedLogId(undefined)}
+        apiId={selectedApiId}
+        onClose={() => {
+          setSelectedLogId(undefined);
+          setSelectedApiId(undefined);
+        }}
         onNavigatePrev={() => {
           /* prev logic */
         }}

package/dist/build-observability-base-url.d.ts

@@ -1,8 +1,8 @@
 export interface BuildObservabilityBaseUrlOptions {
     /**
-     * When `true`, strips the origin from `managementBaseURL` and keeps only the
-     * pathname. Use this when a local dev proxy forwards `/management/…` requests
-     * to the real Management API — the browser must hit the proxy origin, not the
+     * When `true`, strips the origin from `gammaBaseURL` and keeps only the
+     * pathname. Use this when a local dev proxy forwards `/gamma/…` requests
+     * to the real Gamma API — the browser must hit the proxy origin, not the
      * remote one advertised in bootstrap.
      *
      * @default false
@@ -11,23 +11,23 @@ export interface BuildObservabilityBaseUrlOptions {
 }
 /**
  * Build the `baseUrl` that `<observability.Routes>` (and all built-in HTTP
- * adapters) expect.
+ * adapters) expect. All observability endpoints now live under the Gamma API:
  *
  * ```
- * managementBaseURL        environmentId     result
- * ─────────────────────    ─────────────     ──────
- * https://host/management  DEFAULT           https://host/management/v2/environments/DEFAULT
- * /management              DEFAULT           /management/v2/environments/DEFAULT
+ * gammaBaseURL             orgId   envId     result
+ * ────────────────────     ─────   ─────     ──────
+ * https://host/gamma       org-1   DEFAULT   https://host/gamma/organizations/org-1/environments/DEFAULT
+ * /gamma                   org-1   DEFAULT   /gamma/organizations/org-1/environments/DEFAULT
  * ```
  *
- * With `{ useDevProxy: true }`, an absolute `managementBaseURL` is reduced to
- * its pathname before the `/v2/environments/{envId}` suffix is appended:
+ * With `{ useDevProxy: true }`, an absolute `gammaBaseURL` is reduced to
+ * its pathname before the org/env suffix is appended:
  *
  * ```
- * https://host/management  DEFAULT  { useDevProxy: true }  →  /management/v2/environments/DEFAULT
+ * https://host/gamma  org-1  DEFAULT  { useDevProxy: true }  →  /gamma/organizations/org-1/environments/DEFAULT
  * ```
  *
  * The function is **pure** — it never fetches bootstrap or reads env vars.
  */
-export declare function buildObservabilityBaseUrl(managementBaseURL: string, environmentId: string, options?: BuildObservabilityBaseUrlOptions): string;
+export declare function buildObservabilityBaseUrl(gammaBaseURL: string, organizationId: string, environmentId: string, options?: BuildObservabilityBaseUrlOptions): string;
 //# sourceMappingURL=build-observability-base-url.d.ts.map

package/dist/build-observability-base-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-observability-base-url.d.ts","sourceRoot":"","sources":["../src/build-observability-base-url.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gCAAgC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CACvC,iBAAiB,EAAE,MAAM,EACzB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,gCAAgC,GACzC,MAAM,CAcR"}
+{"version":3,"file":"build-observability-base-url.d.ts","sourceRoot":"","sources":["../src/build-observability-base-url.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gCAAgC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,gCAAgC,GACzC,MAAM,CAcR"}

package/dist/build-traces-base-url.d.ts

@@ -1,15 +1,13 @@
-export interface BuildTracesBaseUrlOptions {
-    /**
-     * When `true`, strips the origin from `gammaBaseURL` and keeps only the
-     * pathname. Use this when a local dev proxy forwards `/gamma/…` requests
-     * to the real Gamma API — the browser must hit the proxy origin, not the
-     * remote one advertised in bootstrap.
-     *
-     * @default false
-     */
-    readonly useDevProxy?: boolean;
-}
+import { BuildObservabilityBaseUrlOptions } from './build-observability-base-url';
 /**
+ * @deprecated Use {@link buildObservabilityBaseUrl} instead — both now produce
+ * identical Gamma-scoped URLs. This alias is kept for backward compatibility.
+ */
+export type BuildTracesBaseUrlOptions = BuildObservabilityBaseUrlOptions;
+/**
+ * @deprecated Use {@link buildObservabilityBaseUrl} instead — both now produce
+ * identical Gamma-scoped URLs. This alias is kept for backward compatibility.
+ *
  * Build the `tracesBaseUrl` that tracing HTTP adapters expect.
  *
  * Tracing endpoints live under the Gamma API, which is org-scoped:
@@ -21,13 +19,6 @@ export interface BuildTracesBaseUrlOptions {
  * /gamma                 org-1   DEFAULT   /gamma/organizations/org-1/environments/DEFAULT
  * ```
  *
- * With `{ useDevProxy: true }`, an absolute `gammaBaseURL` is reduced to
- * its pathname before the org/env suffix is appended:
- *
- * ```
- * https://host/gamma  org-1  DEFAULT  { useDevProxy: true }  →  /gamma/organizations/org-1/environments/DEFAULT
- * ```
- *
  * The function is **pure** — it never fetches bootstrap or reads env vars.
  */
 export declare function buildTracesBaseUrl(gammaBaseURL: string, organizationId: string, environmentId: string, options?: BuildTracesBaseUrlOptions): string;

package/dist/build-traces-base-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-traces-base-url.d.ts","sourceRoot":"","sources":["../src/build-traces-base-url.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,yBAAyB,GAClC,MAAM,CAcR"}
+{"version":3,"file":"build-traces-base-url.d.ts","sourceRoot":"","sources":["../src/build-traces-base-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,gCAAgC,EAAE,MAAM,gCAAgC,CAAC;AAElH;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,gCAAgC,CAAC;AAEzE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,yBAAyB,GAClC,MAAM,CAER"}

package/dist/data-sources/http-data-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-data-source.d.ts","sourceRoot":"","sources":["../../src/data-sources/http-data-source.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAY9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAuB/D,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACrE;AAsJD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,iBAAiB,CA+CxG"}
+{"version":3,"file":"http-data-source.d.ts","sourceRoot":"","sources":["../../src/data-sources/http-data-source.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAY9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAuB/D,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACrE;AAsJD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,iBAAiB,CAuDxG"}

package/dist/data-sources/http-filter-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-filter-source.d.ts","sourceRoot":"","sources":["../../src/data-sources/http-filter-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,4BAA4B,CAAC;AACxG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAgD9D,MAAM,WAAW,YAAY;IAC3B,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACxE,aAAa,CACX,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,YAAY,CA6G3F"}
+{"version":3,"file":"http-filter-source.d.ts","sourceRoot":"","sources":["../../src/data-sources/http-filter-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,4BAA4B,CAAC;AACxG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAsD9D,MAAM,WAAW,YAAY;IAC3B,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACxE,aAAa,CACX,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,YAAY,CA8G3F"}