Merge pull request ceph#64172 from zdover23/wip-doc-2025-06-25-tr70758-radosgw-bucket_logging

doc/radosgw: line edit bucket_logging.rst

Reviewed-by: Yuval Lifshitz <[email protected]>

Author: zdover23

doc/radosgw/bucket_logging.rst

@@ -6,60 +6,74 @@ 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::
    :maxdepth: 1
 
 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>``