Skip to content

Client library

Jump to bottom
remiges-shuvam edited this page Feb 29, 2024 · 28 revisions

LogHarbour provides client libraries, in Java and Go, to allow business applications to perform all operations on a LogHarbour instance. The documentation below specifies the function signatures for the Go version. The semantics are identical in the two versions.

All functions require a token. A token is tied to a realm, and is generated by mechanisms outside the client library. See the page on access controls in LogHarbour.

Writing log entries

These functions are needed to write log entries into the various logs of LogHarbour.

WriteActivityLog()

func LogHarbour.WriteActivityLog(writetoken, app string, data any) (err error)

This function will be used by the business application code to write a log entry in the activity log.

WriteDataChgLog()

func LogHarbour.WriteDataChgLog(writetoken, app string, data any) (err error)

This function will be used by the business application code to write a log entry in the data-change log.

WriteDebugLog()

func LogHarbour.WriteDebugLog(writetoken, app string, data any) (err error)

This function will be used by the business application code to write a log entry in the debug log.

Log retrieval

GetLogs()

This function is the general purpose function to fetch log entries from the activity logs and data-change logs in the repository.

type GeneralLog_t struct {
    ts          time.Time            // timestamp of record insertion as maintained by LogHarbour
    docid       string               // unique internally generated record ID
    when        string               // timestamp of event as specified by the business application
    who         string               // some identity information to identify whose action generated this entry
    app         string               // the application ID of the app which generated this entry
    system      string               // the system or server or container where this entry originated
    module      string               // the sub-system of the application where this entry originated
    op          string               // the operation which generated this entry, e.g. "vouchercreate" or "reportget"
    type        string               // "A" for activity log, "C" for data change log, "D" for debug log
    class       string               // the class of object on which this operation was done, e.g. "voucher" or "misreport"
    instance    string               // a unique ID of one object instance of the class specified in "class"
    pri         LogPri_t             // priority of the entry -- an enum. A data-change log entry has no priority.
    status      string               // "success", "ok", "err", "failed", "aborted", or some such string
    error       string               // any string which specifies an error which may have occured due to the operation
    remoteIP    string               // the IP address of the system from where the operation was triggered
    message     string               // any string which gives a message to indicate what was done
    data        map[string]string    // a collection of attribute-value pairs of additional info
}
func LogHarbour.GetLogs(querytoken, app, type, who, class, instance string, fromts, tots time.Time, ndays int, remoteIP string, pri LogPri_t,
                                searchAfterTS time.Time, searchAfterDocID string)
                               (logs []GeneralLog_t, nrec int, err error)

where

  • querytoken: mandatory, is the query token of the realm
  • app: optional, to extract log entries for just the app specified
  • type: optional, A meaning activity logs, C meaning data-change logs, D meaning debug logs, and omitted meaning all three
  • who: optional, to extract log entries inserted only by actions performed by the specified user
  • class: optional, to extract logs related to objects of the specified class only
  • instance: optional, to extract logs only for a specific object instance. This parameter must be nil if class is not specified.
  • fromts, tots: optional, timestamps, to extract log entries whose when value falls in this time range.
  • ndays: optional, an integer specifying how many days back in time the retrieval must attempt, counting backwards in time from the current date
  • remoteIP: optional, an IP address in string form specifying the remote IP from where the operation was triggered which generated the log entry
  • pri: optional, specifies that only logs of priority equal to or higher than the value given here will be returned. If this parameter is present in the call, then data-change log entries are omitted from the result, because those log entries have no priority.
  • searchAfterTS: optional. If specified, it indicates that only logs with timestamps older than the specified parameter must be retrieved
  • searchAfterDocID: optional. If specified, it indicates that only logs whose document IDs are earlier than the one specified must be retrieved.

