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.

• setSmState

  public void setSmState(Map<String,Object> props)

• 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.