README.md

   1 # XAPP-FRAME
   2
   3 ## Introduction
   4 **xapp-frame** is a simple framework for rapid development of RIC xapps, and supports various services essential for RIC xapps such as RESTful APIs, RMR (RIC Message Routing), logging, performance metrics and database backend services. It also provides configuration interface for reading, watching and populating config-map changes in K8S environment.
   5
   6 ## Architecture
   7
   8 ![Architecture](assets/xappframe-arch.png)
   9
  10 ## Features and Components
  11
  12 * RESTful support
  13 * Health check/probes (readiness and liveliness)
  14 * Reading and watching config-map
  15 * RMR messaging
  16 * SDL
  17 * Loggind and tracing
  18 * Encoding and decoding of commonly used RIC ASN.1 messages
  19 * And more to come
  20
  21 ## Prerequisites
  22 Make sure that following tools are properly installed and configured
  23 * GO (golang) development and runtime tools
  24 * MDCLOG (ricplt/com/log)
  25 * RMR (ricplt/lib/rmr)
  26 * DBAAS (redis-server)
  27
  28 ## Quick Start
  29
  30 #### Below is a simple example xapp. For more information, see the sample code in the xapp/examples folder:
  31 ```go
  32 package main
  33
  34 import "gerrit.o-ran-sc.org/r/ric-plt/xapp-frame/pkg/xapp"
  35
  36 type ExampleXapp struct {
  37 }
  38
  39 func (m *ExampleXapp) Consume(rp *xapp.RMRParams) (err error) {
  40         xapp.Logger.Debug("Message received - type=%d len=%d", rp.Mtype, rp.PayloadLen)
  41
  42         xapp.Sdl.Store("myKey", rp.Payload)
  43         xapp.Rmr.Send(r)
  44         return nil
  45 }
  46
  47 func main() {
  48        xapp.Run(ExampleXapp{})
  49 }
  50 ```
  51 #### Building and running the example xapp
  52
  53     git clone https://gerrit.o-ran-sc.org/r/ric-plt/xapp-frame
  54     cd xapp-frame
  55
  56 #### To generate an executable binary for our sample xApp application, run the following command:
  57
  58     GO111MODULE=on GO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o example-xapp examples/example-xapp.go
  59
  60 #### To run the generated executable binary locally, run the following command:
  61
  62     RMR_SEED_RT=examples/config/uta_rtg.rt ./example_xapp -f examples/config/config-file.json
  63
  64 Congratulations! You've just built your first **xapp** application.
  65
  66 ## API LIST
  67 #### Logging APIs
  68  * SetLevel(level int)
  69   ```
  70   Sets logging level to given "level". Level can be 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG
  71   ```
  72  * SetMdc(key string, value string)
  73   ```
  74   Sets the application MDC to given string. The MDC will be visible in the logs
  75   ```
  76  * Error(pattern string, args ...interface{}).
  77   ```
  78   Writes an error log. Other possible function are: Warn, Info and Debug
  79   ```
  80
  81 #### Config APIs
  82  * AddConfigChangeListener(f ConfigChangeCB)
  83   ```
  84   Injects an application callback function that is called when config change occurs
  85   ```
  86  * GetString(key string) string
  87   ```
  88   Returns the value associated with the key as a string. Other possible functions are: GetInt, GetBool and GetStringSlice
  89   ```
  90
  91 #### Metrics APIs
  92  * RegisterCounterGroup(opts []CounterOpts, subsytem string) (c map[string]Counter)
  93   ```
  94   Creates a new 'Counter' vector based on the provided CounterOpts and partitioned by the given label names.
  95   ```
  96  * RegisterGaugeGroup(opts []CounterOpts, subsytem string) (c map[string]Gauge)
  97   ```
  98   Creates a new 'Gauge' vector based on the provided CounterOpts and partitioned by the given label names.
  99   ```
 100
 101 #### RMR-client APIs
 102  * IsReady() bool
 103   ```
 104   Indicates whether RMR is ready or not
 105   ```
 106  * SetReadyCB(cb ReadyCB, params interface{})
 107   ```
 108   Injects a callback function that is called when RMR is ready
 109   ```
 110  * Allocate() *C.rmr_mbuf_t
 111   ```
 112   Allocates and return RMR message buffer
 113   ```
 114  * Free(mbuf *C.rmr_mbuf_t)
 115   ```
 116   De-allocates a RMR message buffer previously allocated with 'Allocate'
 117   ```
 118  * SendMsg(params *RMRParams)
 119   ```
 120   Sends RMR message based on the given RMR parameters
 121   ```
 122  * SendRts(params *RMRParams)
 123   ```
 124   Sends 'rts' RMR message based on the given RMR parameters
 125   ```
 126
 127 #### REST APIs
 128  * InjectRoute(url string, handler http.HandlerFunc, method string) *mux.Route
 129   ```
 130   Registers a given URL and corresponding handler, which will be called when incoming request matches with the URL
 131   ```
 132  * InjectQueryRoute(url string, h http.HandlerFunc, m string, q ...string) *mux.Route
 133   ```
 134   Registers an inquiry URL and corresponding handler, which will be called when incoming request matches with the URL
 135   ```
 136  * InjectStatusCb(f StatusCb)
 137   ```
 138   Injects a callback function, which is called during K8s aliveness probe
 139   ```
 140
 141 #### SDL APIs
 142  * Store(key string, value interface{}) (err error)
 143   ```
 144   Store writes the value of a key to SDL. MStore writes multiple key-value pairs atomically
 145   ```
 146  * Read(key string) (value map[string]interface{}, err error)
 147   ```
 148   Reads the value of a key from SDL. MRead reads multiple keys atomically
 149   ```
 150
 151 #### API Usage and Examples
 152 * Setting logging level and writing to log
 153     ```
 154     xapp.Logger.SetLevel(4)
 155     xapp.Logger.Info("Status inquiry ...")
 156     ```
 157 * Storing key-value data to SDL
 158     ```
 159     xapp.Sdl.Store("myKey", payload)
 160     ```
 161 * Sending RMR messages
 162     ```
 163     mid := Rmr.GetRicMessageId("RIC_SUB_RESP")
 164     xapp.Rmr.Send(mid, 1234, len, payload)
 165     ```
 166 * Injecting REST API resources (URL)
 167     ```
 168     xapp.Resource.InjectRoute("/ric/v1/health/stat", statisticsHandler, "GET")
 169     Resource.InjectQueryRoute("/ric/v1/user", handler, "GET", "foo", "bar", "id", "mykey")
 170     ```
 171
 172 * Metrics: registering couple of counters
 173     ```
 174     metrics := []xapp.CounterOpts{
 175                 {Name: "RICIndicationsRx", Help: "The total number of RIC inidcation events received"},
 176                 {Name: "RICExampleMessageRx", Help: "The total number of RIC example messages received"},
 177         }
 178     xapp.Metric.RegisterCounterGroup(metrics, "MyXApp")
 179
 180     // Use curl-command to get metrics
 181     curl http://localhost:8080/ric/v1/metrics
 182     ```
 183
 184 ## Running unit tests
 185   Unit tests of xApp-framework can be run as following:
 186   ```
 187   make test
 188   ```
 189
 190 ## Documentation
 191
 192 ## Community
 193
 194 ## License
 195 This project is licensed under the Apache License 2.0 - see the [LICENSE.md](LICENSE.md) file for details
 196