org.apache.uima.ducc.cli

Class AServicePing



  • public abstract class AServicePing
    extends Object
    Abstraction for service pinger.
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      protected boolean autostart_enabled
      This indicates whether the service's autostart flag is enabled or disabled.
      protected org.apache.uima.ducc.common.utils.DuccLogger duccLogger
      When the pinger is run as a thread inside the SM, this logger is used to join the ping log with the SM log.
      protected int failure_cursor 
      protected int failure_max
      This is the total number of instance failures allowed within the failure window.
      protected int[] failure_window 
      protected int failure_window_period
      This is the time, in minutes, over which the failure window is implemented.
      protected int failure_window_size 
      protected Map<String,Object> initializationState
      This is a map containing the initialization state for the service, passed in only once, during pinger initialization.
      protected long last_use
      This is the time/date the service was last used.
      protected boolean log_enabled
      This specifies whether the service log is requested to be enabled.
      protected int monitor_rate
      This is the time between pings, in minutes.
      protected long service_id
      This is the unique DUCC_assigned ID of the service.
      protected Map<String,Object> smState
      This is a map containing current service state, passed in from the SM on every ping.
      protected int total_failures
      This is the total number of instance failures since the SM or pinger was last started.
    • Constructor Summary

      Constructors 
      Constructor and Description
      AServicePing() 
    • Field Detail

      • failure_window

        protected int[] failure_window
      • failure_cursor

        protected int failure_cursor
      • total_failures

        protected int total_failures
        This is the total number of instance failures since the SM or pinger was last started.
      • failure_max

        protected int failure_max
        This is the total number of instance failures allowed within the failure window.
      • failure_window_period

        protected int failure_window_period
        This is the time, in minutes, over which the failure window is implemented.
      • failure_window_size

        protected int failure_window_size
      • monitor_rate

        protected int monitor_rate
        This is the time between pings, in minutes.
      • autostart_enabled

        protected boolean autostart_enabled
        This indicates whether the service's autostart flag is enabled or disabled.
      • last_use

        protected long last_use
        This is the time/date the service was last used. If 0, the time is either unknown or the service has never been used by clients. It is persisted by the SM over restarts.
      • log_enabled

        protected boolean log_enabled
        This specifies whether the service log is requested to be enabled.
      • service_id

        protected long service_id
        This is the unique DUCC_assigned ID of the service.
      • smState

        protected Map<String,Object> smState
        This is a map containing current service state, passed in from the SM on every ping. See getSmState() for details of the map.
      • initializationState

        protected Map<String,Object> initializationState
        This is a map containing the initialization state for the service, passed in only once, during pinger initialization. Its fields are set into primitive fields in this class. The map itself isn't directly used by implementors.
      • duccLogger

        protected org.apache.uima.ducc.common.utils.DuccLogger duccLogger
        When the pinger is run as a thread inside the SM, this logger is used to join the ping log with the SM log. When run as a process, # the doLog(String, Object...) method writes to stdout which is directed to the declared service log directory by the infrastructore.
    • Constructor Detail

      • AServicePing

        public AServicePing()
    • Method Detail

      • init

        public abstract void init(String arguments,
                                  String endpoint)
                           throws Exception
        Called by the ping driver, to pass in useful things the pinger may want.
        Parameters:
        arguments - This is passed in from the service specification's service_ping_arguments string.
        endpoint - This is the name of the service endpoint, as passed in at service registration.
        Throws:
        Exception - If initialization fails
      • init

        public void init(String arguments,
                         String endpoint,
                         Map<String,Object> initState)
                  throws Exception
        Called by the ping driver to initialize static information about the service and pinger. This method calls the public init() method and is not intended for public consumption. This method initializes the following state prior to invoking init(String, String): VAR NAME TYPE MEANING ------------------ -------- --------------------------------------------- monitor_rate int Ping period, in minutes. service_id long DUCC ID of the service being monitored log_enabled boolean Is the service registered with log enabled? failure_max int Registered max consecutive failures failure_window_size int The window, in terms of minutes, in which 'failure-max' errors indicates excessive instance failures. autostart_enabled boolean Is the service registered with autostart on? last_use long When was the last known use of this service before it was (re)started?
        Parameters:
        arguments - This is passed in from the service specification's service_ping_arguments string.
        endpoint - This is the name of the service endpoint, as passed in at service registration.
        initState - Properties file with static data about the service and pinger.
        Throws:
        Exception - If initialization fails
      • stop

        public abstract void stop()
        Stop is called by the ping wrapper when it is being killed. Implementors may optionally override this method with conenction shutdown code.
      • getStatistics

        public abstract IServiceStatistics getStatistics()
        Returns the object with application-derived health and statistics.
        Returns:
        an object that implements IServiceStatistics containing the basic service health information for use by SM and display in the Web Server.
      • getSmState

        public Map<String,Object> getSmState()
        Getter of the service state; Implementors may just access it directly if they want. Access the state passed to the ping/monitor from SM: KEY Object Type MEANING ---------------- ------------- ------------------------------------------------------------------ all-instances Long[] DUCC Ids of all running instances (may not all be in Running state) active-instances Long[] DUCC Ids of all instances that are Running autostart-enabled Boolean Current state of service autostart references Long[] DUCC Ids of all jobs referencing this service run-failures Integer Total run failures since the service was started
        Returns:
        A String to Object Map containing dynamic information from the SM. Callers must cast the value to the correct type as shown below.
      • getAdditions

        public int getAdditions()

        Called by the service manager to query the number of additional needed service instances.

        Implementing ping/monitors override this method to request additional instances.

        Returns:
        the number of new instances of the service to start.
      • getDeletions

        public Long[] getDeletions()

        Called by the service manager to retrieve the specific service instances to stop.

        Implementing ping/monitors return the specific IDs of service processes to be terminated by DUCC. The IDs are a subset of the IDS found in the 'all-instances' map from getSmState();

        Returns:
        a Long[] array of service instance IDs to terminate.
      • isAutostart

        public boolean isAutostart()

        The SM queries the ping/monitors autostart on return from each ping. The default is to return the same value that came in on the ping.

        Implementing ping/monitors may override this behaviour to dynanically enable or disable autostart.

        It is useful to disable autostart if a pinger detects that a service has been idle for a long time and it wants to shrink the number of live instances below the autostart value. If autostart is not disabled it the number of instances will not be allowed to shrink to 0.

        Returns:
        true if the service should be marked for autostart, and false otherwise.
      • getLastUse

        public long getLastUse()

        Pingers may track when a service was last used. If set to non-zero this is the time and date of last use, converted to milliseconds, as returned by System.getTimeMillis(). Its value is always set into the meta file for the pinger on each ping.

        Implementing ping/monitors may return a datestamp to indicate when the service was last used by a job.

        Returns:
        A Long, representing the time of last known use of the service, as returned by System.getTimeMillis().
      • setLogger

        public void setLogger(org.apache.uima.ducc.common.utils.DuccLogger logger)
      • doLog

        public void doLog(String methodName,
                          Object... msg)
        This is a convenience method for logging which enforces the use of the calling method name and permits use of commas to separate fields in the message. The fields are converted via toString() and joined on a single space ' '. The composed string is then written to the logger if it exists, and System.out otherwise.
        Parameters:
        methodName - This should be the named of the method calling doLog.
        msg - This is a variable length parameter list which gets joined on ' ' and emitted to the logger.
      • isExcessiveFailures

        public boolean isExcessiveFailures()
        This determines if there have been excessive service instance failures by tracking the number of failures, not consecutive, but rather within a window of time. It may be overridden by extending monitors. This default implementation uses a time window to determine if exessive failures have occurred in a short period of time. It operates off the two failure parameters from the service registration: instance_failure_window [time-in-minutes] instance_failure_limit [number of failures] If more than 'instance_failure_limit' failures occure within the preceding 'time-in-minutes' this method returns 'true' and the SM disables automatic restart of instances. Restart may be resumed by manually issuing a CLI start to the service one the problem is resolved. Implementing ping/monitors may override this with custom logic to determine if a service has had excessive failures.
        Returns:
        true if too many failures have been observed, false otherwise. If 'true' is returned, the SM no longer restarts failed instances.

Copyright © 2012–2019 The Apache Software Foundation. All rights reserved.