Documentation: Metrics endpoint information is incomplete and potentially incorrect

[fivetran-arunsuri]

Describe the bug

The current telemetry docs has misleading information about the metrics endpoint that may cause confusion for users setting up Prometheus scraping.

Issues Found

1. Port number may be incorrect
   The documentation states:
   "they are available from Polaris's management interface (port 8282 by default)"

However, in our deployment (and checking the default configuration), the management port is 8182, not 8282.

2. Incomplete endpoint documentation
   The documentation only mentions /q/metrics:
   "under the path /q/metrics. For example, if the server is running on localhost, the metrics can be accessed via http://localhost:8282/q/metrics"

However, Quarkus with Micrometer also exposes metrics at /metrics (the standard Prometheus endpoint), which is not documented.

Testing Results

When testing against a running Polaris 1.0 instance:

Both endpoints return identical metrics

curl localhost:8182/metrics # ✅ Works (standard Prometheus path)
curl localhost:8182/q/metrics # ✅ Works (Quarkus-specific path)

Both endpoints return the exact same metric data.

Why This Matters

1. Standard Prometheus tooling expects /metrics - Most Prometheus configurations, ServiceMonitors, and scraping tools default to /metrics, not /q/metrics
2. Port confusion - Users may waste time troubleshooting connectivity if the port number is wrong
3. Real-world impact - In our case, our infrastructure was already scraping /metrics successfully, but the documentation made us question if we had configured it correctly

Suggested Documentation Fix

Update the telemetry documentation to:

1. Correct the port number (or clarify it's configurable):
   Metrics are available from Polaris's management interface (port 8182 by default, configurable via quarkus.management.port)
2. Document both endpoints:
   Metrics are exposed at two paths:

• /metrics - Standard Prometheus endpoint (recommended for most use cases)
• /q/metrics - Quarkus-specific management endpoint

Both paths return identical metrics. For example, if the server is running on localhost:

• http://localhost:8182/metrics
• http://localhost:8182/q/metrics

3. Add a note about Prometheus scraping:
   Note: Standard Prometheus configurations and Kubernetes ServiceMonitors typically use /metrics by default.

Environment

• Polaris Version: 1.2
• Runtime: Quarkus 3.25.4
• Deployment: Kubernetes

Happy to contribute the fix if everyone of us agree to this

[rishii-19-works]

Hi @fivetran-arunsuri I went through the issue and I can confirm the mismatch in the documentation. The management interface actually comes up on 8182, and both /metrics and /q/metrics return the same Micrometer data in Polaris. This can definitely confuse users who rely on Prometheus defaults.

I’d be happy to open a small PR to update the telemetry docs with the correct port info and mention both endpoints. Let me know if this looks good, and I’ll proceed with the fix.