doc/radosgw: line edit bucket_logging.rst

Edit doc/radosgw/bucket_logging.rst so that it is not solecistic and so
that its punctuation is corrected and its use of articles is corrected.
This file remains in my judgment demotic and maybe demotic enough to
warrant another editorial pass in the future.

Fixes: https://tracker.ceph.com/issues/70758
Signed-off-by: Zac Dover <zac.dover@proton.me>

diff --git a/doc/radosgw/bucket_logging.rst b/doc/radosgw/bucket_logging.rst
index a82566d62e647c36d31c16b116f5bcb7914737bf..9a1ca46182a4ecad47bd18cf362f9b9e3803abee 100644 (file)
--- a/doc/radosgw/bucket_logging.rst
+++ b/doc/radosgw/bucket_logging.rst
@@ -6,29 +6,33 @@ Bucket Logging
 
 .. contents::
 
-Bucket logging provides a mechanism for logging all access to a bucket. The
-log data can be used to monitor bucket activity, detect unauthorized
-access, get insights into the bucket usage and use the logs as a journal for bucket changes.
-The log records are stored in objects in a separate bucket and can be analyzed later.
-Logging configuration is done at the bucket level and can be enabled or disabled at any time.
-The log bucket can accumulate logs from multiple buckets. It is recommended to configured
-a different "prefix" for each bucket, so that the logs of different buckets will be stored
-in different objects in the log bucket.
+Bucket logging provides a mechanism for logging all access to a bucket. The log
+data can be used to monitor bucket activity, detect unauthorized access, get
+insights into bucket usage, and use the logs as a journal for bucket
+changes. The log records are stored in objects in a separate bucket and can be
+analyzed later. Logging configuration is done at the bucket level and can be
+enabled or disabled at any time. The log bucket can accumulate logs from
+multiple buckets. It is recommended to configure a different "prefix" for each
+bucket, so that the logs of different buckets will be stored in different
+objects in the log bucket.
 
 .. note::
 
     - The log bucket must be created before enabling logging on a bucket
     - The log bucket cannot be the same as the bucket being logged
     - The log bucket cannot have logging enabled on it
-    - The log bucket cannot have any encryption set on in (including SSE-S3 with AES-256)
+    - The log bucket cannot have any encryption set on it (including SSE-S3
+      with AES-256)
     - The log bucket cannot have any compression set on it
     - The log bucket must not have RequestPayer enabled
-    - Source and log bucket must be in the same zonegroup
-    - Source and log buckets may belong to different accounts (with proper bucket policy set)
+    - Source and log buckets must be in the same zonegroup
+    - Source and log buckets may belong to different accounts (with proper
+      bucket policy set)
     - The log bucket may have object lock enabled with default retention period
-    - The 16 byte unique ID part of the log object name is a lexicographically ordered random string,
-      that consists of a 10 bytes counter, and a 6 bytes random alphanumeric string.
-      or a random, alphanumeric string if the counter is not available
+    - The 16-byte unique ID part of the log object name is a lexicographically
+      ordered random string that consists of a 10-byte counter and a 6-byte
+      random alphanumeric string (or a random alphanumeric string if the
+      counter is not available)
 
 
 .. toctree::
@@ -36,30 +40,40 @@ in different objects in the log bucket.
 
 Logging Reliability
 -------------------
-For performance reasons, even though the log records are written to persistent storage, the log object will
-appear in the log bucket only after some configurable amount of time (or if the maximum object size of 128MB is reached).
-This time (in seconds) could be set per source bucket via a Ceph extension to the REST API,
-or globally via the `rgw_bucket_logging_obj_roll_time` configuration option. If not set, the default time is 5 minutes.
-Adding a log object to the log bucket is done "lazily", meaning, that if no more records are written to the object, it may
-remain outside of the log bucket even after the configured time has passed.
-To counter that, you can flush all logging objects on a given source bucket to log them,
-regardless if enough time passed or if no more records are written to the object.
-Flushing will happen automatically when logging is disabled on a bucket, its logging configuration is changed, or the bucket is deleted.
+For performance reasons, even though the log records are written to persistent
+storage, the log object will appear in the log bucket only after some
+configurable amount of time (or if the maximum object size of 128MB is
+reached). This time (in seconds) can be set per source bucket via a Ceph
+extension to the REST API, or globally via the
+`rgw_bucket_logging_obj_roll_time` configuration option. If not set, the
+default time is 5 minutes. Adding a log object to the log bucket is done
+"lazily", meaning that if no more records are written to the object, it may
+remain outside of the log bucket even after the configured time has passed. To
+counter that, you can flush all logging objects on a given source bucket to log
+them, regardless if enough time passed or if no more records are written to the
+object. Flushing will happen automatically when logging is disabled on a
+bucket, or its logging configuration is changed, or the bucket is deleted.
 
 Standard
 ````````
