org.apache.kafka.server.quota

Interface ClientQuotaCallback

All Superinterfaces:

Configurable

public interface ClientQuotaCallback
extends Configurable

Quota callback interface for brokers that enables customization of client quota computation.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this instance.
default void	enableDynamicQuota(boolean enableDynamicQuota) Enable or Disable returning dynamic quotas as configured by updateDynamicQuotas().
default Map<String,String>	parentQuotaMetricTags(ClientQuotaType quotaType, Map<String,String> metricTags) Quota callback invoked to determine parent metric tags to be applied for an original set of metric tags.
Double	quotaLimit(ClientQuotaType quotaType, Map<String,String> metricTags) Returns the quota limit associated with the provided metric tags.
Map<String,String>	quotaMetricTags(ClientQuotaType quotaType, KafkaPrincipal principal, String clientId) Quota callback invoked to determine the quota metric tags to be applied for a request.
default Map<String,String>	quotaMetricTagsFromTopic(ClientQuotaType quotaType, String topic) Quota callback invoked to determine the quota metric tags to be applied for a topic.
boolean	quotaResetRequired(ClientQuotaType quotaType) Returns true if any of the existing quota configs may have been updated since the last call to this method for the provided quota type.
void	removeQuota(ClientQuotaType quotaType, ClientQuotaEntity quotaEntity) Quota configuration removal callback that is invoked when quota configuration for an entity is removed in the quorum.
boolean	updateClusterMetadata(Cluster cluster) Metadata update callback that is invoked whenever UpdateMetadata request is received from the controller.
default boolean	updateDynamicQuotas(Map<Map<String,String>,Map<String,Long>> dynamicQuotas) Dynamic tenant quota update callback that is invoked when a PublishTenantBandwidthQuota request is received from the controller.
void	updateQuota(ClientQuotaType quotaType, ClientQuotaEntity quotaEntity, double newValue) Quota configuration update callback that is invoked when quota configuration for an entity is updated in the quorum.

Methods inherited from interface org.apache.kafka.common.Configurable

configure

Method Detail

quotaMetricTags

Map<String,String> quotaMetricTags(ClientQuotaType quotaType,
                                   KafkaPrincipal principal,
                                   String clientId)

Quota callback invoked to determine the quota metric tags to be applied for a request. Quota limits are associated with quota metrics and all clients which use the same metric tags share the quota limit.

Parameters:

quotaType - Type of quota requested

principal - The user principal of the connection for which quota is requested

clientId - The client id associated with the request

Returns:

quota metric tags that indicate which other clients share this quota

quotaMetricTagsFromTopic

default Map<String,String> quotaMetricTagsFromTopic(ClientQuotaType quotaType,
                                                    String topic)

Quota callback invoked to determine the quota metric tags to be applied for a topic. Quota limits are associated with quota metrics and all clients which use the same metric tags share the quota limit.

Parameters:

quotaType - Type of quota requested

topic - Name of the topic the tenant name is extracted from

Returns:

quota metric tags corresponding to a parent quota

parentQuotaMetricTags

default Map<String,String> parentQuotaMetricTags(ClientQuotaType quotaType,
                                                 Map<String,String> metricTags)

Quota callback invoked to determine parent metric tags to be applied for an original set of metric tags. Defining parent metric tags allows for multiple entity quotas to be applied for a single request.

Parameters:

quotaType - Type of quota requested

metricTags - Original metric tags

Returns:

quota metric tags corresponding to a parent quota

quotaLimit

Double quotaLimit(ClientQuotaType quotaType,
                  Map<String,String> metricTags)

Returns the quota limit associated with the provided metric tags. These tags were returned from a previous call to quotaMetricTags(ClientQuotaType, KafkaPrincipal, String). This method is invoked by quota managers to obtain the current quota limit applied to a metric when the first request using these tags is processed. It is also invoked after a quota update or cluster metadata change. If the tags are no longer in use after the update, (e.g. this is a {user, client-id} quota metric and the quota now in use is a {user} quota), null is returned.

Parameters:

quotaType - Type of quota requested

metricTags - Metric tags for a quota metric of type `quotaType`

Returns:

the quota limit for the provided metric tags or null if the metric tags are no longer in use

updateQuota

void updateQuota(ClientQuotaType quotaType,
                 ClientQuotaEntity quotaEntity,
                 double newValue)

Quota configuration update callback that is invoked when quota configuration for an entity is updated in the quorum. This is useful to track configured quotas if built-in quota configuration tools are used for quota management.

Parameters:

quotaType - Type of quota being updated

quotaEntity - The quota entity for which quota is being updated

newValue - The new quota value

updateDynamicQuotas

default boolean updateDynamicQuotas(Map<Map<String,String>,Map<String,Long>> dynamicQuotas)

Dynamic tenant quota update callback that is invoked when a PublishTenantBandwidthQuota request is received from the controller. This is used to proactively update tenant quotas based on their consumption.

Parameters:

dynamicQuotas - The map of tenants to a map of client quota type to the quota value

Returns:

true if quotas have changed and metric configs may need to be updated

enableDynamicQuota

default void enableDynamicQuota(boolean enableDynamicQuota)

Enable or Disable returning dynamic quotas as configured by updateDynamicQuotas().

Parameters:

enableDynamicQuota - true if dynamicQuota is effective.

removeQuota

void removeQuota(ClientQuotaType quotaType,
                 ClientQuotaEntity quotaEntity)

Quota configuration removal callback that is invoked when quota configuration for an entity is removed in the quorum. This is useful to track configured quotas if built-in quota configuration tools are used for quota management.

Parameters:

quotaType - Type of quota being updated

quotaEntity - The quota entity for which quota is being updated

quotaResetRequired

boolean quotaResetRequired(ClientQuotaType quotaType)

Returns true if any of the existing quota configs may have been updated since the last call to this method for the provided quota type. Quota updates as a result of calls to updateClusterMetadata(Cluster), updateQuota(ClientQuotaType, ClientQuotaEntity, double) and removeQuota(ClientQuotaType, ClientQuotaEntity) are automatically processed. So callbacks that rely only on built-in quota configuration tools always return false. Quota callbacks with external quota configuration or custom reconfigurable quota configs that affect quota limits must return true if existing metric configs may need to be updated. This method is invoked on every request and hence is expected to be handled by callbacks as a simple flag that is updated when quotas change.

Parameters:

quotaType - Type of quota

updateClusterMetadata

boolean updateClusterMetadata(Cluster cluster)

Metadata update callback that is invoked whenever UpdateMetadata request is received from the controller. This is useful if quota computation takes partitions into account. Topics that are being deleted will not be included in `cluster`.

Parameters:

cluster - Cluster metadata including partitions and their leaders if known

Returns:

true if quotas have changed and metric configs may need to be updated

close

void close()

Closes this instance.