Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doc improvements #5258

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Doc improvements #5258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f32da84
ARTEMIS-5057 add docs for large-message-sync
jbertram Sep 24, 2024
05556f2
ARTEMIS-5057 fill in missing config index + other doc updates
jbertram Sep 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions artemis-server/src/main/resources/schema/artemis-configuration.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -600,7 +600,7 @@
<xsd:element name="journal-retention-directory" maxOccurs="1" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
the directory to store journal-retention message in and rention configuraion.
where to keep retained data including attributes for how long to keep it (unit and period) and how much to keep (storage-limit)
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
Expand Down Expand Up @@ -636,7 +636,7 @@
Notice we first remove files based on period and if you're using more storage then you
configured we start removing older files.
By default this is unlimited (not filled).
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
Expand Down Expand Up @@ -685,7 +685,7 @@
</xsd:annotation>
</xsd:element>

<xsd:element name="journal-device-block-size" type="xsd:long" maxOccurs="1" minOccurs="0">
<xsd:element name="journal-device-block-size" type="xsd:long" default="4096" maxOccurs="1" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
The size in bytes used by the device. This is usually translated as fstat/st_blksize
Expand All @@ -698,7 +698,7 @@
<xsd:annotation>
<xsd:documentation>
The size (in bytes) of the internal buffer on the journal.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -733,7 +733,7 @@
<xsd:annotation>
<xsd:documentation>
The size (in bytes) of each journal file.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -809,7 +809,7 @@
<xsd:documentation>
Size (in bytes) before all addresses will enter into their Full Policy configured upon messages being
produced.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand All @@ -827,7 +827,7 @@
<xsd:annotation>
<xsd:documentation>
Min free bytes on disk below which the system blocks or fails clients. Supports byte notation like
"K", "Mb", "GB", etc. Will override max-disk-usage if both are set.
"K", "MB", "GB", etc. Will override max-disk-usage if both are set.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -1421,7 +1421,7 @@
<xsd:annotation>
<xsd:documentation>
Any message larger than this size (in bytes) is considered a large message (to be sent in chunks).
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -1506,7 +1506,7 @@
<xsd:annotation>
<xsd:documentation>
Once the bridge has received this many bytes, it sends a confirmation.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand All @@ -1515,7 +1515,7 @@
<xsd:annotation>
<xsd:documentation>
Producer flow control.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -2461,7 +2461,7 @@
<xsd:annotation>
<xsd:documentation>
Messages larger than this are considered large-messages.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -2559,7 +2559,7 @@
<xsd:annotation>
<xsd:documentation>
The size (in bytes) of the window used for confirming data from the server connected to.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand All @@ -2568,7 +2568,7 @@
<xsd:annotation>
<xsd:documentation>
Producer flow control.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -2904,7 +2904,7 @@
<xsd:annotation>
<xsd:documentation>
The max page size (in bytes) to use for all addresses when using JDBC.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -3933,7 +3933,7 @@
<xsd:documentation>
the maximum size (in bytes) for an address (-1 means no limits). This is used in PAGING, BLOCK and
FAIL policies.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand All @@ -3950,7 +3950,7 @@
<xsd:annotation>
<xsd:documentation>
After the address enters into page mode, this attribute will configure how many pages can be written into page before activating the page-full-policy.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -3978,7 +3978,7 @@
<xsd:annotation>
<xsd:documentation>
The page size (in bytes) to use for an address.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down Expand Up @@ -4580,7 +4580,7 @@
<xsd:element name="connector-services">
<xsd:annotation>
<xsd:documentation>
a list of connector services
DEPRECATED: a list of connector services
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
Expand All @@ -4596,7 +4596,7 @@
<xsd:element maxOccurs="1" minOccurs="1" name="factory-class" type="xsd:string">
<xsd:annotation>
<xsd:documentation>
Name of the factory class of the ConnectorService
DEPRECATED: Name of the factory class of the ConnectorService
</xsd:documentation>
</xsd:annotation>
</xsd:element>
Expand Down
97 changes: 94 additions & 3 deletions docs/user-manual/configuration-index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,11 @@ This is a list
| The amount in bytes before all addresses are considered full.
| Half of the JVM's `-Xmx`

