From 2f1ff84c12397666dc20a935a6ac2cb99cba1632 Mon Sep 17 00:00:00 2001 From: Radu Ioan Fericean Date: Sat, 10 Mar 2012 12:21:43 +0200 Subject: [PATCH] more tutorial --- README.md | 8 +-- cmd/rater/rater.go | 12 ++-- docs/apicalls.rst | 10 ++-- docs/intro.rst | 10 ++-- docs/tutorial.rst | 125 ++++++++++++++++++++++++++++-------------- timespans/calldesc.go | 11 ++-- 6 files changed, 110 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index b7102bf77..1d9eeb711 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,15 @@ ## Features ## + Rates for prepaid and for postpaid + The budget expressed in money and/or minutes (seconds) -+ High accuracy rating: configurable to miliseconds -+ Handles volume dicount ++ High accuracy rating: configurable to milliseconds ++ Handles volume discount + Received calls bonus + Fully/Easy configurable + Very fast (5000+ req/sec) + Good documentation -+ Paid support ++ Commercial support available ## Documentation ## Browsable HTML http://readthedocs.org/docs/cgrates/ -PDF,epub,man http://readthedocs.org/projects/cgrates/downloads/ \ No newline at end of file +PDF, Epub, Manpage http://readthedocs.org/projects/cgrates/downloads/ \ No newline at end of file diff --git a/cmd/rater/rater.go b/cmd/rater/rater.go index f71a5599e..eea3a3877 100644 --- a/cmd/rater/rater.go +++ b/cmd/rater/rater.go @@ -27,9 +27,9 @@ import ( ) var ( - server = flag.String("server", "127.0.0.1:2000", "target host:port") - listen = flag.String("listen", "127.0.0.1:1234", "target host:port") - storage Storage + balancer = flag.String("balancer", "127.0.0.1:2000", "balancer address host:port") + listen = flag.String("listen", "127.0.0.1:1234", "listening address host:port") + storage Storage ) type Storage struct { @@ -116,7 +116,7 @@ func (s *Storage) ResetUserBudget(cd timespans.CallDescriptor, reply *float64) ( } /* -RPC method that trigers rater shutdown in case of server exit. +RPC method that triggers rater shutdown in case of balancer exit. */ func (s *Storage) Shutdown(args string, reply *string) (err error) { s.sg.Close() @@ -137,8 +137,8 @@ func main() { storage := NewStorage(getter) rpc.Register(storage) rpc.HandleHTTP() - go RegisterToServer(server, listen) - go StopSingnalHandler(server, listen, getter) + go RegisterToServer(balancer, listen) + go StopSingnalHandler(balancer, listen, getter) addr, err1 := net.ResolveTCPAddr("tcp", *listen) l, err2 := net.ListenTCP("tcp", addr) if err1 != nil || err2 != nil { diff --git a/docs/apicalls.rst b/docs/apicalls.rst index 440277998..5c2cf0f47 100644 --- a/docs/apicalls.rst +++ b/docs/apicalls.rst @@ -4,14 +4,14 @@ Api Calls JSON RPC -------- GetCost - Creates a CallCost structure with the cost nformation calculated for the received CallDescriptor. + Creates a CallCost structure with the cost information calculated for the received CallDescriptor. DebitBalance Interface method used to add/substract an amount of cents from user's money budget. The amount filed has to be filled in call descriptor. DebitSMS - Interface method used to add/substract an amount of units from user's sms budget. + Interface method used to add/substract an amount of units from user's SMS budget. The amount filed has to be filled in call descriptor. DebitSeconds @@ -19,7 +19,7 @@ DebitSeconds The amount filed has to be filled in call descriptor. GetMaxSessionTime - Returns the aproximate max allowed session for user budget. It will try the max amount received in the call descriptor + Returns the approximate max allowed session for user budget. It will try the max amount received in the call descriptor and will decrease it by 10% for nine times. So if the user has little credit it will still allow 10% of the initial amount. If the user has no credit then it will return 0. @@ -31,13 +31,13 @@ ResetVolumeDiscountSeconds Resets the accumulated volume discount seconds (to zero). AddRecievedCallSeconds - Adds the specified amount of seconds to the recived call seconds. When the threshold specified in the user's tariff plan is reached then the recived call budget is reseted and the bonus specified in the tariff plan is applyed. + Adds the specified amount of seconds to the received call seconds. When the threshold specified in the user's tariff plan is reached then the received call budget is reseted and the bonus specified in the tariff plan is applied. The amount filed has to be filled in call descriptor. ResetUserBudget Resets user budgets value to the amounts specified in the tariff plan. -Http +HTTP ---- getcost diff --git a/docs/intro.rst b/docs/intro.rst index 0e3aa24f2..c8bd6c13e 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,23 +1,23 @@ Introduction ============ -CGRates is a very fast and easy scalable rating enginge targeted especialli for telecom providers. +CGRates is a very fast and easy scalable rating engine targeted especially for telecom providers. It is written in go (http://golang.net) and accesible from any language via JSON RPC. The code is well documented (go doc compliant api docs) and heavily tested. Supported databases: kyoto_ cabinet, redis_, mongodb_. .. _kyoto: http://fallabs.com/kyotocabinet -.. _redis: http://redis.io +.. _redis: http://redis.io0 .. _mongodb: http://www.mongodb.org Features -------- + Rates for prepaid and for postpaid + The budget expressed in money and/or minutes (seconds) -+ High accuracy rating: configurable to miliseconds -+ Handles volume dicount ++ High accuracy rating: configurable to milliseconds ++ Handles volume discount + Received calls bonus + Fully/Easy configurable + Very fast (5000+ req/sec) + Good documentation -+ Paid support \ No newline at end of file ++ Commercial support available \ No newline at end of file diff --git a/docs/tutorial.rst b/docs/tutorial.rst index a413212c2..1fcae3a91 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -1,6 +1,14 @@ Tutorial ======== -The general usage of the cgrates involves creating a CallDescriptor stucture sending it to the balancer via JSON RPC and getting a response from the balancer inf form of a CallCost structure or a numeric value for requested information. +The general usage of the CGRates involves creating a CallDescriptor structure sending it to the balancer via JSON RPC and getting a response from the balancer inf form of a CallCost structure or a numeric value for requested information. + +The general steps to get up and running with CGRates are: + +#. Create JSON files containing rates, budgets, tariff plans and destinations, see :ref:`data-importing`. +#. Load the data in the databases using the loader tool. +#. Start the balancer, see :ref:`running`. +#. Start one ore more raters. +#. Make API calls to the balancer. CallDescriptor structure ------------------------ @@ -11,7 +19,7 @@ CallDescriptor structure TOR Type Of Record, used to differentiate between various type of records CstmId - Customer Identification used for multi tennant databases + Customer Identification used for multi tenant databases Subject Subject for this query DestinationPrefix @@ -19,7 +27,7 @@ DestinationPrefix TimeStart, TimeEnd The start end end of the call in question Amount - The amount requested in various api calss (e.g. DebitSMS amount) + The amount requested in various API calls (e.g. DebitSMS amount) CallCost structure ------------------ @@ -30,7 +38,7 @@ CallCost structure TOR Type Of Record, used to differentiate between various type of records (for query identification and confirmation) CstmId - Customer Identification used for multi tennant databases (for query identification and confirmation) + Customer Identification used for multi tenant databases (for query identification and confirmation) Subject Subject for this query (for query identification and confirmation) DestinationPrefix @@ -40,7 +48,7 @@ Cost ConnectFee The requested connection cost Timespans - The timespans in wicht the initial TimeStart-TimeEnd was split in for cost determination with all pricingg and cost information attached. + The timespans in witch the initial TimeStart-TimeEnd was split in for cost determination with all pricing and cost information attached. .. image:: images/general.png @@ -48,52 +56,89 @@ Instalation ----------- **Using packages** **Using source** + +.. _running: + Running ------- +There are only three main command to used with CGRates: + +balancer +:: + + rif@grace:~$ balancer --help + Usage of balancer: + -httpapiaddr="127.0.0.1:8000": HTTP API server address (localhost:2002) + -jsonrpcaddr="127.0.0.1:2001": JSON RPC server address (localhost:2001) + -rateraddr="127.0.0.1:2000": Rater server address (localhost:2000) + +rater +:: + rif@grace:~$ rater --help + Usage of rater: + -listen="127.0.0.1:1234": listening address host:port + -balancer="127.0.0.1:2000": balancer address host:port + +loader +:: + rif@grace:~$ loader --help + Usage of loader: + -apfile="ap.json": Activation Periods containing intervals file + -destfile="dest.json": Destinations file + -kyotofile="storage.kch": kyoto storage file (storage.kch) + -mdb="test": mongo database name (test) + -mongoserver="127.0.0.1:27017": mongo server address (127.0.0.1:27017) + -pass="": redis database password + -rdb=10: redis database number (10) + -redisserver="tcp:127.0.0.1:6379": redis server address (tcp:127.0.0.1:6379) + -storage="all": kyoto|redis|mongo + -tpfile="tp.json": Tariff plans file + -ubfile="ub.json": User budgets file + +.. _data-importing: + Data importing -------------- **Activation periods** - - -{"TOR": 0,"CstmId":"vdf","Subject":"rif","DestinationPrefix":"0257", "ActivationPeriods": [ - {"ActivationTime": "2012-01-01T00:00:00Z", "Intervals": [ - {"BillingUnit":1,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":0.1,"StartTime":"18:00:00","EndTime":"","WeekDays":[1,2,3,4,5]}, - {"BillingUnit":1,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":0.2,"StartTime":"","EndTime":"18:00:00","WeekDays":[1,2,3,4,5]}, - {"BillingUnit":1,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":0.1,"StartTime":"","EndTime":"","WeekDays":[6,0]} - ] - }, - {"ActivationTime": "2012-02-08T00:00:00Z", "Intervals": [ - {"BillingUnit":60,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":10,"StartTime":"","EndTime":"18:00:00","WeekDays":[1,2,3,4,5]}, - {"BillingUnit":60,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":1,"StartTime":"18:00:00","EndTime":"","WeekDays":[1,2,3,4,5]}, - {"BillingUnit":60,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":1,"StartTime":"","EndTime":"","WeekDays":[6,0]} - ] - } - ] -}, - +:: + {"TOR": 0,"CstmId":"vdf","Subject":"rif","DestinationPrefix":"0257", "ActivationPeriods": [ + {"ActivationTime": "2012-01-01T00:00:00Z", "Intervals": [ + {"BillingUnit":1,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":0.1,"StartTime":"18:00:00","EndTime":"","WeekDays":[1,2,3,4,5]}, + {"BillingUnit":1,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":0.2,"StartTime":"","EndTime":"18:00:00","WeekDays":[1,2,3,4,5]}, + {"BillingUnit":1,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":0.1,"StartTime":"","EndTime":"","WeekDays":[6,0]} + ] + }, + {"ActivationTime": "2012-02-08T00:00:00Z", "Intervals": [ + {"BillingUnit":60,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":10,"StartTime":"","EndTime":"18:00:00","WeekDays":[1,2,3,4,5]}, + {"BillingUnit":60,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":1,"StartTime":"18:00:00","EndTime":"","WeekDays":[1,2,3,4,5]}, + {"BillingUnit":60,"ConnectFee":0,"Month":0,"MonthDay":0,"Ponder":0,"Price":1,"StartTime":"","EndTime":"","WeekDays":[6,0]} + ] + } + ] + }, **Destinations** - -{"Id":"nationale", "Prefixes":["0256","0257","0723","0740"]}, -{"Id":"retea", "Prefixes":["0723","0724"]}, -{"Id":"mobil", "Prefixes":["0723","0740"]}, -{"Id":"radu", "Prefixes":["0723045326"]} +:: + {"Id":"nationale", "Prefixes":["0256","0257","0723","0740"]}, + {"Id":"retea", "Prefixes":["0723","0724"]}, + {"Id":"mobil", "Prefixes":["0723","0740"]}, + {"Id":"radu", "Prefixes":["0723045326"]} **Tariff plans** - -{"Id":"dimineata","SmsCredit":100,"ReceivedCallsSecondsLimit": 100, - "RecivedCallBonus" : {"Credit": 100}, - "MinuteBuckets": - [{"Seconds":100,"Priority":10,"Price":0.01,"DestinationId":"nationale"}, {"Seconds":1000,"Priority":20,"Price":0,"DestinationId":"retea"}], - "VolumeDiscountThresholds": - [{"Volume": 100, "Discount": 10},{"Volume": 500, "Discount": 15},{"Volume": 1000, "Discount": 20}] -} +:: + {"Id":"dimineata","SmsCredit":100,"ReceivedCallsSecondsLimit": 100, + "RecivedCallBonus" : {"Credit": 100}, + "MinuteBuckets": + [{"Seconds":100,"Priority":10,"Price":0.01,"DestinationId":"nationale"}, {"Seconds":1000,"Priority":20,"Price":0,"DestinationId":"retea"}], + "VolumeDiscountThresholds": + [{"Volume": 100, "Discount": 10},{"Volume": 500, "Discount": 15},{"Volume": 1000, "Discount": 20}] + } **User budgets** - -{"Id":"broker","Credit":0,"SmsCredit":0,"Traffic":0,"VolumeDiscountSeconds":0,"ReceivedCallSeconds":0,"ResetDayOfTheMonth":10,"TariffPlanId":"seara","MinuteBuckets": - [{"Seconds":10,"Priority":10,"Price":0.01,"DestinationId":"nationale"}, - {"Seconds":100,"Priority":20,"Price":0,"DestinationId":"retea"}]} \ No newline at end of file +:: + {"Id":"broker","Credit":0,"SmsCredit":0,"Traffic":0,"VolumeDiscountSeconds":0,"ReceivedCallSeconds":0,"ResetDayOfTheMonth":10,"TariffPlanId":"seara","MinuteBuckets": + [{"Seconds":10,"Priority":10,"Price":0.01,"DestinationId":"nationale"}, + {"Seconds":100,"Priority":20,"Price":0,"DestinationId":"retea"}]} \ No newline at end of file diff --git a/timespans/calldesc.go b/timespans/calldesc.go index dc7acd1a3..86f1d62b7 100644 --- a/timespans/calldesc.go +++ b/timespans/calldesc.go @@ -197,7 +197,7 @@ func (cd *CallDescriptor) splitTimeSpan(firstSpan *TimeSpan) (timespans []*TimeS } /* -Creates a CallCost structure with the cost nformation calculated for the received CallDescriptor. +Creates a CallCost structure with the cost information calculated for the received CallDescriptor. */ func (cd *CallDescriptor) GetCost() (*CallCost, error) { destPrefix, err := cd.SearchStorageForPrefix() @@ -233,7 +233,6 @@ type CallCost struct { Timespans []*TimeSpan } - /* Returns the cost of a second in the present time conditions. */ @@ -252,7 +251,7 @@ func (cd *CallDescriptor) getPresentSecondCost() (cost float64, err error) { } /* -Returns the aproximate max allowed session for user budget. It will try the max amount received in the call descriptor +Returns the approximate max allowed session for user budget. It will try the max amount received in the call descriptor and will decrease it by 10% for nine times. So if the user has little credit it will still allow 10% of the initial amount. If the user has no credit then it will return 0. */ @@ -351,9 +350,9 @@ func (cd *CallDescriptor) ResetVolumeDiscountSeconds() (err error) { } /* -Adds the specified amount of seconds to the recived call seconds. When the threshold specified -in the user's tariff plan is reached then the recived call budget is reseted and the bonus -specified in the tariff plan is applyed. +Adds the specified amount of seconds to the received call seconds. When the threshold specified +in the user's tariff plan is reached then the received call budget is reseted and the bonus +specified in the tariff plan is applied. The amount filed has to be filled in call descriptor. */ func (cd *CallDescriptor) AddRecievedCallSeconds() (err error) {