Documentation: many properties in cuebot/opencue.properties lack inline docs

[DiegoTavares]

Summary

While reviewing cuebot/src/main/resources/opencue.properties it became clear that a substantial number of properties have no inline documentation (no preceding comment describing what the property does, units, valid range, or default behavior). This makes it hard for operators to know what they can safely tune, what units values are in, and what the behavioral implications are — especially when overriding via JVM -D / Spring Boot CLI args / env vars in Docker deployments.

This issue is documentation-only — proposing inline comments be added above each listed property in opencue.properties. No behavior change is requested.

Properties with no inline documentation

File: cuebot/src/main/resources/opencue.properties

Top-of-file properties

• L1 cue.proxy — what is this Ice/legacy proxy string used for? Is it still needed?
• L2 spring.velocity.checkTemplateLocation — why is this set, and is it still needed given current Spring Boot version?

Datasource (HikariCP) — no section header, no per-property docs

• L4 datasource.cue-data-source.driver-class-name
• L5 datasource.cue-data-source.jdbc-url
• L6 datasource.cue-data-source.username
• L7 datasource.cue-data-source.password

HikariCP — likely incorrect comment

• L29-30 datasource.cue-data-source.leak-detection-threshold — comment reads How often to check for idle connections that can be evicted (30 seconds), but this property is HikariCP's leak detection threshold (time a connection can be out of the pool before a leak is logged), not an idle-eviction interval. The doc should be corrected.

gRPC ports / message size

• L32 grpc.cue_port — Cuebot's main gRPC port (clients/GUI)
• L33 grpc.rqd_server_port — RQD report server port
• L34 grpc.max_message_bytes — max inbound gRPC message size; units (bytes)

Thread pools — section header # Healthy Threadpool Executor exists, but per-property docs are missing

• L49 booking_queue.threadpool.health_threshold
• L50 booking_queue.threadpool.core_pool_size
• L51 booking_queue.threadpool.max_pool_size
• L52 booking_queue.threadpool.queue_capacity
• L53 dispatch.threadpool.core_pool_size
• L54 dispatch.threadpool.max_pool_size
• L55 dispatch.threadpool.queue_capacity
• L56 healthy_threadpool.health_threshold
• L57 healthy_threadpool.min_unhealthy_period_min

Report / kill queues

• L62 report_queue.threadPoolSizeInitial
• L63 report_queue.threadPoolSizeMax
• L66 kill_queue.threadPoolSizeInitial
• L67 kill_queue.threadPoolSizeMax
• L68 kill_queue.queueSize

Kafka producer settings — section header only, no per-property docs

• L249 monitoring.kafka.acks (valid values: 0, 1, all)
• L250 monitoring.kafka.retries
• L251 monitoring.kafka.batch.size (bytes)
• L252 monitoring.kafka.linger.ms
• L253 monitoring.kafka.buffer.memory (bytes)
• L254 monitoring.kafka.compression.type (valid: none/gzip/snappy/lz4/zstd)

Kafka consumer settings — section header only, no per-property docs

• L257 monitoring.kafka.consumer.group.id
• L258 monitoring.kafka.consumer.auto.offset.reset (valid: earliest/latest/none)
• L259 monitoring.kafka.consumer.enable.auto.commit
• L260 monitoring.kafka.consumer.auto.commit.interval.ms
• L261 monitoring.kafka.consumer.max.poll.records

Elasticsearch connection — section header only, no per-property docs

• L268 monitoring.elasticsearch.host
• L269 monitoring.elasticsearch.port
• L270 monitoring.elasticsearch.scheme (valid: http/https)

Suggested format

For consistency with the well-documented sections (e.g. dispatcher.memory.*, maintenance.*), each entry should include:

1. One-line description of what the property controls.
2. Units, where applicable (ms, seconds, bytes, percent, etc.).
3. Default value.
4. Valid values / range, where applicable.
5. Behavioral side-effect (e.g. setting this above X may cause Y).

Why this matters

Cuebot is a Spring Boot application — every property here can be overridden via JVM -Dprop=value, Spring Boot --prop=value, or environment variables when running in Docker. Operators tuning a deployment (pool sizes, gRPC limits, Kafka/ES integrations) currently have to read Java source to understand what each property does. Inline comments would dramatically lower that bar.