You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Dynamic send and batch send splits for milestone 1.5 (#367)
* Improve producer edge cases
* remove the code duplication when the producer is closed correctly or not
* make the unconfirmed operation more atomic to avoid rare cases when the unconfirmed operations were out of the mutex lock
* Increase the timeout for the Reliable producers and consumers. It was too low. Now, there is one more wait for the producer to wait for pending messages to be flushed when closed.
* refactor publish confirm channel with a lock to check if it is valid or not and avoid race conditions during the closing
* handle when the producer is not found during the confirmation. It can happen when the producer is closed before all the messages are confirmed
Signed-off-by: Gabriele Santomaggio <[email protected]>
* Improve producer edge cases
* remove the code duplication when the producer is closed correctly or not
* make the unconfirmed operation more atomic to avoid rare cases when the unconfirmed operations were out of the mutex lock
* Increase the timeout for the Reliable producers and consumers. It was too low. Now, there is one more wait for the producer to wait for pending messages to be flushed when closed.
* refactor publish confirm channel with a lock to check if it is valid or not and avoid race conditions during the closing
* handle when the producer is not found during the confirmation. It can happen when the producer is closed before all the messages are confirmed
Signed-off-by: Gabriele Santomaggio <[email protected]>
* Bump Windows version to rabbitmq 4.0.5 and erlang 27.2
Signed-off-by: Gabriele Santomaggio <[email protected]>
* update dependencies
Signed-off-by: Gabriele Santomaggio <[email protected]>
* temporary remove Windows test due to actions/checkout#1186
---------
Signed-off-by: Gabriele Santomaggio <[email protected]>
Co-authored-by: Alberto Moretti <[email protected]>
The broker should start in a few seconds. When it’s ready, enable the `stream` plugin and `stream_management`:
73
74
```shell
@@ -85,6 +86,11 @@ See [getting started](./examples/getting_started.go) example.
85
86
86
87
See [examples](./examples/) directory for more use cases.
87
88
89
+
### Client best practices
90
+
91
+
This client provides a set of best practices to use the client in the best way. </br>
92
+
See [best practices](./best_practices/README.md) for more details.
93
+
88
94
# Usage
89
95
90
96
### Connect
@@ -251,15 +257,8 @@ To publish a message you need a `*stream.Producer` instance:
251
257
producer, err:= env.NewProducer("my-stream", nil)
252
258
```
253
259
254
-
With `ProducerOptions` is possible to customize the Producer behaviour:
255
-
```golang
256
-
typeProducerOptionsstruct {
257
-
Namestring// Producer name, it is useful to handle deduplication messages
258
-
QueueSizeint// Internal queue to handle back-pressure, low value reduces the back-pressure on the server
259
-
BatchSizeint// It is the batch-size aggregation, low value reduce the latency, high value increase the throughput
260
-
BatchPublishingDelayint// Period to send a batch of messages.
261
-
}
262
-
```
260
+
With `ProducerOptions` is possible to customize the Producer behaviour.
261
+
263
262
264
263
The client provides two interfaces to send messages.
265
264
`send`:
@@ -277,30 +276,35 @@ for z := 0; z < 10; z++ {
277
276
err = producer.BatchSend(messages)
278
277
```
279
278
279
+
### `Send` vs `BatchSend`
280
280
281
-
`producer.Send`:
282
-
- accepts one message as parameter
283
-
- automatically aggregates the messages
284
-
- automatically splits the messages in case the size is bigger than `requestedMaxFrameSize`
285
-
- automatically splits the messages based on batch-size
286
-
- sends the messages in case nothing happens in `producer-send-timeout`
287
-
- is asynchronous
281
+
The `BatchSend` is the primitive to send the messages. It is up to the user to manage the aggregation.
282
+
`Send` introduces a smart layer to publish messages and internally uses `BatchSend`.
288
283
289
-
`producer.BatchSend`:
290
-
- accepts an array messages as parameter
291
-
- is synchronous
284
+
Starting from version 1.5.0, the `Send` uses a dynamic send.
285
+
The client sends the message buffer regardless of any timeout.</br>
292
286
293
-
Close the producer:
294
-
`producer.Close()` the producer is removed from the server. TCP connection is closed if there aren't </b>
295
-
other producers
287
+
What should you use? </br>
288
+
The `Send` method is the best choice for most of the cases:</br>
289
+
- It is asynchronous
290
+
- It is smart to aggregate the messages in a batch with a low-latency
291
+
- It is smart to split the messages in case the size is bigger than `requestedMaxFrameSize`
292
+
- You can play with `BatchSize` parameter to increase the throughput
296
293
297
-
### `Send` vs `BatchSend`
294
+
The `BatchSend` is useful in case you need to manage the aggregation by yourself. </br>
295
+
It gives you more control over the aggregation process: </br>
296
+
- It is synchronous
297
+
- It is up to the user to manage the aggregation
298
+
- It is up to the user to split the messages in case the size is bigger than `requestedMaxFrameSize`
299
+
- It can be faster than `Send` in case the aggregation is managed by the user.
298
300
299
-
The `BatchSend` is the primitive to send the messages, `Send` introduces a smart layer to publish messages and internally uses `BatchSend`.
301
+
#### Throughput vs Latency</br>
302
+
With both methods you can have low-latency and/or high-throughput. </br>
303
+
The `Send` is the best choice for low-latency without care about aggregation.
304
+
With `BatchSend` you have more control.</br>
300
305
301
-
The `Send` interface works in most of the cases, In some condition is about 15/20 slower than `BatchSend`. See also this [thread](https://groups.google.com/g/rabbitmq-users/c/IO_9-BbCzgQ).
302
-
303
-
See also "Client performances" example in the [examples](./examples/performances/) directory
306
+
Performance test tool can help you to test `Send` and `BatchSend` </br>
307
+
See also the [Performance test tool](#performance-test-tool) section.
304
308
305
309
### Publish Confirmation
306
310
@@ -350,10 +354,13 @@ the values `messageStatus.GetMessage().GetPublishingId()` and `messageStatus.Get
350
354
351
355
See also "Getting started" example in the [examples](./examples/) directory
352
356
353
-
354
-
355
357
### Deduplication
356
358
359
+
The deduplication is a feature that allows to avoid the duplication of messages. </br>
360
+
It is enabled by the user by setting the producer name with the options: </br>
The scope of this document is to provide a set of best practices for the client applications that use the Go client library.</br>
5
+
6
+
7
+
#### General recommendations
8
+
- Messages are not thread-safe, you should not share the same message between different go-routines or different Send/BatchSend calls.
9
+
- Use the producer name only if you need deduplication.
10
+
- Avoid to store the consumer offset to the server too often.
11
+
-`Send` works well in most of the cases, use `BatchSend` when you need more control.
12
+
- Connections/producers/consumers are designed to be long-lived. You should avoid creating and closing them too often.
13
+
- The library is generally thread-safe,even it is better to use one producer/consumer per go-routine.
14
+
15
+
#### Default configuration
16
+
17
+
The default configuration of the client library is designed to be used in most of the cases.
18
+
No particular tuning is required. Just follow the [Getting started](../examples/getting_started.go) example.
19
+
20
+
#### Multiple producers and consumers
21
+
22
+
Each connection can support multiple producers and consumers, you can reduce the number of connections by using the same connection for multiple producers and consumers.</br>
23
+
With:
24
+
```golang
25
+
SetMaxConsumersPerClient(10).
26
+
SetMaxConsumersPerClient(10)
27
+
```
28
+
The TCP connection will be shared between the producers and consumers.
29
+
Note about consumers: One slow consumer can block the others, so it is important:
30
+
- To have a good balance between the number of consumers and the speed of the consumers.
31
+
- work application side to avoid slow consumers, for example, by using a go-routines/buffers.
32
+
33
+
#### High throughput
34
+
35
+
To achieve high throughput, you should use one producer per connection, and one consumer per connection.
36
+
This will avoid lock contention between the producers when sending messages and between the consumers when receiving messages.
37
+
38
+
The method `Send` is usually enough to achieve high throughput.
39
+
In some case you can use the `BatchSend` method. See the `Send` vs `BatchSend` documentation for more details.
40
+
41
+
#### Low latency
42
+
43
+
To achieve Low latency, you should use one producer per connection, and one consumer per connection.
44
+
45
+
The method `Send` is the best choice to achieve low latency. Default values are tuned for low latency.
46
+
You can change the `BatchSize` parameter to increase or reduce the max number of messages sent in one batch.
47
+
Note: Since the client uses dynamic send, the `BatchSize` parameter is a hint to the client, the client can send less than the `BatchSize`.
48
+
49
+
#### Store several text based messages
50
+
51
+
In case you want to store logs, text-based or big messages, you can use the `Sub Entries Batching` method.
52
+
Where it is possible to store multiple messages in one entry and compress the entry with different algorithms.
53
+
It is useful to reduce the disk space and the network bandwidth.
54
+
See the `Sub Entries Batching` documentation for more details.</br>
55
+
56
+
#### Store several small messages
57
+
58
+
In case you want to store a lot of small messages, you can use the `BatchSend` method.
59
+
Where it is possible to store multiple messages in one entry. This will avoid creating small chunks on the server side.</br>
60
+
61
+
62
+
#### Avoid duplications
63
+
64
+
In case you want to store messages with deduplication, you need to set the producer name and the deduplication id.
65
+
See the `Deduplication` documentation for more details.</br>
66
+
67
+
68
+
#### Consumer fail over
69
+
70
+
In case you want to have a consumer fail over, you can use the `Single Active Consumer` method.
71
+
Where only one consumer is active at a time, and the other consumers are in standby mode.
72
+
73
+
#### Reliable producer and consumer
74
+
75
+
The client library provides a reliable producer and consumer, where the producer and consumer can recover from a connection failure.
76
+
See the `Reliable` documentation for more details.</br>
77
+
78
+
79
+
#### Scaling the streams
80
+
81
+
In case you want to scale the streams, you can use the `Super Stream` method.
82
+
Where you can have multiple streams and only one stream is active at a time.
83
+
See the `Super Stream` documentation for more details.</br>
84
+
85
+
86
+
#### Filtering the data when consuming
87
+
88
+
In case you want to filter the data when consuming, you can use the `Stream Filtering` method.
89
+
Where you can filter the data based on the metadata.
90
+
See the `Stream Filtering` documentation for more details.</br>
91
+
92
+
93
+
#### Using a load balancer
94
+
95
+
In case you want to use a load balancer, you can use the `Using a load balancer` method.
96
+
In Kubernetes, you can use the service name as load balancer dns.
97
+
See the `Using a load balancer` documentation for more details.</br>
0 commit comments