Configuration docs

cluster/grpc_rpc_client.go

@@ -128,7 +128,7 @@ func (gs *GRPCClient) Send(uid string, d []byte) error {
 	return constants.ErrNotImplemented
 }
 
-// BroadcastSessionBind sends the binding information to other servers that may br interested in this info
+// BroadcastSessionBind sends the binding information to other servers that may be interested in this info
 func (gs *GRPCClient) BroadcastSessionBind(uid string) error {
 	if gs.bindingStorage == nil {
 		return constants.ErrNoBindingStorageModule

cluster/nats_rpc_server.go

@@ -88,11 +88,11 @@ func (ns *NatsRPCServer) configure() error {
 		return constants.ErrNoNatsConnectionString
 	}
 	ns.maxReconnectionRetries = ns.config.GetInt("pitaya.cluster.rpc.server.nats.maxreconnectionretries")
-	ns.messagesBufferSize = ns.config.GetInt("pitaya.buffer.cluster.rpc.server.messages")
+	ns.messagesBufferSize = ns.config.GetInt("pitaya.buffer.cluster.rpc.server.nats.messages")
 	if ns.messagesBufferSize == 0 {
 		return constants.ErrNatsMessagesBufferSizeZero
 	}
-	ns.pushBufferSize = ns.config.GetInt("pitaya.buffer.cluster.rpc.server.push")
+	ns.pushBufferSize = ns.config.GetInt("pitaya.buffer.cluster.rpc.server.nats.push")
 	if ns.pushBufferSize == 0 {
 		return constants.ErrNatsPushBufferSizeZero
 	}

cluster/nats_rpc_server_test.go

@@ -75,8 +75,8 @@ func TestNatsRPCServerConfigure(t *testing.T) {
 		t.Run(fmt.Sprintf("%s-%d-%d", table.natsConnect, table.messagesBufferSize, table.pushBufferSize), func(t *testing.T) {
 			cfg := viper.New()
 			cfg.Set("pitaya.cluster.rpc.server.nats.connect", table.natsConnect)
-			cfg.Set("pitaya.buffer.cluster.rpc.server.messages", table.messagesBufferSize)
-			cfg.Set("pitaya.buffer.cluster.rpc.server.push", table.pushBufferSize)
+			cfg.Set("pitaya.buffer.cluster.rpc.server.nats.messages", table.messagesBufferSize)
+			cfg.Set("pitaya.buffer.cluster.rpc.server.nats.push", table.pushBufferSize)
 			conf := getConfig(cfg)
 			_, err := NewNatsRPCServer(conf, getServer(), nil, nil)
 			assert.Equal(t, table.err, err)

config/config.go

@@ -52,13 +52,13 @@ func (c *Config) fillDefaultValues() {
 	defaultsMap := map[string]interface{}{
 		"pitaya.buffer.agent.messages": 100,
 		// the max buffer size that nats will accept, if this buffer overflows, messages will begin to be dropped
-		"pitaya.buffer.cluster.rpc.server.messages": 75,
-		"pitaya.buffer.cluster.rpc.server.push":     100,
-		"pitaya.buffer.handler.localprocess":        20,
-		"pitaya.buffer.handler.remoteprocess":       20,
+		"pitaya.buffer.cluster.rpc.server.nats.messages": 75,
+		"pitaya.buffer.cluster.rpc.server.nats.push":     100,
+		"pitaya.buffer.handler.localprocess":             20,
+		"pitaya.buffer.handler.remoteprocess":            20,
 		// the sum of this config among all the frontend servers should always be less than
-		// the sum of pitaya.buffer.cluster.rpc.server.messages, for covering the worst case scenario
-		// a single backend server should have the config pitaya.buffer.cluster.rpc.server.messages bigger
+		// the sum of pitaya.buffer.cluster.rpc.server.nats.messages, for covering the worst case scenario
+		// a single backend server should have the config pitaya.buffer.cluster.rpc.server.nats.messages bigger
 		// than the sum of the config pitaya.concurrency.handler.dispatch among all frontend servers
 		"pitaya.concurrency.handler.dispatch":                   25,
 		"pitaya.concurrency.remote.service":                     30,

constants/errors.go

@@ -38,9 +38,9 @@ var (
 	ErrFrontSessionCantPushToFront    = errors.New("frontend session can't push to front")
 	ErrIllegalUID                     = errors.New("illegal uid")
 	ErrMemberNotFound                 = errors.New("member not found in the group")
-	ErrNatsMessagesBufferSizeZero     = errors.New("pitaya.buffer.cluster.rpc.server.messages cant be zero")
+	ErrNatsMessagesBufferSizeZero     = errors.New("pitaya.buffer.cluster.rpc.server.nats.messages cant be zero")
 	ErrNatsNoRequestTimeout           = errors.New("pitaya.cluster.rpc.client.nats.requesttimeout cant be empty")
-	ErrNatsPushBufferSizeZero         = errors.New("pitaya.buffer.cluster.rpc.server.push cant be zero")
+	ErrNatsPushBufferSizeZero         = errors.New("pitaya.buffer.cluster.rpc.server.nats.push cant be zero")
 	ErrNilCondition                   = errors.New("pitaya/timer: nil condition")
 	ErrNoNatsConnectionString         = errors.New("you have to provide a nats url")
 	ErrNoConnectionToServer           = errors.New("rpc client has no connection to the chosen server")

docs/configuration.md

@@ -0,0 +1,77 @@
+Configuration
+=============
+
+Pitaya uses Viper to control its configuration. Below we describe the configuration variables split by topic. We judge the default values are good for most cases, but might need to be changed for some use cases.
+
+## Service Discovery
+
+These configuration values configure service discovery for the default etcd service discovery module.
+ They only need to be set if the application runs in cluster mode.
+
+| Configuration | Default value | Type | Description |
+|------------------------------------|---------------|-----------|------------------------------------------|
+| pitaya.cluster.sd.etcd.dialtimeout | 5s | time.Time | Dial timeout value passed to the service discovery etcd client |
+| pitaya.cluster.sd.etcd.endpoints | localhost:2379 | string | List of comma separated etcd endpoints |
+| pitaya.cluster.sd.etcd.heartbeat.ttl | 60s | time.Time | Hearbeat interval for the etcd lease |
+| pitaya.cluster.sd.etcd.heartbeat.log | false | bool | Whether etcd heartbeats should be logged in debug mode |
+| pitaya.cluster.sd.etcd.prefix | pitaya/ | string | Prefix used to avoid collisions with different pitaya applications, servers must have the same prefix to be able to see each other |
+| pitaya.cluster.sd.etcd.syncservers.interval | 120s | time.Time | Interval between server syncs performed by the service discovery module |
+
+## RPC Service
+
+The configurations only need to be set if the RPC Service is enabled with the given type.
+
+| Configuration | Default value | Type | Description |
+|------------------------------------|---------------|-----------|------------------------------------------|
+| pitaya.buffer.cluster.rpc.server.nats.messages | 75 | int | Size of the buffer that for the nats RPC server accepts before starting to drop incoming messages |
+| pitaya.buffer.cluster.rpc.server.nats.push | 100 | int | Size of the buffer that the nats RPC server creates for push messages |
+| pitaya.cluster.rpc.client.grpc.requesttimeout | 5s | time.Time | Request timeout for RPC calls with the gRPC client |
+| pitaya.cluster.rpc.client.grpc.dialtimeout | 5s | time.Time| Timeout for the gRPC client to establish the connection |
+| pitaya.cluster.rpc.client.nats.connect | nats://localhost:4222 | string | Nats address for the client |
+| pitaya.cluster.rpc.client.nats.requesttimeout | 5s | time.Time | Request timeout for RPC calls with the nats client |
+| pitaya.cluster.rpc.client.nats.maxreconnectionretries | 15 | int | Maximum number of retries to reconnect to nats for the client |
+| pitaya.cluster.rpc.server.nats.connect | nats://localhost:4222 | string | Nats address for the server |
+| pitaya.cluster.rpc.server.nats.maxreconnectionretries | 15 | int | Maximum number of retries to reconnect to nats for the server |
+| pitaya.cluster.rpc.server.grpc.port | 3434 | int | The port that the gRPC server listens to |
+| pitaya.concurrency.remote.service | 30 | int | Number of goroutines processing messages at the remote service for the nats RPC service |
+
+## Connection
+
+| Configuration | Default value | Type | Description |
+|------------------------------------|---------------|-----------|------------------------------------------|
+| pitaya.handler.messages.compression | true | bool | Whether messages between client and server should be compressed |
+| pitaya.heartbeat.interval | 30s | time.Time | Keepalive heartbeat interval for the client connection |
+
+## Metrics Reporting
+
+| Configuration | Default value | Type | Description |
+|------------------------------------|---------------|-----------|------------------------------------------|
+| pitaya.metrics.statsd.enabled | false | bool | Whether statsd reporting should be enabled |
+| pitaya.metrics.statsd.host | localhost:9125 | string | Address of the statsd server to send the metrics to |
+| pitaya.metrics.statsd.prefix | pitaya. | string | Prefix of the metrics reported to statsd |
+| pitaya.metrics.statsd.rate | 1 | int | Statsd metrics rate |
+| pitaya.metrics.prometheus.enabled | false | bool | Whether prometheus reporting should be enabled |
+| pitaya.metrics.prometheus.port | 9090 | int | Port to expose prometheus metrics |
+| pitaya.metrics.tags | map[string]string{} | map[string]string | Tags to be added to reported metrics |
+
+## Concurrency
+
+| Configuration | Default value | Type | Description |
+|------------------------------------|---------------|-----------|------------------------------------------|
+| pitaya.buffer.agent.messages | 100 | int | Buffer size for received client messages for each agent |
+| pitaya.buffer.handler.localprocess | 20 | int | Buffer size for messages received by the handler and processed locally |
+| pitaya.buffer.handler.remoteprocess | 20 | int | Buffer size for messages received by the handler and forwarded to remote servers |
+| pitaya.concurrency.handler.dispatch | 25 | int | Number of goroutines processing messages at the handler service |
+
+## Modules
+
+These configurations are only used if the modules are created. It is recommended to use Binding Storage module with gRPC RPC service to be able to use all RPC service features.
+
+| Configuration | Default value | Type | Description |
+|------------------------------------|---------------|-----------|------------------------------------------|
+| pitaya.session.unique | true | bool | Whether Pitaya should enforce unique sessions for the clients, enabling the unique sessions module |
+| pitaya.modules.bindingstorage.etcd.endpoints | localhost:2379 | string | Comma separated list of etcd endpoints to be used by the binding storage module, should be the same as the service discovery etcd |
+| pitaya.modules.bindingstorage.etcd.prefix | pitaya/ | string | Prefix used for etcd, should be the same as the service discovery |
+| pitaya.modules.bindingstorage.etcd.dialtimeout | 5s | time.Time | Timeout to establish the etcd connection |
+| pitaya.modules.bindingstorage.etcd.leasettl | 1h | time.Time | Duration of the etcd lease before automatic renewal |
+

docs/index.rst

@@ -13,6 +13,7 @@ Welcome to Pitaya's documentation!
    overview
    features
    communication
+   configuration
    API
    examples
 

service/handler.go

@@ -119,6 +119,7 @@ func (h *HandlerService) Dispatch(thread int) {
 
 	for {
 		// Calls to remote servers block calls to local server
+		// TODO: Measure pressure here (time between setting message and processing it)
 		select {
 		case lm := <-h.chLocalProcess:
 			h.localProcess(lm.ctx, lm.agent, lm.route, lm.msg)