docs(config): refine metrics related config documentations (#1125)

Signed-off-by: Shichao Nie <[email protected]>

core/src/main/scala/kafka/server/KafkaConfig.scala

@@ -537,17 +537,18 @@ object KafkaConfig {
   val S3NetworkBaselineBandwidthDoc = "The total available bandwidth for object storage requests. This is used to prevent stream set object compaction and catch-up read from monopolizing normal read and write traffic. Produce and Consume will also separately consume traffic in and traffic out. " +
     "For example, suppose this value is set to 100MB/s, and the normal read and write traffic is 80MB/s, then the available traffic for stream set object compaction is 20MB/s."
   val S3RefillPeriodMsDoc = "The network bandwidth token refill period in milliseconds."
-  val S3MetricsEnableDoc = "Whether to enable metrics exporter for s3stream."
+  val S3MetricsEnableDoc = "Whether to enable OTel metrics exporter."
   val S3TracerEnableDoc = "Whether to enable tracer exporter for s3stream."
-  val S3MetricsLevelDoc = "The metrics level, supported value: INFO, DEBUG"
-  val S3MetricsExporterTypeDoc = "The enabled S3 metrics exporters type, seperated by comma. Supported type: otlp, prometheus, log"
+  val S3MetricsLevelDoc = "The metrics level that will be used on recording metrics. The \"INFO\" level includes most of the metrics that users should care about, for example throughput and latency of common stream operations. " +
+    "The \"DEBUG\" level includes detailed metrics that would help with diagnosis, for example latency of different stages when writing to underlying block device."
+  val S3MetricsExporterTypeDoc = "The list of metrics exporter types that should be used. The \"otlp\" type will export metrics to backend service with OTLP protocol. The \"prometheus\" type will start a built-in HTTP server that allows Prometheus backend scrape metrics from it."
   val S3TraceExporterOTLPEndpointDoc = "The endpoint of OTLP collector for traces"
-  val S3ExporterOTLPEndpointDoc = "The endpoint of OTLP collector"
-  val S3ExporterOTLPProtocolDoc = "The protocol of OTLP collector, supported value: grpc or http, default: grpc"
+  val S3ExporterOTLPEndpointDoc = "The endpoint of the backend service that the metrics should be exported to when using OTLP exporter."
+  val S3ExporterOTLPProtocolDoc = "The protocol to use when using OTLP exporter"
   val S3ExporterOTLPCompressionEnableDoc = "Whether to enable compression for OTLP exporter, valid only when use http protocol"
-  val S3ExporterReportIntervalMsDoc = "The interval in milliseconds to report telemetry"
-  val S3MetricsExporterPromHostDoc = "The host address of Prometheus http server to expose the metrics"
-  val S3MetricsExporterPromPortDoc = "The port of Prometheus http server to expose the metrics"
+  val S3ExporterReportIntervalMsDoc = "This configuration controls how often the metrics should be exported."
+  val S3MetricsExporterPromHostDoc = "The host address of the built-in Prometheus HTTP server that used to expose the OTel metrics."
+  val S3MetricsExporterPromPortDoc = "The port number of the built-in Prometheus HTTP server that used to expose the OTel metrics."
   val S3SpanScheduledDelayMsDoc = "The delay in milliseconds to export queued spans"
   val S3SpanMaxQueueSizeDoc = "The max number of spans that can be queued before dropped"
   val S3SpanMaxBatchSizeDoc = "The max number of spans that can be exported in a single batch"