The three parameters, fromts, tots, and ndays have inter-dependency as follows:

  • If fromts and tots are specified, then tots must be after fromts.
  • If either or both of fromts and tots is specified, then ndays is ignored.
  • If just one of fronts or tots is specified, then the function will return all records which satisfy this filter, up to a maximum of LOGHARBOUR_GETLOGS_MAXREC entries, where the value of this parameter is a global configuration entry. If fromts is specified, then entries will be returned sorted forward in time (i.e. oldest to newest) based on their when field. If tots is specified then entries will be sorted from newest to oldest.

Under all circumstances, the response carries an array of up to LOGHARBOUR_GETLOGS_MAXREC entries. Each entry has fields as mentioned in the annotated data structure definition above.

The searchAfterTS and searchAfterDocID parameters must have the value nil the first time this function is called with a specific set of parameters. This call returns at most LOGHARBOUR_GETLOGS_MAXREC entries. The actual number of entries matching this request is returned in nrecs. If this number exceeds the value of LOGHARBOUR_GETLOGS_MAXREC, then the function is called again with exactly the same set of parameters but with specific values for these two parameters, which makes the function skip the earlier block(s) of entries and fetch only the next set. This way, the same function can retrieve a large data set over multiple calls, getting LOGHARBOUR_GETLOGS_MAXREC entries in every call.

GetSet()

This function gets a set of values for an attribute from the log entries specified.

func LogHarbour.GetSet(client, app, type, who, class, instance string, fromts, tots time.Time, ndays int, remoteIP string, pri LogPri_t,
                                searchAfterTS time.Time, searchAfterDocID string)

AppList()

func LogHarbour.AppList(querytoken) (apps []string, err error)

This function will be used by a business application to retrieve the list of apps under a realm. The response will carry an array of apps. An app is a one-word string, and is an attribute of every log entry. This data will be pulled out from the log entries in the repository, and making a unique set out of them. If there are no log entries in the repository at this time, the array will be of zero length.

GetUnusualIP()

This function will go through the logs of the last ndays days which match the search criteria, and pull out all the remote IP addresses which account for a low enough percentage of the total to be treated as unusual or suspicious.

func LogHarbour.GetUnusualIP(client, app, who, class, op string, ndays int, unusualpercent float32) (unusualIPs []string, err error)

where

  • client is the client token which authorises the call to the function
  • app: optional, the application ID whose matching log entries must be searched
  • who: optional, the user identity whose log entries must be searched
  • class: optional, the class of entities whose log entries must be searched
  • op: optional, the operation which triggered the generation of the log entries which must be searched. This parameter may carry a meaningful value only if class has been specified, and will be ignored if class is nil.
  • ndays: optional, an integer specifying how many days back in time the retrieval must attempt, counting backwards in time from the current date. If this is omitted, then the most recent LOGHARBOUR_GETLOG_MAXREC log entries will be processed
  • unusualpercent: mandatory, specifies the percent upper limit of an IP address' occurrence in the list of remote IPs for it to be considered "unusual". Typical values will range between 0.5 and 5.0. A value above 50 will be rejected and the function will return with an error.

The processing will require that the client have activitylogs, datachglogs or report capabilities

function GetUnusualIP(filtering parameters, ndays, unusualpercent):
  # Aggregate logs by IP and count occurrences
  aggregatedIPs = select remoteIPs of log entries matching the request parameters
  
  # Calculate total number of logs to find what 1% represents
  var PercentThreshold float = count_of(aggregatedIPs) * unusualpercent / 100.0
  if PercentThreshold < 1, then PercentThreshold = 1, endif

  # Initialize an empty list to hold unusual IPs
  unusualIPs = []

  # For each IP in the aggregated IP list
  for each IP in aggregatedIPs do
      # If the count of logs for this IP is less than the threshold
      if IP.count <= onePercentThreshold, then
          if IP.address != "LOCAL" then
              unusualIPs.append(IP.address)
          endif
      endif
  done

  return unusualIPs

The response will return a list of "unusual" IP addresses from all the matching log entries.

Clone this wiki locally