| xref:paging.adoc#global-max-messages[global-max-messages]
| Number of messages before all addresses will enter into their Full Policy configured.
It works in conjunction with global-max-size, being watever value hits its maximum first.
| `-1`

| xref:graceful-shutdown.adoc#graceful-server-shutdown[graceful-shutdown-enabled]
| true means that graceful shutdown is enabled.
| `false`
Expand Down Expand Up @@ -345,14 +350,30 @@ The system will create as many files as needed however when reclaiming files it
| the type of journal to use.
| `ASYNCIO`

| xref:data-retention.adoc#data-retention[journal-retention-directory]
| where to keep retained data including attributes for how long to keep it (`unit` & `period`) and how much to keep (`storage-limit`)
| n/a

| xref:persistence.adoc#configuring-the-message-journal[journal-datasync]
| It will use msync/fsync on journal operations.
| `true`

| journal-device-block-size
| The size in bytes used by the storage device. This is usually translated as `fstat`/`st_blksize`, and this is a way to bypass the value returned as `st_blksize`.
| `4096`

| log-journal-write-rate
| Whether to log messages about the journal write rate.
| `false`

| xref:large-messages.adoc#large-messages[large-messages-directory]
| the directory to store large messages.
| `data/largemessages`

| xref:large-messages.adoc#configuring-the-server[large-message-sync]
| should sync large messages before closing the file
| `true`

| log-delegate-factory-class-name
| *deprecated* the name of the factory class to use for log delegation.
| n/a
Expand All @@ -379,9 +400,16 @@ If set to "true" the passwords are masked.
| xref:paging.adoc#max-disk-usage[max-disk-usage]
| The max percentage of data we should use from disks.
The broker will block while the disk is full.
Disable by setting -1.
Disable by setting `-1`.
| 90

| xref:paging.adoc#minimum-disk-free[min-disk-free]
| Min free bytes on disk below which the system blocks or fails clients.
Supports byte notation like "K", "MB", "GB", etc.
Will override `max-disk-usage` if both are set.
Disable by setting `-1`.
| `-1`

| xref:perf-tuning.adoc#performance-tuning[memory-measure-interval]
| frequency to sample JVM memory in ms (or -1 to disable memory sampling).
| -1
Expand Down Expand Up @@ -487,14 +515,22 @@ In most cases this should be set to '1'.
| Maximum number of threads to use for the scheduled thread pool.
| 5

| xref:security.adoc#authentication-authorization[security-enabled]
| xref:security.adoc#basic-configuration[security-enabled]
| true means that security is enabled.
| `true`

| xref:security.adoc#authentication-authorization[security-invalidation-interval]
| xref:security.adoc#caching-security-operations[security-invalidation-interval]
| how long (in ms) to wait before invalidating the security cache.
| 10000

| xref:security.adoc#caching-security-operations[authentication-cache-size]
| how large to make the authentication cache
| 1000

| xref:security.adoc#caching-security-operations[authorization-cache-size]
| how large to make the authorization cache
| 1000

| system-property-prefix
| Prefix for replacing configuration settings using Bean Utils.
| n/a
Expand All @@ -507,6 +543,10 @@ In most cases this should be set to '1'.
| whether or not to add the name of the validated user to the messages that user sends.
| `false`

| xref:security.adoc#tracking-the-validated-user[reject-empty-validated-user]
| true means that the server will not allow any message that doesn't have a validated user, in JMS this is `JMSXUserID`
| `false`

| xref:security.adoc#role-based-security-for-addresses[security-settings]
| <<security-setting-type,a list of security-setting>>.
| n/a
Expand Down Expand Up @@ -604,6 +644,57 @@ in your security-settings.
| [[management-rbac-prefix]] management-rbac-prefix
| parameter to configure the prefix for security-settings match addresses to control RBAC on xref:management.adoc#jmx-authorization-in-broker-xml[JMX MBean operations] and optionally on xref:management.adoc#fine-grained-rbac-on-management-messages[management messages]
| mops (shorthand for management operations)

