# XAPP-FRAME
## Introduction
-**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), database backend services and watching and populating config-map changes in K8S environment.
+**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.
## Architecture
* Encoding and decoding of commonly used RIC ASN.1 messages
* And more to come
+## Prerequisites
+Make sure that following tools are properly installed and configured
+* GO (golang) development and runtime tools
+* MDCLOG (ricplt/com/log)
+* RMR (ricplt/lib/rmr)
+* DBAAS (redis-server)
+
## Quick Start
#### Below is a simple example xapp. For more information, see the sample code in the xapp/examples folder:
```go
package main
-import "gitlabe1.ext.net.nokia.com/ric_dev/nokia-xapps/xapp/pkg/xapp"
+import "gerrit.o-ran-sc.org/r/ric-plt/xapp-frame/pkg/xapp"
-type MessageCounsumer struct {
+type ExampleXapp struct {
}
-func (m MessageCounsumer) Consume(mtype, len int, payload []byte) (err error) {
- xapp.Logger.Debug("Message received - type=%d len=%d", mtype, len)
+func (m *ExampleXapp) Consume(rp *xapp.RMRParams) (err error) {
+ xapp.Logger.Debug("Message received - type=%d len=%d", rp.Mtype, rp.PayloadLen)
- xapp.Sdl.Store("myKey", payload)
- xapp.Rmr.Send(10005, len, payload)
+ xapp.Sdl.Store("myKey", rp.Payload)
+ xapp.Rmr.Send(r)
return nil
}
func main() {
- xapp.Run(MessageCounsumer{})
+ xapp.Run(ExampleXapp{})
}
```
-#### Installing and running the example xapp
+#### Building and running the example xapp
+
+ git clone https://gerrit.o-ran-sc.org/r/ric-plt/xapp-frame
+ cd xapp-frame
+
+#### To generate an executable binary for our sample xApp application, run the following command:
+
+ GO111MODULE=on GO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o example-xapp examples/example-xapp.go
- git clone git@gitlabe1.ext.net.nokia.com:ric_dev/nokia-xapps/xapp.git
+#### To run the generated executable binary locally, run the following command:
-#### Build and run
- unset GOPATH
- cd xapp/examples
- go build example-xapp.go
- ./example-xapp
+ RMR_SEED_RT=examples/config/uta_rtg.rt ./example_xapp -f examples/config/config-file.json
Congratulations! You've just built your first **xapp** application.
-## API
-#### API List
- * TBD
+## API LIST
+#### Logging APIs
+ * SetLevel(level int)
+ ```
+ Sets logging level to given "level". Level can be 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG
+ ```
+ * SetMdc(key string, value string)
+ ```
+ Sets the application MDC to given string. The MDC will be visible in the logs
+ ```
+ * Error(pattern string, args ...interface{}).
+ ```
+ Writes an error log. Other possible function are: Warn, Info and Debug
+ ```
+
+#### Config APIs
+ * AddConfigChangeListener(f ConfigChangeCB)
+ ```
+ Injects an application callback function that is called when config change occurs
+ ```
+ * GetString(key string) string
+ ```
+ Returns the value associated with the key as a string. Other possible functions are: GetInt, GetBool and GetStringSlice
+ ```
+
+#### Metrics APIs
+ * RegisterCounterGroup(opts []CounterOpts, subsytem string) (c map[string]Counter)
+ ```
+ Creates a new 'Counter' vector based on the provided CounterOpts and partitioned by the given label names.
+ ```
+ * RegisterGaugeGroup(opts []CounterOpts, subsytem string) (c map[string]Gauge)
+ ```
+ Creates a new 'Gauge' vector based on the provided CounterOpts and partitioned by the given label names.
+ ```
+
+#### RMR-client APIs
+ * IsReady() bool
+ ```
+ Indicates whether RMR is ready or not
+ ```
+ * SetReadyCB(cb ReadyCB, params interface{})
+ ```
+ Injects a callback function that is called when RMR is ready
+ ```
+ * Allocate() *C.rmr_mbuf_t
+ ```
+ Allocates and return RMR message buffer
+ ```
+ * Free(mbuf *C.rmr_mbuf_t)
+ ```
+ De-allocates a RMR message buffer previously allocated with 'Allocate'
+ ```
+ * SendMsg(params *RMRParams)
+ ```
+ Sends RMR message based on the given RMR parameters
+ ```
+ * SendRts(params *RMRParams)
+ ```
+ Sends 'rts' RMR message based on the given RMR parameters
+ ```
+
+#### REST APIs
+ * InjectRoute(url string, handler http.HandlerFunc, method string) *mux.Route
+ ```
+ Registers a given URL and corresponding handler, which will be called when incoming request matches with the URL
+ ```
+ * InjectQueryRoute(url string, h http.HandlerFunc, m string, q ...string) *mux.Route
+ ```
+ Registers an inquiry URL and corresponding handler, which will be called when incoming request matches with the URL
+ ```
+ * InjectStatusCb(f StatusCb)
+ ```
+ Injects a callback function, which is called during K8s aliveness probe
+ ```
+
+#### SDL APIs
+ * Store(key string, value interface{}) (err error)
+ ```
+ Store writes the value of a key to SDL. MStore writes multiple key-value pairs atomically
+ ```
+ * Read(key string) (value map[string]interface{}, err error)
+ ```
+ Reads the value of a key from SDL. MRead reads multiple keys atomically
+ ```
#### API Usage and Examples
* Setting logging level and writing to log
Resource.InjectQueryRoute("/ric/v1/user", handler, "GET", "foo", "bar", "id", "mykey")
```
+* Metrics: registering couple of counters
+ ```
+ metrics := []xapp.CounterOpts{
+ {Name: "RICIndicationsRx", Help: "The total number of RIC inidcation events received"},
+ {Name: "RICExampleMessageRx", Help: "The total number of RIC example messages received"},
+ }
+ xapp.Metric.RegisterCounterGroup(metrics, "MyXApp")
+
+ // Use curl-command to get metrics
+ curl http://localhost:8080/ric/v1/metrics
+ ```
+
+## Running unit tests
+ Unit tests of xApp-framework can be run as following:
+ ```
+ make test
+ ```
+
## Documentation
## Community
Code Review / ric-plt / xapp-frame.git / blobdiff