Package 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 Details

    • 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

    • cleanUpTenantDynamicQuotas

      default void cleanUpTenantDynamicQuotas(List<Map<String,String>> tenants, Set<String> targetTenants)
      Clean up dynamicBrokerQuotas on specific tenants.
      Parameters:
      tenants - The list of map of tenants
      targetTenants - The set of target tenants

    • 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
      invalid reference 
      #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(ClientQuotaClusterDescriber 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

    • updateTenantFlexFanoutEnabled

      default void updateTenantFlexFanoutEnabled(String logicalClusterId, Boolean isFlexFanoutEnabled)
      Update whether flex fanout is enabled on this tenant.
      Parameters:
      logicalClusterId - logical cluster(tenant) id
      isFlexFanoutEnabled - is flex fanout enabled

    • getTenantWithFlexFanoutEnabled

      default Set<String> getTenantWithFlexFanoutEnabled()
      Return tenants with flex fanout enabled.
      Returns:
      set of tenants

    • close

      void close()
      Closes this instance.