Current state: Under Discussion
Discussion thread: TODO
JIRA: TODO
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
KIP-714 introduced the ClientTelemetryReceiver interface to enable MetricsReporter instances running on brokers to collect client telemetry metrics. Typically a reporter stores metrics it receives in a "metrics registry" and exposes them in a format suitable for the external monitoring system is built for. This is exactly what JmxReporter does. Kafka clients and brokers explicitly delete their metrics when they are not used anymore. However for client telemetry metrics there isn't an explicit deletion mechanism.
Clients send their telemetry metrics at a regular interval, configured via telemetry subscriptions. Reporters are not aware of this push interval. Without the interval and an explicit deletion mechanism, reporters don't know when to clear client telemetry metrics and stop exposing them. This makes it hard to not expose stale metrics. Having uncertainty in metrics is a major problem as operators rely on them to manage their clusters.
package org.apache.kafka.server.telemetry;
import org.apache.kafka.server.authorizer.AuthorizableRequestContext;
public interface ClientTelemetryContext extends AuthorizableRequestContext {
int pushInterval();
AuthorizableRequestContext authorizableRequestContext();
} |
A new method in ClientTelemetryReceiver
/**
* Called by the broker when a client reports telemetry metrics. The associated telemetry context
* can be used by the metrics plugin to retrieve additional client information such as client ids,
* endpoints or the push interval.
* <p>
* This method may be called from the request handling thread, and as such should avoid blocking.
*
* @param context the client telemetry context for the corresponding {@code PushTelemetryRequest}
* api call.
* @param payload the encoded telemetry payload as sent by the client.
*/
default void exportMetrics(ClientTelemetryContext context, ClientTelemetryPayload payload) {
exportMetrics(context.authorizableRequestContext(), payload);
} |
Deprecate the existing ClientTelemetryReceiver.exportMetrics() method
/**
* Called by the broker when a client reports telemetry metrics. The associated request context
* can be used by the metrics plugin to retrieve additional client information such as client ids
* or endpoints.
* <p>
* This method may be called from the request handling thread, and as such should avoid blocking.
* <p>
* This method is deprecated, {@link #exportMetrics(ClientTelemetryContext, ClientTelemetryPayload)} should be used
* instead.
*
* @param context the client request context for the corresponding {@code PushTelemetryRequest}
* api call.
* @param payload the encoded telemetry payload as sent by the client.
*/
@Deprecated(since = "4.2.0")
void exportMetrics(AuthorizableRequestContext context, ClientTelemetryPayload payload); |
The new method has a default implementation so it should not break existing classes implementing ClientTelemetryReceiver.
Implementations that want to benefit from the new context need to override both the new and old exportMetrics() methods. The body for the old method can be the following for example, since it won't be called if void exportMetrics(ClientTelemetryContext context, ClientTelemetryPayload payload) is also implemented.
public void exportMetrics(AuthorizableRequestContext context, ClientTelemetryPayload payload) {
throw new IllegalStateException("Should not be called");
} |
Adequate unit and integration tests will be added to ensure ClientTelemetryReceiver implementations use the old or new contexts.
N/A