Example xApp enhancement
[ric-plt/xapp-frame.git] / 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