| xref:address-model.adoc#temporary-queues[temporary-queue-namespace]
| the namespace to use for looking up address settings for temporary queues
| n/a

| xref:mqtt.adoc#automatic-subscription-clean-up[mqtt-session-scan-interval]
| how often (in ms) to scan for expired MQTT sessions
| `5000`

| xref:mqtt.adoc#persistent-subscriptions[mqtt-session-state-persistence-timeout]
| how long (in ms) to wait to persist MQTT session state
| `5000`

| xref:federation.adoc#federation[federations]
| a list of federation elements
| n/a

| xref:connection-routers.adoc#connection-routers[connection-routers]
| a list of connection-router elements
| n/a

| mirror-ack-manager-queue-attempts
| The number of times a mirror target would retry an acknowledgement on the queue before scanning page files for the message.
| `5`

| mirror-ack-manager-page-attempts
| The number of times a mirror target would retry an acknowledgement on paging.
| `2`

| mirror-ack-manager-retry-delay
| Period in milliseconds for which retries are going to be exercised.
| `100`

| mirror-page-transaction
| Should Mirror use Page Transactions When target destinations is paging?
When a target queue on the mirror is paged, the mirror will not record a page transaction for every message.
The default is `false`, and the overhead of paged messages will be smaller, but there is a possibility of eventual duplicates in case of interrupted communication between the mirror source and target.
If you set this to `true` there will be a record stored on the journal for the page-transaction additionally to the record in the page store.
| `false`

| xref:management.adoc#suppressing-session-notifications[suppress-session-notifications]
| Whether to suppress `SESSION_CREATED` and `SESSION_CLOSED` notifications.
Set to `true` to reduce notification overhead.
However, these are required to enforce unique client ID utilization in a cluster for MQTT clients.
| `false`

| xref:address-settings.adoc#literal-matches[literal-match-markers]
| The characters that mark a "literal" match.
A literal match means the setting(s) will only apply to the exact match regardless of wildcards.
If this setting is not omitted then it must be two characters - the start marker and the end marker.
| n/a
|===

== address-setting type
Expand Down
6 changes: 3 additions & 3 deletions docs/user-manual/core-bridges.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ See the xref:transformers.adoc#transformers[transformer chapter] for more detail

min-large-message-size::
Any message larger than this size (in bytes) is considered a large message (to be sent in chunks).
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
Default is `102400` (i.e. 100KiB).

check-period::
Expand Down Expand Up @@ -158,7 +158,7 @@ The default value for this parameter is `true`.

confirmation-window-size::
This optional parameter determines the `confirmation-window-size` to use for the connection used to forward messages to the target node.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
This attribute is described in section xref:client-failover.adoc#reconnection-and-failover-attributes[Client failover attributes]
+
[WARNING]
Expand All @@ -169,7 +169,7 @@ When using the bridge to forward messages to an address which uses the `BLOCK` `
producer-window-size::
This optional parameter determines the producer flow control through the bridge.
Use `-1` to disable.
Supports byte notation like "K", "Mb", "MiB", "GB", etc.
Supports byte notation like "K", "MB", "MiB", "GB", etc.
Default is `1048576` (i.e. 1MiB).

user::
Expand Down
12 changes: 8 additions & 4 deletions docs/user-manual/data-retention.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,17 @@
:idprefix:
:idseparator: -

If you enable `journal-retention` on broker.xml, ActiveMQ Artemis will keep copy of every data that has passed through the broker on this folder.
If you enable `journal-retention-directory` on broker.xml, ActiveMQ Artemis will keep copy of every data that has passed through the broker on this folder.

[,xml]
----
...
<journal-retention unit="DAYS" directory="history" period="365" storage-limit="10G"/>
...
<configuration...>
<core...>
...
<journal-retention-directory unit="DAYS" period="365" storage-limit="10G">history</journal-retention-directory>
...
</core>
</configuration>
----

ActiveMQ Artemis will keep a copy of each generated journal file, up to the configured retention period, at the unit chose.
Expand Down
Loading