Use panel setting to determine API mode (#128)

* Add buildModeInfo to plugin description

* Use a panel setting to determine childCount or not

* Revert supportsChildCount from pluginJson

* Try and restore e2e behaviour

* Correct defaults

* Correct env behaviour

Author: nojaf

.config/webpack/webpack.config.ts

@@ -193,9 +193,10 @@ const config = async (env: Env): Promise<Configuration> => {
     plugins: [
       new BuildModeWebpackPlugin(),
       virtualPublicPath,
-      // Define environment variables for build-time configuration
+      // Define environment variable for setting default panel option value
+      // Default is true (child count enabled). Set SUPPORTS_CHILD_COUNT=0 to disable.
       new webpack.DefinePlugin({
-        'process.env.SUPPORTS_CHILD_COUNT': JSON.stringify(process.env.SUPPORTS_CHILD_COUNT === '1'),
+        'process.env.SUPPORTS_CHILD_COUNT': process.env.SUPPORTS_CHILD_COUNT !== '0',
       }),
       // Insert create plugin version information into the bundle
       new webpack.BannerPlugin({

.github/workflows/ci.yml

@@ -134,8 +134,8 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build plugin
-        run: bun run build
+      - name: Build plugin (without child count for standard Tempo tests)
+        run: bun run build:without-child-count
 
       - name: Start Grafana
         run: |
@@ -171,8 +171,8 @@ jobs:
       - name: Stop grafana docker (after regular tests)
         run: docker compose down
 
-      - name: Build with child count support
-        run: bun run build:with-child-count
+      - name: Build plugin (with child count, default)
+        run: bun run build
 
       - name: Start Grafana (for child count tests)
         run: |

.github/workflows/release.yml

@@ -33,7 +33,7 @@ jobs:
         run: bun install --frozen-lockfile
 
       - name: Build plugin
-        run: bun run build:with-child-count
+        run: bun run build
 
       - name: Package unsigned plugin
         run: bun ./scripts/package-plugin.js

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.2.0] - 2025-11-04
+
+### Changed
+
+- Converted `SUPPORTS_CHILD_COUNT` from build-time environment variable to runtime panel option. The plugin now uses a panel setting "Enable G-Research Tempo API support" that can be configured per panel when editing a dashboard. This allows a single build to work with both standard Grafana Tempo API and G-Research custom Tempo API.
+- Removed `build:with-child-count` script. Use `bun run build` for all builds.
+- Updated release workflow to use standard build process.
+
+### Added
+
+- Panel option "Enable G-Research Tempo API support" for runtime configuration of child count support.
+- Support for setting default panel option value via `SUPPORTS_CHILD_COUNT` environment variable for local development (e.g., `SUPPORTS_CHILD_COUNT=1 bun run dev`).
+
 ## [0.1.5] - 2025-10-31
 
 ### Added

README.md

@@ -19,18 +19,34 @@ For detailed usage instructions and troubleshooting, see [HELP.md](HELP.md).
 
 App plugins can let you create a custom out-of-the-box monitoring experience by custom pages, nested data sources and panel plugins.
 
-## Build-time Configuration
+## Panel Configuration
 
-The plugin supports build-time configuration through environment variables. Create a `.env` file in the root directory and set the following variables:
+The plugin supports runtime configuration through panel options. To configure the setting:
 
-- `SUPPORTS_CHILD_COUNT`: Set to `'1'` to enable child count support, `'0'` to disable it. This affects whether the plugin will use `childCount` attributes from the backend. Default is `'false'`.
+1. Create or edit a panel using this plugin on a dashboard
+2. In the panel edit mode, look for the "Enable G-Research Tempo API support" option in the panel options panel (right sidebar)
+3. Toggle the setting as needed
 
-Example `.env` file:
+**Setting**: Enable G-Research Tempo API support
+
+- A boolean setting that controls whether the plugin uses child count support for G-Research custom Tempo API. When enabled, the plugin will use `childCount` attributes from the backend. When disabled, it works with the standard Grafana Tempo API.
+
+### Development Default
+
+By default, child count support is **enabled** (for G-Research custom Tempo API). For local development with standard Grafana Tempo API, you can disable it:
 
 ```bash
-SUPPORTS_CHILD_COUNT=0
+# Default: child count enabled (for G-Research custom Tempo API)
+bun run dev
+
+# Disable for standard Grafana Tempo API
+SUPPORTS_CHILD_COUNT=0 bun run dev
+# Or use the convenience script:
+bun run dev:without-child-count
 ```
 
+This sets the default value for new panels, but you can still override it per panel in the UI.
+
 ## Get started
 
 ### Frontend
@@ -53,12 +69,6 @@ SUPPORTS_CHILD_COUNT=0
    bun run build
    ```
 
-   To build with child count support enabled:
-
-   ```bash
-   bun run build:with-child-count
-   ```
-
 4. Run the tests (using Jest)
 
    ```bash
@@ -256,13 +266,12 @@ Minor differences:
 
 ## API discrepancies
 
-To differentiate between the Grafana Tempo API and the G-Research–flavoured Tempo API, the plugin checks the `SUPPORTS_CHILD_COUNT` environment variable.
-Building with `SUPPORTS_CHILD_COUNT=1` results in the runtime behavior described above.
+To differentiate between the Grafana Tempo API and the G-Research–flavoured Tempo API, the plugin uses a panel setting called "Enable G-Research Tempo API support". When enabled, the plugin will use the G-Research custom API features like child count support. When disabled, it works with the standard Grafana Tempo API.
 
 ## Testing
 
 We run end-to-end using Playwright and `@grafana/plugin-e2e`.
-There are two ways to run the tests, there is setup for when `SUPPORTS_CHILD_COUNT=0` or `SUPPORTS_CHILD_COUNT=1`.
+There are two ways to run the tests, depending on which API you want to test against (standard Grafana Tempo API or G-Research custom API).
 In both cases, we rely on a provisioned Docker compose setup.
 
 **Playwright requires Chromium as a dependency**
@@ -275,18 +284,18 @@ _Why is this not part of our package.json?_
 
 Chromium cannot be installed in our production environment, so we do not include it as a required dependency in package.json.
 
-### SUPPORTS_CHILD_COUNT = 0
+### Standard Grafana Tempo API
 
 Run `bun run server` to start the regular developer setup.  
 Here we shall target the Grafana Tempo API as mentioned in [./docker-compose.yaml].
 
 Run
 
 ```shell
-bun run build
+bun run build:without-child-count
 ```
 
-to build a bundle without `SUPPORTS_CHILD_COUNT`.
+to build the plugin without child count support (for standard Grafana Tempo API). When creating or editing a panel on a dashboard, make sure "Enable G-Research Tempo API support" is disabled in the panel options.
 
 Next, we need to provision sample data to our Tempo store.
 Run
@@ -303,7 +312,7 @@ Afterwards all pieces are in place to run the e2e tests:
 bun run e2e
 ```
 
-### SUPPORTS_CHILD_COUNT = 1
+### G-Research Custom Tempo API
 
 To simulate the production API, we have constructed a different Docker setup in [local-tempo-docker-compose.yml](./local-tempo-docker-compose.yml).
 There we also have a `Tempo` service, so from Grafana's point of view nothing will have changed.
@@ -323,12 +332,14 @@ In production, this would be the .NET side of things, for our local setup, we ca
 bun run tests/test-api.ts
 ```
 
-Next, build our plugin using `SUPPORTS_CHILD_COUNT=1` via
+Next, build our plugin (default has child count enabled):
 
 ```shell
-bun run build:with-child-count
+bun run build
 ```
 
+The default panel option will have "Enable G-Research Tempo API support" enabled, which is correct for this setup.
+
 Afterwards, you should be able to run the tests using:
 
 ```shell
@@ -338,7 +349,7 @@ bun run e2e
 ### Updating the test Trace
 
 In `scripts/e2e-tempo-trace.js`, we have a test scenario.
-To ensure we use the same data during `SUPPORTS_CHILD_COUNT=1`.
+To ensure we use the same data when testing with G-Research custom Tempo API.
 You can extract the last trace to [tests/test-trace.json](./tests/test-trace.json) via
 
 ```shell

package.json

@@ -1,10 +1,11 @@
 {
   "name": "grafana-incremental-trace-viewer",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "scripts": {
     "build": "webpack -c ./.config/webpack/webpack.config.ts --env production",
-    "build:with-child-count": "SUPPORTS_CHILD_COUNT=1 webpack -c ./.config/webpack/webpack.config.ts --env production",
+    "build:without-child-count": "SUPPORTS_CHILD_COUNT=0 webpack -c ./.config/webpack/webpack.config.ts --env production",
     "dev": "webpack -w -c ./.config/webpack/webpack.config.ts --env development",
+    "dev:without-child-count": "SUPPORTS_CHILD_COUNT=0 webpack -w -c ./.config/webpack/webpack.config.ts --env development",
     "test": "jest --watch --onlyChanged",
     "test:ci": "jest --passWithNoTests --maxWorkers 4",
     "typecheck": "tsc --noEmit",

src/components/Span/SpanDetailsPanel.tsx

@@ -5,14 +5,7 @@ import { IconButton, Input } from '@grafana/ui';
 import type { SpanInfo } from '../../types';
 import { formatUnixNanoToDateTime, formatDuration } from 'utils/utils.timeline';
 import { useQuery } from '@tanstack/react-query';
-import {
-  KeyValue,
-  AnyValue,
-  FetchFunction,
-  TagAttributes,
-  getTagAttributesForSpan,
-  supportsChildCount,
-} from 'utils/utils.api';
+import { KeyValue, AnyValue, FetchFunction, TagAttributes, getTagAttributesForSpan } from 'utils/utils.api';
 import { Accordion } from './Accordion';
 
 function collectTagAttributes(result: KeyValue[]): TagAttributes {
@@ -143,10 +136,12 @@ export function SpanDetailPanel({
   span,
   onClose,
   fetchFn,
+  supportsChildCount,
 }: {
   span: SpanInfo;
   onClose: () => void;
   fetchFn: FetchFunction<any>;
+  supportsChildCount: boolean;
 }) {
   const [expandedSections, setExpandedSections] = useState({
     additionalData: false,

src/components/TraceDetail.tsx

@@ -4,7 +4,7 @@ import { useVirtualizer } from '@tanstack/react-virtual';
 import { testIds } from './testIds';
 import { Span as SpanComponent, SpanDetailPanel } from './Span';
 import { mkUnixEpochFromNanoSeconds, mkUnixEpochFromMiliseconds, formatDuration } from '../utils/utils.timeline';
-import { FetchFunction, search, SearchResponse, Span, supportsChildCount } from '../utils/utils.api';
+import { FetchFunction, search, SearchResponse, Span } from '../utils/utils.api';
 import type { QueryInfo as TraceDetailProps } from './TraceViewerPanel';
 import { SpanOverlayDrawer } from './Span/SpanOverlayDrawer';
 import { ChildStatus, SpanInfo } from 'types';
@@ -140,14 +140,18 @@ async function extractSpans(
   return spans;
 }
 
-const pipeSelect = `| select (span:name, resource.service.name${supportsChildCount ? ', childCount' : ''})`;
+function getPipeSelect(supportsChildCount: boolean): string {
+  return `| select (span:name, resource.service.name${supportsChildCount ? ', childCount' : ''})`;
+}
 
 async function loadMoreSpans(
   fetchFn: FetchFunction<SearchResponse>,
   traceId: string,
   idToLevelMap: Map<string, number>,
-  span: SpanInfo
+  span: SpanInfo,
+  supportsChildCount: boolean
 ): Promise<SpanInfo[]> {
+  const pipeSelect = getPipeSelect(supportsChildCount);
   const q = `{ trace:id = "${traceId}" && span:parentID = "${span.spanId}" } ${pipeSelect}`;
   const start = mkUnixEpochFromNanoSeconds(span.startTimeUnixNano);
   // As a precaution, we add 1 second to the end time.
@@ -166,7 +170,8 @@ function TraceDetail({
   panelWidth,
   panelHeight,
   timeRange,
-}: TraceDetailProps & { timeRange: TimeRange }): React.JSX.Element {
+  supportsChildCount,
+}: TraceDetailProps & { timeRange: TimeRange; supportsChildCount: boolean }): React.JSX.Element {
   // Should we assert for traceId and datasourceId?
   if (!traceId || !datasourceUid) {
     throw new Error('traceId and datasourceId are required');
@@ -212,6 +217,7 @@ function TraceDetail({
         setLoadingMessage('Loading root nodes of trace');
         const start = mkUnixEpochFromMiliseconds(startTimeInMs);
         const end = mkUnixEpochFromMiliseconds(startTimeInMs + durationInMs);
+        const pipeSelect = getPipeSelect(supportsChildCount);
         const q = `{ trace:id = "${traceId}" && nestedSetParent = -1 } ${pipeSelect}`;
         const data = await search(fetchFn, q, start, end);
         // We pass in hasMore: false because we are fetching the first round of children later.
@@ -233,7 +239,7 @@ function TraceDetail({
           }
           allSpans.push(span);
           if (!hasNoChildren) {
-            const moreSpans = await loadMoreSpans(fetchFn, traceId, idToLevelMap.current, span);
+            const moreSpans = await loadMoreSpans(fetchFn, traceId, idToLevelMap.current, span, supportsChildCount);
             allSpans.push(...moreSpans);
           }
         }
@@ -328,7 +334,7 @@ function TraceDetail({
     });
 
     // Load the children
-    const spans = await loadMoreSpans(fetchFn, traceId, idToLevelMap.current, span);
+    const spans = await loadMoreSpans(fetchFn, traceId, idToLevelMap.current, span, supportsChildCount);
 
     // Update the parent span to show children
     queryClient.setQueryData<SpanInfo[]>(queryKey, (oldData) => {
@@ -524,6 +530,7 @@ function TraceDetail({
               setSelectedSpanElementYOffset(null);
             }}
             fetchFn={fetchFn}
+            supportsChildCount={supportsChildCount}
           />
         )}
       </SpanOverlayDrawer>

src/components/TraceViewerPanel.tsx

@@ -4,10 +4,11 @@ import { Icon, TextLink } from '@grafana/ui';
 import TraceDetail from './TraceDetail';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { HelpModal } from './HelpModal';
+import { PanelOptions } from '../types';
 
 const queryClient = new QueryClient();
 
-interface Props extends PanelProps<{}> {}
+interface Props extends PanelProps<PanelOptions> {}
 
 export type QueryInfo = {
   datasourceUid: string;
@@ -152,6 +153,7 @@ export const TraceViewerPanel: React.FC<Props> = ({ options, data, width, height
         // Grafana adds padding-block of 8px
         panelHeight={height + 16}
         timeRange={timeRange}
+        supportsChildCount={options.supportsChildCount ?? false}
       />
     </QueryClientProvider>
   );

src/module.ts

@@ -1,5 +1,19 @@
 import { PanelPlugin } from '@grafana/data';
 import { TraceViewerPanel } from './components/TraceViewerPanel';
 import './styles/tailwind.css';
+import { PanelOptions } from './types';
 
-export const plugin = new PanelPlugin<{}>(TraceViewerPanel);
+// Allow setting default value via environment variable for local development
+// Default is true (child count enabled). Set SUPPORTS_CHILD_COUNT=0 to disable.
+// Usage: SUPPORTS_CHILD_COUNT=0 bun run dev
+// Note: webpack DefinePlugin replaces process.env.SUPPORTS_CHILD_COUNT with a boolean literal (true or false)
+const defaultSupportsChildCount = process.env.SUPPORTS_CHILD_COUNT as unknown as boolean;
+
+export const plugin = new PanelPlugin<PanelOptions>(TraceViewerPanel).setPanelOptions((builder) => {
+  return builder.addBooleanSwitch({
+    path: 'supportsChildCount',
+    name: 'Enable G-Research Tempo API support',
+    description: 'Enable child count support for G-Research custom Tempo API. Disable for standard Grafana Tempo API.',
+    defaultValue: defaultSupportsChildCount, // Default is true (child count enabled)
+  });
+});