You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brpc.apache.org by GitBox <gi...@apache.org> on 2021/12/30 11:39:44 UTC
[GitHub] [incubator-brpc] zyearn commented on a change in pull request #1654: Added autotranslated and cleanup english documentation
zyearn commented on a change in pull request #1654:
URL: https://github.com/apache/incubator-brpc/pull/1654#discussion_r776685142
##########
File path: docs/en/auto_concurrency_limiter.md
##########
@@ -0,0 +1,153 @@
+# Adaptive current limit
+
+The processing capacity of the service has an objective upper limit. When the request speed exceeds the processing speed of the service, the service becomes overloaded.
+
+If the service continues to be overloaded, it will cause more and more request backlogs, and eventually all requests have to wait a long time to be processed, thus making the entire service paralyzed.
+
+In contrast, if you directly reject some of the requests, it will enable the service to process more requests in a "timely" manner. The corresponding method is [Set Maximum Concurrency](https://github.com/brpc/brpc/blob/master/docs/cn/server.md#%E9%99%90%E5%88%B6%E6%9C %80%E5%A4%A7%E5%B9%B6%E5%8F%91).
+
+Adaptive current limiting can dynamically adjust the maximum concurrency of the service, allowing the service to process as many requests as possible under the premise of ensuring that the service is not overloaded.
+
+## scenes to be used
+Under normal circumstances, if the service is not overloaded, you only need to perform a stress test before going online and calculate best_max_concurrency through little's law. However, in a situation where the number of services is large, the topology is complex, and the processing capacity will gradually change, using a fixed maximum concurrency will bring a huge test workload, which is very inconvenient. Adaptive current limiting is to solve this problem.
+
+It is recommended to do the following before using adaptive current limiting:
+1. The client has enabled the retry function.
+
+2. There are multiple nodes on the server side.
+
+In this way, when a node returns to overload, the client can initiate a retry to other nodes, so as not to lose traffic as much as possible.
+
+## How to open
+Currently, only the method level supports adaptive current limiting. If you want to enable adaptive current limiting for a method, you only need to set its maximum concurrency to "auto".
+
+```c++
+// Set auto concurrency limiter for all methods
+brpc::ServerOptions options;
+options.method_max_concurrency = "auto";
+
+// Set auto concurrency limiter for specific method
+server.MaxConcurrencyOf("example.EchoService.Echo") = "auto";
+```
+
+## Principle
+
+### noun
Review comment:
Definitions / Terms ?
##########
File path: docs/en/baidu_std.md
##########
@@ -0,0 +1,159 @@
+# introduce
+
+baidu_std is a binary RPC communication protocol based on TCP protocol. It uses Protobuf as the basic data exchange format, and based on the built-in RPC Service form of Protobuf, it specifies the data exchange protocol between the communicating parties to achieve complete RPC calls.
+
+baidu_std does not consider the cross-TCP connection.
+
+# Basic agreement
+
+## Serve
+
+All RPC services are published on a certain IP address through a certain port.
+
+A port can publish multiple services at the same time. Services are identified by name. The service name must be UpperCamelCase, consisting of uppercase and lowercase letters and numbers, and no more than 64 characters in length.
+
+A service can contain one or more methods. Each method is identified by a name, composed of uppercase and lowercase letters, numbers, and underscores, and the length does not exceed 64 characters. Considering that different language styles are quite different, the method naming format is not mandatory here.
+
+The four-tuple uniquely identifies an RPC method.
+
+The parameters needed to call the method should be placed in a Protobuf message. If the method returns a result, it should also be placed in a Protobuf message. The specific definition shall be agreed upon by the communicating parties. In particular, an empty Protobuf message can be used to indicate that the request/response is empty.
+
+## Bag
+
+The package is the basic data exchange unit of baidu_std. Each package consists of a header and a package body. The package body is divided into three parts: metadata, data, and attachments. The specific parameters and return results are placed in the data section.
+
+There are two types of packages: request packages and response packages. Their header format is the same, but the definition of the metadata part is different.
+
+## Baotou
Review comment:
Package header
##########
File path: docs/en/baidu_std.md
##########
@@ -0,0 +1,159 @@
+# introduce
+
+baidu_std is a binary RPC communication protocol based on TCP protocol. It uses Protobuf as the basic data exchange format, and based on the built-in RPC Service form of Protobuf, it specifies the data exchange protocol between the communicating parties to achieve complete RPC calls.
+
+baidu_std does not consider the cross-TCP connection.
+
+# Basic agreement
+
+## Serve
+
+All RPC services are published on a certain IP address through a certain port.
+
+A port can publish multiple services at the same time. Services are identified by name. The service name must be UpperCamelCase, consisting of uppercase and lowercase letters and numbers, and no more than 64 characters in length.
+
+A service can contain one or more methods. Each method is identified by a name, composed of uppercase and lowercase letters, numbers, and underscores, and the length does not exceed 64 characters. Considering that different language styles are quite different, the method naming format is not mandatory here.
+
+The four-tuple uniquely identifies an RPC method.
+
+The parameters needed to call the method should be placed in a Protobuf message. If the method returns a result, it should also be placed in a Protobuf message. The specific definition shall be agreed upon by the communicating parties. In particular, an empty Protobuf message can be used to indicate that the request/response is empty.
+
+## Bag
Review comment:
package
##########
File path: docs/en/auto_concurrency_limiter.md
##########
@@ -0,0 +1,153 @@
+# Adaptive current limit
+
+The processing capacity of the service has an objective upper limit. When the request speed exceeds the processing speed of the service, the service becomes overloaded.
+
+If the service continues to be overloaded, it will cause more and more request backlogs, and eventually all requests have to wait a long time to be processed, thus making the entire service paralyzed.
+
+In contrast, if you directly reject some of the requests, it will enable the service to process more requests in a "timely" manner. The corresponding method is [Set Maximum Concurrency](https://github.com/brpc/brpc/blob/master/docs/cn/server.md#%E9%99%90%E5%88%B6%E6%9C %80%E5%A4%A7%E5%B9%B6%E5%8F%91).
+
+Adaptive current limiting can dynamically adjust the maximum concurrency of the service, allowing the service to process as many requests as possible under the premise of ensuring that the service is not overloaded.
+
+## scenes to be used
+Under normal circumstances, if the service is not overloaded, you only need to perform a stress test before going online and calculate best_max_concurrency through little's law. However, in a situation where the number of services is large, the topology is complex, and the processing capacity will gradually change, using a fixed maximum concurrency will bring a huge test workload, which is very inconvenient. Adaptive current limiting is to solve this problem.
+
+It is recommended to do the following before using adaptive current limiting:
+1. The client has enabled the retry function.
+
+2. There are multiple nodes on the server side.
+
+In this way, when a node returns to overload, the client can initiate a retry to other nodes, so as not to lose traffic as much as possible.
+
+## How to open
Review comment:
How to turn on?
##########
File path: docs/en/auto_concurrency_limiter.md
##########
@@ -0,0 +1,153 @@
+# Adaptive current limit
Review comment:
There're some specific translation that auto-translation cannot catch.
we should replace 'current limit' with Adaptive Load Shedding
##########
File path: docs/en/baidu_std.md
##########
@@ -0,0 +1,159 @@
+# introduce
Review comment:
Introduction
##########
File path: docs/en/case_elf.md
##########
@@ -0,0 +1,87 @@
+# background
+
+ELF (Essential/Extreme/Excellent Learning Framework) framework provides learning/mining algorithm development support for big data applications inside and outside the company. The platform mainly includes framework support for iterative data processing, communication support during parallel computing, and a distributed, fast, and highly available parameter server for storing large-scale parameters. Used in fcr-model, public cloud bml, big data laboratory, voice technology department, etc. Previously it was based on the rpc packaged by [zeromq](http://zeromq.org/), this time I use brpc instead.
+
+# in conclusion
Review comment:
Maybe we should replace all 'in conclusion' in heading with 'Summary'?
##########
File path: docs/en/case_baidu_dsp.md
##########
@@ -0,0 +1,23 @@
+# background
+
+baidu-dsp is a demand-side platform of the alliance based on Ad Exchange and RTB models, serving large customers and agency products. We have transformed a number of modules, all of which have achieved remarkable results. This article only introduces the changes to super-nova-as. super-nova-as is the AS of baidu-dsp. It was previously written using ub-aserver. In order to minimize changes, we did not modify the entire as, but only connected the super-nova-as downstream (ctr-server, cvr-server, The client of super-nova-bs) is upgraded from ubrpc to brpc.
+
+# in conclusion
Review comment:
Summary?
##########
File path: docs/en/bthread_id.md
##########
@@ -0,0 +1,36 @@
+bthread_id is a special synchronization structure, which can mutually exclusive different links in the RPC process, and can also find the RPC context (ie Controller) in O(1) time. Note that here we are talking about bthread_id_t, not bthread_t (bthread's tid), this name is indeed not very good and easy to confuse.
+
+Specifically, the problems solved by bthread_id are:
+
+-The response came back during the process of sending the RPC, and the response code competed with the sending code.
+-The timer is triggered soon after setting the timer, and the timeout processing code and the sending code compete.
+-Retry the competition generated by multiple responses coming back at the same time.
+-Find the corresponding RPC context in O(1) time through correlation_id, without building a global hash table from correlation_id to RPC context.
+-Cancel RPC.
+
+The bugs mentioned above are widespread in other rpc frameworks. Let's take a look at how brpc solves these problems through bthread_id.
+
+bthread_id consists of two parts, one is the 64-bit id visible to the user, and the other is the corresponding invisible bthread::Id structure. User interfaces are all operations id. The way of mapping from id to structure is similar to [other structure] (memory_management.md) in brpc: 32-bit is the displacement of the memory pool, and 32-bit is the version. The former is O(1) time positioning, and the latter prevents ABA problems.
+
+The interface of bthread_id is not very concise, there are many APIs:
+
+- create
+- lock
+- unlock
+- unlock_and_destroy
+- join
+- error
+
+So many interfaces are to satisfy different usage processes.
+
+- 发送request的流程：bthread_id_create -> bthread_id_lock -> ... register timer and send RPC ... -> bthread_id_unlock
Review comment:
The process of sending a request: bthread_id_create -> bthread_id_lock -> ... register timer and send RPC ... -> bthread_id_unlock
##########
File path: docs/en/circuit_breaker.md
##########
@@ -0,0 +1,64 @@
+# Fuse function
+When we initiate an rpc, brpc will first get a list of available nodes from the naming service, and then select a node as the actually visited node according to the load balancing strategy. When a node fails, brpc can automatically remove it from the list of available nodes, and periodically perform health checks on the failed node.
+
+# Default circuit breaker strategy
+By default, brpc will provide a simple fuse strategy. Under the default fuse strategy, if brpc detects that a node cannot establish a connection, it will fuse the node. When a certain rpc returns the following errors, brpc will think that the target node cannot establish a connection: ECONNREFUSED, ENETUNREACH, EHOSTUNREACH, EINVAL.
+
+What needs to be pointed out here is that if brpc finds that a node has three consecutive connection timeouts (instead of rpc timeout), then the third timeout will also be treated as ENETUNREACH. So if the rpc timeout is set to be shorter than the connection timeout, then when the node cannot establish a connection, the rpc timeout will be triggered earlier than the connection timeout, which will eventually cause the fuse to never be triggered. Therefore, when customizing the timeout time, you need to ensure that the rpc timeout time is greater than the connection timeout time. That is, ChannelOptions.timeout_ms> ChannelOptions.connect_timeout_ms.
+
+The default fusing strategy is always on, no configuration is required, and it cannot be turned off.
+
+# Optional fusing strategy
+Relying only on the above-mentioned default circuit breaker strategy sometimes cannot fully meet the demand. Take an extreme example: if a downstream node logic thread is all stuck, but the io thread can work normally, then all requests will time out, but the tcp connection Can be established normally. For such situations, brpc provides a more radical fusing strategy on the basis of the default fusing strategy. After being turned on, brpc will determine whether the node is in a fault state based on the error rate.
+
+## How to open
Review comment:
turn on
##########
File path: docs/en/timer_keeping.md
##########
@@ -0,0 +1,55 @@
+Doing something at a few points is a basic requirement of the RPC framework, which is harder than it looks.
Review comment:
at some certain time points
##########
File path: docs/en/case_baidu_dsp.md
##########
@@ -0,0 +1,23 @@
+# background
Review comment:
Background
##########
File path: docs/en/contention_profiler.md
##########
@@ -0,0 +1,31 @@
+brpc can analyze the time spent waiting for the lock and the functions that waited for.
+
+# How to open
Review comment:
And we may need replace 'open' with 'turn on' in all places
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@brpc.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@brpc.apache.org
For additional commands, e-mail: dev-help@brpc.apache.org