Statistics / Usage-Reporting

Symphony has a built-in statistic reporting mechanism.

Prerequisites

Dependency Versions

The minimum required versions for symphony and symphony-cli are as follows:

Package	Version
symphony	@stechquick/symphony@0.1.7
symphony-cli	@stechquick/symphony-cli@0.5.10

ReportingUrl

Reporting Endpoint to handle Symphony Stats reporting requests. (should be set to reportUrl)

Activation

Statistics reporting can be activated by adding a stats: key in config.yaml inside sym-engine folder in project root. Stats key should be added to each environment section in config.yaml

Usage Example

default: # Environment Section
  #...
  stats:
    #stats keys below
  #...
production: # Environment Section
  #...
  stats:
    #stats keys below
  #...

Remarks

• Stats can store usage statistics by function breakdown and total call count.
• Stats stores statistics on memory until the application shuts down or crash or until successful reporting call (reportURL).
• Stats does not lose usage statistics with unsuccessful reporting calls (reportURL). It continues cumulating data in memory. This results in the data in the memory spanning a larger time frame.
• Stats changes states with unsuccessful reporting calls (reportURL). Normal -> Observing -> Failure.
  • Normal: Stats is in normal state. Reporting is done with time span and accumulated call count.
  • Observing: In the first error observing state kicks in. During this state time span calls continue and accumulated call count changes to observingState.samplingFrequency.
  • Failure: When samplings in the observing state reaches observingState.failureStateThreshold failure count Failure state starts. During this state accumulated call count is disabled. And time span based reporting switches to observingState.failureStateIntervalTime timespan. So, you can raise this interval during Failure State to protect backend from overload; OR; you can lower this interval during Failure State to prevent losing usage statistics in memory as you are in Failure State, usage statistics now have a larger data for a larger timespan.
• Stats data in memory can be monitored on liveness endpoint.

Common Pitfalls

• make sure you activated stats key under target environment section.
• make sure you obtained endpoint url correctly and wrote it to endpointUrl in stats
• make sure enough time or accumulated request calls occurred in your service.

Stats Key Structure

default structure of stats is presented below.

  stats:
    reportUrl: "http://127.0.0.1:4321/"               # [required]
  #   reportIntervalTime: 300000  #(5min)             # [optional]
  #   reportIntervalCount: 200                        # [optional]
  #   applicationName: my-sym-app                     # [optional]
  #   observingState:                                 # [optional]
  #       samplingFrequency: 10                       # [optional]
  #       failureStateThreshold: 3                    # [optional]
  #       failureStateIntervalTime: 180000  #(3min)   # [optional]

Key	Description	Required	Type	Default Value
reportUrl	Endpoint url to push statistic report	true	string	--
reportIntervalTime	Time span in milliseconds for pushing cumulative statistics to reportUrl	false	number	300000 -> (5min)
reportIntervalCount	Accumulated number of calls if reached, to trigger reporting even reportIntervalTime is not reached	false	number	200
applicationName	Application name that can be used to define your application name	false	string	--
observingState	Stats has reporting states. Below this section are the values to manipulate the behaviour of these states.	false	object	--
observingState.samplingFrequency	ReportURL monitoring sampling frequency during Observing state.	false	number	10
observingState.failureStateThreshold	Number of report failures (reportURL) during Observing state to switch to Failure state.	false	number	3
observingState.failureStateIntervalTime	Time span in milliseconds for pushing cumulative statistics to reportUrl during the Failure state.	false	number	180000 -> (3min)

Stats Key Structure (ISBANK)

Key	Description	Required	Type	Default Value
isbankMetricName	if you need to change metric name	false	string	bff.trx.cnt

Example Request Body (ISBANK)

{
    "metrics": [
        {
            "metricName": "bff.trx.cnt",
            "value": 2
        }
    ]
}

Example Request Body (ISBANK) (With 'applicationName')

{
    "applicationName": "<YOUR APP NAME IN PACKAGE.JSON>",
    "metrics": [
        {
            "metricName": "bff.trx.cnt",
            "value": 2
        }
    ]
}