refactor: deprecate clickhouse.json feature gate in favor of per-exporter json config

Replace the deprecated --feature-gates=clickhouse.json CLI flag with the
per-exporter json: true config option, as recommended by the upstream
OpenTelemetry ClickHouse exporter (v0.149.0).

Changes:
- Add HYPERDX_CLICKHOUSE_JSON_ENABLED env var to replace OTEL_AGENT_FEATURE_GATE_ARG
- Add json field to ClickHouse exporter configs in opampController.ts
- Add json field to standalone config (config.standalone.yaml)
- Update entrypoint.sh to detect JSON mode via the new env var
- Remove feature gate pass-through from supervisor template and entrypoint
- Update docker-compose.dev.yml comments and env vars

Ref: HDX-3994

Author: wrn14897

docker-compose.dev.yml

@@ -80,9 +80,9 @@ services:
       CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml'
       # Uncomment to enable stdout logging for the OTel collector
       OTEL_SUPERVISOR_LOGS: 'true'
-      # Uncomment to enable JSON schema in ClickHouse
+      # Enable JSON schema in the ClickHouse exporter (per-exporter config)
       # Be sure to also set BETA_CH_OTEL_JSON_SCHEMA_ENABLED to 'true' in ch-server
-      OTEL_AGENT_FEATURE_GATE_ARG: '--feature-gates=clickhouse.json'
+      HYPERDX_CLICKHOUSE_JSON_ENABLED: 'true'
     volumes:
       - ./docker/otel-collector/config.yaml:/etc/otelcol-contrib/config.yaml
       - ./docker/otel-collector/supervisor_docker.yaml.tmpl:/etc/otel/supervisor.yaml.tmpl
@@ -109,7 +109,7 @@ services:
       CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
       HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
       # Set to 'true' to allow for proper OTel JSON Schema creation
-      # Be sure to also set the OTEL_AGENT_FEATURE_GATE_ARG env in otel-collector
+      # Be sure to also set HYPERDX_CLICKHOUSE_JSON_ENABLED in otel-collector
       # BETA_CH_OTEL_JSON_SCHEMA_ENABLED: 'true'
     volumes:
       - ./docker/clickhouse/local/config.xml:/etc/clickhouse-server/config.xml

docker/otel-collector/config.standalone.yaml

@@ -33,6 +33,7 @@ exporters:
     logs_table_name: hyperdx_sessions
     timeout: 5s
     create_schema: ${env:HYPERDX_OTEL_EXPORTER_CREATE_LEGACY_SCHEMA:-false}
+    json: ${env:HYPERDX_CLICKHOUSE_JSON_ENABLED:-false}
     retry_on_failure:
       enabled: true
       initial_interval: 5s
@@ -46,6 +47,7 @@ exporters:
     ttl: 720h
     timeout: 5s
     create_schema: ${env:HYPERDX_OTEL_EXPORTER_CREATE_LEGACY_SCHEMA:-false}
+    json: ${env:HYPERDX_CLICKHOUSE_JSON_ENABLED:-false}
     retry_on_failure:
       enabled: true
       initial_interval: 5s

docker/otel-collector/entrypoint.sh

@@ -1,8 +1,8 @@
 #!/bin/sh
 set -e
 
-# Fall back to legacy schema when the ClickHouse JSON feature gate is enabled
-if echo "$OTEL_AGENT_FEATURE_GATE_ARG" | grep -q "clickhouse.json"; then
+# Fall back to legacy schema when ClickHouse JSON exporter mode is enabled
+if [ "$HYPERDX_CLICKHOUSE_JSON_ENABLED" = "true" ]; then
   export HYPERDX_OTEL_EXPORTER_CREATE_LEGACY_SCHEMA=true
 fi
 
@@ -39,11 +39,6 @@ if [ -z "$OPAMP_SERVER_URL" ]; then
     COLLECTOR_ARGS="$COLLECTOR_ARGS --config $CUSTOM_OTELCOL_CONFIG_FILE"
   fi
 
-  # Pass feature gates to the collector in standalone mode
-  if [ -n "$OTEL_AGENT_FEATURE_GATE_ARG" ]; then
-    COLLECTOR_ARGS="$COLLECTOR_ARGS $OTEL_AGENT_FEATURE_GATE_ARG"
-  fi
-
   # Execute collector directly
   exec /otelcontribcol $COLLECTOR_ARGS
 else

docker/otel-collector/supervisor_docker.yaml.tmpl

@@ -23,10 +23,6 @@ agent:
 {{- if getenv "CUSTOM_OTELCOL_CONFIG_FILE" }}
     - {{ getenv "CUSTOM_OTELCOL_CONFIG_FILE" }}
 {{- end }}
-  args:
-{{- if getenv "OTEL_AGENT_FEATURE_GATE_ARG" }}
-    - {{ getenv "OTEL_AGENT_FEATURE_GATE_ARG" }}
-{{- end }}
 
 storage:
   directory: /etc/otel/supervisor-data/

packages/api/src/opamp/controllers/opampController.ts

@@ -82,6 +82,7 @@ type CollectorConfig = {
       logs_table_name: string;
       timeout: string;
       create_schema: string;
+      json: string;
       retry_on_failure: {
         enabled: boolean;
         initial_interval: string;
@@ -97,6 +98,7 @@ type CollectorConfig = {
       ttl: string;
       timeout: string;
       create_schema: string;
+      json: string;
       retry_on_failure: {
         enabled: boolean;
         initial_interval: string;
@@ -205,6 +207,7 @@ export const buildOtelCollectorConfig = (
         timeout: '5s',
         create_schema:
           '${env:HYPERDX_OTEL_EXPORTER_CREATE_LEGACY_SCHEMA:-false}',
+        json: '${env:HYPERDX_CLICKHOUSE_JSON_ENABLED:-false}',
         retry_on_failure: {
           enabled: true,
           initial_interval: '5s',
@@ -221,6 +224,7 @@ export const buildOtelCollectorConfig = (
         timeout: '5s',
         create_schema:
           '${env:HYPERDX_OTEL_EXPORTER_CREATE_LEGACY_SCHEMA:-false}',
+        json: '${env:HYPERDX_CLICKHOUSE_JSON_ENABLED:-false}',
         retry_on_failure: {
           enabled: true,
           initial_interval: '5s',