Merge pull request #4713 from ClickHouse/clickstack-json-not-prod-ready

adding warning to make it even more clear that JSON is in beta

Author: dhtclk

docs/use-cases/observability/clickstack/deployment/_snippets/_json_support.md

@@ -4,11 +4,17 @@ import BetaBadge from '@theme/badges/BetaBadge';
 
 <BetaBadge/>
 
+:::warning Beta Feature
+JSON type support in ClickStack is a **beta feature**. While it is under active development and supported by the ClickHouse team, it may have limitations, change in the future, or contain bugs. 
+
+**For production use**, ensure you are running **ClickHouse version 25.3 or later**, where the JSON type is production-ready. For earlier versions of ClickHouse, the JSON type is not recommended for production use.
+:::
+
 ClickStack has beta support for the [JSON type](/interfaces/formats/JSON) from version `2.0.4`.
 
 For the benefits of this type see [Benefits of the JSON type](/use-cases/observability/clickstack/ingesting-data/otel-collector#benefits-json-type).
 
 In order to enable support for the JSON type users must set the following environment variables:
 
 - `OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json'` - enables support in the OTel collector, ensuring schemas are created using the JSON type.
-- `BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true` - enables support in the HyperDX application, allowing JSON data to be queried.
+- `BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true` - enables support in the HyperDX application, allowing JSON data to be queried.

docs/use-cases/observability/clickstack/deployment/hyperdx-clickhouse-cloud.md

@@ -20,6 +20,7 @@ import hyperdx_create_new_source from '@site/static/images/use-cases/observabili
 import hyperdx_create_trace_datasource from '@site/static/images/use-cases/observability/hyperdx_create_trace_datasource.png';
 import read_only from '@site/static/images/clickstack/read-only-access.png';
 import { TrackedLink } from '@site/src/components/GalaxyTrackedLink/GalaxyTrackedLink';
+import JSONSupport from '@site/docs/use-cases/observability/clickstack/deployment/_snippets/_json_support.md';
 
 <PrivatePreviewBadge/>
 
@@ -336,16 +337,6 @@ If using your own schema, we recommend creating a Logs source ensuring the requi
 
 </VerticalStepper>
 
-## JSON type support {#json-type-support}
+<JSONSupport/>
 
-<BetaBadge/>
-
-ClickStack has beta support for the [JSON type](/interfaces/formats/JSON) from version `2.0.4`.
-
-For the benefits of this type, see [Benefits of the JSON type](/use-cases/observability/clickstack/ingesting-data/otel-collector#benefits-json-type).
-
-In order to enable support for the JSON type, users must set the following environment variables:
-
-- `OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json'` - enables support in the OTel collector, ensuring schemas are created using the JSON type.
-
-Additionally, users should contact support@clickhouse.com to ensure JSON is enabled on both their ClickHouse Cloud service.
+Additionally, users should contact support@clickhouse.com to ensure JSON is enabled on both their ClickHouse Cloud service.

docs/use-cases/observability/clickstack/ingesting-data/collector.md

@@ -297,6 +297,12 @@ For agent instances responsible for shipping events to a gateway, and only setti
 
 <BetaBadge/>
 
+:::warning Beta Feature
+JSON type support in ClickStack is a **beta feature**. While it is under active development and supported by the ClickHouse team, it may have limitations, change in the future, or contain bugs. 
+
+**For production use**, ensure you are running **ClickHouse version 25.3 or later**, where the JSON type is production-ready. For earlier versions of ClickHouse, the JSON type is not recommended for production use.
+:::
+
 ClickStack has beta support for the [JSON type](/interfaces/formats/JSON) from version `2.0.4`.
 
 ### Benefits of the JSON type {#benefits-json-type}
@@ -327,7 +333,7 @@ docker run -e OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' -e O
 ### Migrating from map-based schemas to the JSON type {#migrating-from-map-based-schemas-to-json}
 
 :::important Backwards compatibility
-The [JSON type](/interfaces/formats/JSON) type is not backwards compatible with existing map-based schemas. New tables will be created using the `JSON` type.
+The [JSON type](/interfaces/formats/JSON) is **not backwards compatible** with existing map-based schemas. Enabling this feature will create new tables using the `JSON` type and requires manual data migration.
 :::
 
 To migrate from the Map-based schemas, follow these steps: