Handle Debug service in agent connection metrics middleware

[rausingh-rh]

Pull Request check list

• Commit conforms to CONTRIBUTING.md?
• Proper tests/regressions included?
• Documentation updated?

Affected functionality

Agent metrics middleware (pkg/agent/endpoints/metrics.go), service name constants (pkg/common/api/middleware/names.go), and Debug API telemetry helpers (pkg/common/telemetry/agent/adminapi/debugapi.go).

Description of change

The agent's connectionMetrics middleware did not have a case for the Debug service (spire.agent.debug.v1.Debug) in its Preprocess/Postprocess switch statements. This caused a misconfiguration error to be logged every time the Debug API was called:

unrecognized service for connection metrics: spire.agent.debug.v1.Debug

Since the Debug API is typically polled on a schedule (e.g., by monitoring tools), this produced recurring error noise every minute.

Changes:

• Add DebugServiceName and DebugServiceShortName constants in names.go, with a serviceReplacer mapping so logs and metrics use the clean short name "Debug" instead of the full proto path
• Add IncrDebugAPIConnectionCounter and SetDebugAPIConnectionGauge telemetry helpers in debugapi.go, following the same pattern as the DelegatedIdentity helpers
• Handle DebugServiceName in the Preprocess/Postprocess switch, emitting connection counter and gauge metrics (consistent with other agent services like DelegatedIdentity)
• Add a focused regression test (TestDebugServiceConnectionMetrics) that verifies no misconfiguration error is logged and connection metrics are emitted
• Add a guard-rail test (TestAllAgentServicesHandledByConnectionMetrics) that exercises every agent gRPC service through the middleware to catch similar issues in the future

Which issue this PR fixes

Fixes #5183

[sorindumitru]

We don't emit metrics about the health and reflection services because they're gRPC services and possibly not that interesting. It might still be nice to have some metrics for it. Would it be possible to also emit the 2 metrics we emit for the other services? (connection counter and connection gauge).

Also happy to take this as is, since it fixes a real problem.

[rausingh-rh]

Thanks for the suggestion @sorindumitru ! That makes sense, I have updated the PR to emit connection counter and gauge metrics for the Debug service, following the same pattern as DelegatedIdentity. Added IncrDebugAPIConnectionCounter and SetDebugAPIConnectionGauge helper functions in pkg/common/telemetry/agent/adminapi/debugapi.go, and the regression test now asserts the metrics are actually emitted.

[sorindumitru]

This is looking good, thanks @rausingh-rh. Could you also add the new metrics to https://github.com/spiffe/spire/blob/main/doc/telemetry/telemetry.md ?

[rausingh-rh]

Done! Added the debug_api connection and connections metrics to doc/telemetry/telemetry.md.

[sorindumitru]

LGTM, thanks @rausingh-rh !

[rausingh-rh]

Hi @sorindumitru the PR was failing because of the milestone check. I have rebased the branch with latest main.