Skip to content

Commit 6bbba09

Browse files
mkuratczykmkuratczyk
committed
Update README
1 parent 4925530 commit 6bbba09

1 file changed

Lines changed: 47 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 47 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
## omq
22

3-
`omq` is a messaging system client for testing purposes. It currently supports AMQP 1.0, AMQP 0.9.1, STOMP and MQTT 3.1/3.1.1/5.0. It is developed mostly for RabbitMQ but might be useful for other brokers
4-
as well (some tests against ActiveMQ were performed).
3+
`omq` is a messaging system client for testing purposes. It currently supports
4+
AMQP 1.0, AMQP 0.9.1, STOMP and MQTT 3.1/3.1.1/5.0. It is developed mostly for
5+
RabbitMQ but might be useful for other brokers as well (some tests against
6+
ActiveMQ were performed).
57

6-
`omq` starts a group of publishers and a group of consumers, in both cases all publishers/consumers are identical,
7-
except for the target terminus/queue/routing key, which may be slightly different. The publishers can use
8-
a different protocol than the consumers.
8+
`omq` starts a group of publishers and a group of consumers. The publishers
9+
can use a different protocol than the consumers.
910

1011
`omq` has subcommands for all protocol combinations. For example:
1112
```shell
@@ -20,20 +21,37 @@ A more complex example:
2021
$ omq mqtt-amqp --publishers 10 --publish-to 'sensor/%d' --rate 1 --size 100 \
2122
--consumers 1 --consume-from /queues/sensors --binding-key 'sensor.#' --queues classic
2223
```
23-
will start 10 MQTT publishers, each publishing 1 message a second, with 100 bytes of payload, to the `amq.topic` exchange (default for the MQTT plugin)
24-
with the topic/routing key of `sensor/%d`, where the `%d` is the ID of the publisher (from 1 to 10). It will also start a single AMQP 1.0 consumer that
25-
consumes all those messages by declaring a classic queue `sensors` with a wildcard subscription.
24+
will start 10 MQTT publishers, each publishing 1 message a second, with 100
25+
bytes of payload, to the `amq.topic` exchange (default for the MQTT plugin)
26+
with the topic/routing key of `sensor/%d`, where the `%d` is the ID of the
27+
publisher (from 1 to 10). It will also start a single AMQP 1.0 consumer that
28+
consumes all those messages by declaring a classic queue `sensors` with a
29+
wildcard subscription.
2630

27-
If the publishing and consuming protocol is the same, you can use abbreviated commands: `amqp` instead of `amqp-amqp`, `stomp` instead of `stomp-stomp`
28-
and `mqtt` instead of `mqtt-mqtt`.
31+
If the publishing and consuming protocol is the same, you can use abbreviated
32+
commands: `amqp` instead of `amqp-amqp`, `stomp` instead of `stomp-stomp`, etc.
2933

3034
### Installation
3135

36+
#### Binary
37+
38+
You can get the latest binary from there [releases page](https://github.com/rabbitmq/omq/releases).
39+
40+
#### OCI Image
41+
42+
An [OCI image](https://hub.docker.com/r/pivotalrabbitmq/omq/tags) is available: `pivotalrabbitmq/omq`.
43+
44+
#### From source
45+
3246
```shell
3347
$ go install github.com/rabbitmq/omq@main
3448
```
3549

36-
An [OCI image](https://hub.docker.com/r/pivotalrabbitmq/omq/tags) is also available: `pivotalrabbitmq/omq`.
50+
or
51+
```
52+
git clone github.com/rabbitmq/omq
53+
go build
54+
```
3755

3856
### Connecting to the Broker
3957

@@ -44,7 +62,7 @@ you can use `--uri` instead (but can't mix `--uri` with `--publisher-uri` and `-
4462

4563
For example, here both publishers and consumers will connect to either of the 3 URIs:
4664
```shell
47-
$ omq mqtt --uri mqtt://localhost:1883 --uri mqtt://localhost:1884 --uri mqtt://localhost:1885
65+
$ omq mqtt --uri mqtt://localhost:1883,mqtt://localhost:1884,mqtt://localhost:1885
4866
```
4967

5068
And in this case, all consumers will connect to port 1883, while publishers to 1884:
@@ -82,12 +100,17 @@ RabbitMQ 4.1 added [AMQP-1.0 stream filtering support](https://github.com/rabbit
82100
Note that this is a separate feature from stream filtering of the Stream protocol.
83101

84102
`omq` supports AMQP-1.0 stream filtering in the following ways:
85-
1. When publishing, you can specify application properties. If multiple values are provided, one of them is used for each message
86-
(so you get a mix of messages with different values). For example, `--amqp-app-property key=foo,bar,baz` will publish some messages
87-
with `key=foo`, some with `key=bar` and some with `key=baz` (in roughly equal proportions).
88-
2. When consuming, you can apply a filter, for example, `--amqp-app-property-filter key=&p:ba` will tell RabbitMQ to only deliver
89-
messages where the `key` property starts with `ba` (`&p:` means that what follows is a prefix), so it'll return roughly 66%
90-
of the messages in the stream. You can filter on properties (eg. `subject`) or application properties.
103+
1. When publishing, you can specify application properties. If multiple values
104+
are provided, one of them is used for each message (so you get a mix of
105+
messages with different values). For example, `--amqp-app-property
106+
key=foo,bar,baz` will publish some messages with `key=foo`, some with `key=bar`
107+
and some with `key=baz` (in roughly equal proportions).
108+
109+
2. When consuming, you can apply a filter, for example,
110+
`--amqp-app-property-filter key=&p:ba` will tell RabbitMQ to only deliver
111+
messages where the `key` property starts with `ba` (`&p:` means that what
112+
follows is a prefix), so it'll return roughly 66% of the messages in the
113+
stream. You can filter on properties (eg. `subject`) or application properties.
91114

92115
Here's a full example, where we can see this in action:
93116
```shell
@@ -99,17 +122,19 @@ $ omq amqp --queues stream -t /queues/stream -T /queues/stream --rate 100 --amqp
99122
2024/10/04 13:48:29 published=100/s consumed=34/s
100123
```
101124

102-
We publish 100 messages per second with 3 different key values and then consume only messages with one of the values. Therefore, the consumption
103-
rate is one third of the publishing rate.
125+
We publish 100 messages per second with 3 different key values and then consume
126+
only messages with one of the values. Therefore, the consumption rate is one
127+
third of the publishing rate.
104128

105129
### Templated Values
106130

107131
Some flags are parsed as Go text templates and provide additional functions from the [Sprig](https://masterminds.github.io/sprig/) library.
108132
This allows setting random or otherwise generated values. For example:
109133

110-
* `--message-priority '{{ randInt 1 10 }}'` set a random message priority from the given range
111-
* `--consumer-latency '{{ randInt 1 60 }}ms'` wait a random (between 1 and 60) number of milliseconds before acking a message
134+
* `--message-priority '{{ randInt 1 10 }}'` sets a random message priority from the given range
135+
* `--consumer-latency '{{ randInt 1 60 }}ms'` waits a random (between 1 and 60) number of milliseconds before acking a message
112136
* `--publishers 10 --publish-to '/queues/cq-{{ mod .id 2 }}'` declare 2 queues and start 5 publishers per queue
137+
* `--amqp-modify "x-timestamp={{ now }}"` sets the `x-timestamp` annotation to the current time
113138

114139
### Metrics
115140

0 commit comments

Comments
 (0)