-If logging type is set to "Standard" (the default) the log records are written to the log bucket after the bucket operation is completed.
-This means that there are the logging operation may fail, with no indication to he client.
+If the logging type is set to "Standard" (the default) the log records are
+written to the log bucket after the bucket operation is completed. This means
+that the logging operation may fail with no indication to the client.
 
 Journal
 ```````
-If logging type is set to "Journal", the records are written to the log bucket before the bucket operation is completed.
-This means that if the logging action fails, the operation will not be executed, and an error will be returned to the client
-Some exceptions exists to that rule, the "Fails Operation" columns in the table below indicate by "No" which operations will not fail even if logging failed.
-Journal mode supports filtering out records based on matches of the prefixes and suffixes of the logged object keys. Regular-expression matching can also be used on these to create filters.
-Note that it may happen that the log records were successfully written, but the bucket operation failed, since the logs are written.
-
-The following operation are supported in journal mode:
+If the logging type is set to "Journal", the records are written to the log
+bucket before the bucket operation is completed. This means that if the logging
+action fails, the operation is not executed and an error is returned to the
+client. Some exceptions to that rule exist: the "Fails Operation" columns in
+the table below indicate by "No" which operations will not fail even if logging
+failed. Journal mode supports filtering out records based on matches of the
+prefixes and suffixes of the logged object keys. Regular-expression matching
+can also be used on these to create filters. Note that it may happen that the
+log records were successfully written but the bucket operation failed, since
+the logs are written.
+
+The following operations are supported in journal mode:
 
 +-------------------------------+-------------------------------------+-----------------+
 | Operation                     | Operation Name                      | Fails Operation |
@@ -87,16 +101,21 @@ The following operation are supported in journal mode:
 
 Multisite
 `````````
-In a multi-zone deployment, each zone will use its own log object before the log object is added to the log bucket.
-After the log object is added to the log bucket (e.g after being flushed) it will be replicated to other zones.
-This means that for a given time period there could be more than one log object holding relevant log records.
+In a multi-zone deployment, each zone uses its own log object before the
+log object is added to the log bucket. After the log object is added to the
+log bucket (that is, after being flushed) it is replicated to other zones.
+This means that for a given time period there can be more than one log object
+holding relevant log records.
 
 Bucket Logging Policy
 ---------------------
-On the source bucket, only its owner is allowed to enable or disable bucket logging.
-For a bucket to be used as a log bucket, it must have bucket policy that allows that (even if the source bucket and the log bucket are owned by the same user or account).
-The bucket policy must allow the `s3:PutObject` action for the log bucket, to be performed by the `logging.s3.amazonaws.com` service principal.
-It should also specify the source bucket and account that are expected to write logs to it. For example:
+On the source bucket, only its owner is allowed to enable or disable bucket
+logging. For a bucket to be used as a log bucket, it must have a bucket policy
+that allows that (even if the source bucket and the log bucket are owned by the
+same user or account). The bucket policy must allow the `s3:PutObject` action
+for the log bucket, to be performed by the `logging.s3.amazonaws.com` service
+principal. The bucket policy should also specify the source bucket and account
+that are expected to write logs to it. For example:
 
 ::
 
@@ -126,9 +145,11 @@ It should also specify the source bucket and account that are expected to write
 
 Bucket Logging Quota
 --------------------
-Bucket and user quota are applied on the log bucket. Quota is checked every time a log record is written,
-and updated when the log object is added to the log bucket. In "Journal" mode, if the quota is exceeded, the logging operation will fail
-and as a result the bucket operation will also fail. In "Standard" mode, the logging operation will be skipped, but the bucket operation will continue.
+Bucket and user quota are applied on the log bucket. Quota is checked every
+time a log record is written, and is updated when the log object is added to
+the log bucket. In "Journal" mode, if the quota is exceeded, the logging
+operation fails and as a result the bucket operation also fails. In "Standard"
+mode, the logging operation is skipped, but the bucket operation continues.
 
 
 Bucket Logging REST API
@@ -170,14 +191,16 @@ For example:
 Log Records
 ~~~~~~~~~~~
 
-The log records are space separated string columns and have the following possible formats:
+The log records are space-separated string columns and have the following
+possible formats:
 
 Journal
 ```````
-minimum amount of data used for journaling bucket changes (this is a Ceph extension).
+minimum amount of data used for journaling bucket changes (this is a Ceph
+extension).
 
   - bucket owner (or dash if empty)
-  - bucket name (or dash if empty). in the format: ``[tenant:]<bucket name>``
+  - bucket name (or dash if empty), in the format: ``[tenant:]<bucket name>``
   - time in the following format: ``[day/month/year:hour:minute:second timezone]``
   - object key (or dash if empty)
   - operation in the following format: ``WEBSITE/REST.<HTTP method>.<resource>``