Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <chrono>
       4             : #include <cstdint>
       5             : #include <functional>
       6             : #include <memory>
       7             : 
       8             : #include "envoy/common/pure.h"
       9             : #include "envoy/common/time.h"
      10             : #include "envoy/data/cluster/v3/outlier_detection_event.pb.h"
      11             : 
      12             : #include "absl/types/optional.h"
      13             : 
      14             : namespace Envoy {
      15             : namespace Upstream {
      16             : 
      17             : class Host;
      18             : using HostSharedPtr = std::shared_ptr<Host>;
      19             : 
      20             : class HostDescription;
      21             : using HostDescriptionConstSharedPtr = std::shared_ptr<const HostDescription>;
      22             : 
      23             : namespace Outlier {
      24             : 
      25             : /**
      26             :  * Non-HTTP result of requests/operations.
      27             :  */
      28             : enum class Result {
      29             :   // Local origin errors detected by Envoy.
      30             :   LocalOriginTimeout,             // Timed out while connecting or executing a request.
      31             :   LocalOriginConnectFailed,       // Remote host rejected the connection.
      32             :   LocalOriginConnectSuccess,      // Successfully established a connection to upstream host.
      33             :                                   // Use this code when there is another protocol on top of
      34             :                                   // transport protocol. For example HTTP runs on top of tcp.
      35             :                                   // The same for redis. It first establishes TCP and then runs
      36             :                                   // a transaction.
      37             :   LocalOriginConnectSuccessFinal, // Successfully established a connection to upstream host
      38             :                                   // Use this code when there is no other protocol on top of the
      39             :                                   // protocol used by a filter. For example tcp_proxy filter
      40             :                                   // serves only tcp level. There is no other protocol on top of
      41             :                                   // tcp which the tcp_proxy filter is aware of.
      42             : 
      43             :   // The entries below only make sense when Envoy understands requests/responses for the
      44             :   // protocol being proxied. They do not make sense for TcpProxy, for example.
      45             :   // External origin errors.
      46             :   ExtOriginRequestFailed, // The server indicated it cannot process a request
      47             :   ExtOriginRequestSuccess // Request was completed successfully.
      48             : };
      49             : 
      50             : /**
      51             :  * Monitor for per host data. Proxy filters should send pertinent data when available.
      52             :  */
      53             : class DetectorHostMonitor {
      54             : public:
      55             :   // Types of Success Rate monitors.
      56             :   enum class SuccessRateMonitorType { ExternalOrigin, LocalOrigin };
      57             : 
      58        1736 :   virtual ~DetectorHostMonitor() = default;
      59             : 
      60             :   /**
      61             :    * @return the number of times this host has been ejected.
      62             :    */
      63             :   virtual uint32_t numEjections() PURE;
      64             : 
      65             :   /**
      66             :    * Add an HTTP response code for a host.
      67             :    */
      68             :   virtual void putHttpResponseCode(uint64_t code) PURE;
      69             : 
      70             :   /**
      71             :    * Add a non-HTTP result for a host.
      72             :    * Some non-HTTP codes like TIMEOUT may require special mapping to HTTP code
      73             :    * and such code may be passed as optional parameter.
      74             :    */
      75             :   virtual void putResult(Result result, absl::optional<uint64_t> code) PURE;
      76             : 
      77             :   /**
      78             :    * Wrapper around putResult with 2 params when mapping to HTTP code is not
      79             :    * required.
      80             :    */
      81         202 :   void putResult(Result result) { putResult(result, absl::nullopt); }
      82             : 
      83             :   /**
      84             :    * Add a response time for a host (in this case response time is generic and might be used for
      85             :    * different operations including HTTP, Mongo, Redis, etc.).
      86             :    */
      87             :   virtual void putResponseTime(std::chrono::milliseconds time) PURE;
      88             : 
      89             :   /**
      90             :    * Get the time of last ejection.
      91             :    * @return the last time this host was ejected, if the host has been ejected previously.
      92             :    */
      93             :   virtual const absl::optional<MonotonicTime>& lastEjectionTime() PURE;
      94             : 
      95             :   /**
      96             :    * Get the time of last unejection.
      97             :    * @return the last time this host was unejected, if the host has been unejected previously.
      98             :    */
      99             :   virtual const absl::optional<MonotonicTime>& lastUnejectionTime() PURE;
     100             : 
     101             :   /**
     102             :    * @return the success rate of the host in the last calculated interval, in the range 0-100.
     103             :    *         -1 means that the host did not have enough request volume to calculate success rate
     104             :    *         or the cluster did not have enough hosts to run through success rate outlier ejection.
     105             :    * @param type specifies for which Success Rate Monitor the success rate value should be returned.
     106             :    *         If the outlier detector is configured not to split external and local origin errors,
     107             :    *         ExternalOrigin type returns success rate for all types of errors: external and local
     108             :    * origin and LocalOrigin type returns -1. If the outlier detector is configured to split external
     109             :    * and local origin errors, ExternalOrigin type returns success rate for external origin errors
     110             :    * and LocalOrigin type returns success rate for local origin errors.
     111             :    */
     112             :   virtual double successRate(SuccessRateMonitorType type) const PURE;
     113             : };
     114             : 
     115             : using DetectorHostMonitorPtr = std::unique_ptr<DetectorHostMonitor>;
     116             : 
     117             : /**
     118             :  * Interface for an outlier detection engine. Uses per host data to determine which hosts in a
     119             :  * cluster are outliers and should be ejected.
     120             :  */
     121             : class Detector {
     122             : public:
     123           0 :   virtual ~Detector() = default;
     124             : 
     125             :   /**
     126             :    * Outlier detection change state callback.
     127             :    */
     128             :   using ChangeStateCb = std::function<void(const HostSharedPtr& host)>;
     129             : 
     130             :   /**
     131             :    * Add a changed state callback to the detector. The callback will be called whenever any host
     132             :    * changes state (either ejected or brought back in) due to outlier status.
     133             :    */
     134             :   virtual void addChangedStateCb(ChangeStateCb cb) PURE;
     135             : 
     136             :   /**
     137             :    * Returns the average success rate of the hosts in the Detector for the last aggregation
     138             :    * interval.
     139             :    * @return the average success rate, or -1 if there were not enough hosts with enough request
     140             :    *         volume to proceed with success rate based outlier ejection.
     141             :    * @param type - see DetectorHostMonitor::successRate.
     142             :    */
     143             :   virtual double successRateAverage(DetectorHostMonitor::SuccessRateMonitorType) const PURE;
     144             : 
     145             :   /**
     146             :    * Returns the success rate threshold used in the last interval. The threshold is used to eject
     147             :    * hosts based on their success rate.
     148             :    * @return the threshold, or -1 if there were not enough hosts with enough request volume to
     149             :    *         proceed with success rate based outlier ejection.
     150             :    */
     151             :   virtual double
     152             :       successRateEjectionThreshold(DetectorHostMonitor::SuccessRateMonitorType) const PURE;
     153             : };
     154             : 
     155             : using DetectorSharedPtr = std::shared_ptr<Detector>;
     156             : 
     157             : /**
     158             :  * Sink for outlier detection event logs.
     159             :  */
     160             : class EventLogger {
     161             : public:
     162           0 :   virtual ~EventLogger() = default;
     163             : 
     164             :   /**
     165             :    * Log an ejection event.
     166             :    * @param host supplies the host that generated the event.
     167             :    * @param detector supplies the detector that is doing the ejection.
     168             :    * @param type supplies the type of the event.
     169             :    * @param enforced is true if the ejection took place; false, if only logging took place.
     170             :    */
     171             :   virtual void logEject(const HostDescriptionConstSharedPtr& host, Detector& detector,
     172             :                         envoy::data::cluster::v3::OutlierEjectionType type, bool enforced) PURE;
     173             : 
     174             :   /**
     175             :    * Log an unejection event.
     176             :    * @param host supplies the host that generated the event.
     177             :    */
     178             :   virtual void logUneject(const HostDescriptionConstSharedPtr& host) PURE;
     179             : };
     180             : 
     181             : using EventLoggerSharedPtr = std::shared_ptr<EventLogger>;
     182             : 
     183             : } // namespace Outlier
     184             : } // namespace Upstream
     185             : } // namespace Envoy