Skip to content

Commit 790c38e

Browse files
yuvalifyuvalif
committed
rgw/logging: add support for GetBucketLogging and PutBucketLogging
this is based on AWS server access logs: - https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-server-access-logging.html - https://docs.aws.amazon.com/AmazonS3/latest/userguide/ServerLogs.html - https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLogging.html - https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLogging.html however, a new mode was added called "journal" where: - logs of PUT, COPY and MPU are guaranteed - we have logs of DELETE and multi-DELETE operations (not guaranteed) - log records hold only minimal amount of information Fixes: https://tracker.ceph.com/issues/984 Signed-off-by: Yuval Lifshitz <[email protected]>
1 parent 801186f commit 790c38e

29 files changed

+1976
-75
lines changed

‎doc/radosgw/bucket_logging.rst‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
====================
2+
Bucket Logging
3+
====================
4+
5+
.. versionadded:: T
6+
7+
.. contents::
8+
9+
Bucket logging provides a mechanism for logging all access to a bucket. The
10+
log data can be used to monitor bucket activity, detect unauthorized
11+
access, get insights into the bucket usage and use the logs as a journal for bucket changes.
12+
The log records are stored in objects in a separate bucket and can be analyzed later.
13+
Logging configuration is done at the bucket level and can be enabled or disabled at any time.
14+
The log bucket can accumulate logs from multiple buckets. It is recommended to configured
15+
a different "prefix" for each bucket, so that the logs of different buckets will be stored
16+
in different objects in the log bucket.
17+
18+
19+
.. toctree::
20+
:maxdepth: 1
21+
22+
Logging Reliability
23+
-------------------
24+
For performance reasons, even though the log records are written to persistent storage, the log object will
25+
appear in the log bucket only after some configurable amount of time (or if the maximum object size of 128MB is reached).
26+
This time (in seconds) could be set per source bucket via a Ceph extension to the REST API,
27+
or globally via the `rgw_bucket_logging_obj_roll_time` configuration option. If not set, the default time is 5 minutes.
28+
Adding a log object to the log bucket is done "lazily", meaning, that if no more records are written to the object, it may
29+
remain outside of the log bucket even after the configured time has passed.
30+
31+
Standard
32+
````````
33+
If logging type is set to "Standard" (the default) the log records are written to the log bucket after the bucket operation is completed.
34+
This means that there are the logging operation may fail, with no indication to he client.
35+
36+
Journal
37+
```````
38+
If logging type is set to "Journal", the records are written to the log bucket before the bucket operation is completed.
39+
This means that if the logging action fails, the operation will not be executed, and an error will be returned to the client.
40+
An exception to the above are "multi/delete" log records: if writing these log records fail, the operation continues and may still be successful.
41+
Note that it may happen that the log records were successfully written, but the bucket operation failed, since the logs are written
42+
before such a failure, there will be no indication for that in the log records.
43+
44+
45+
Bucket Logging REST API
46+
-----------------------
47+
Detailed under: `Bucket Operations`_.
48+
49+
50+
Log Objects Key Format
51+
----------------------
52+
53+
Simple
54+
``````
55+
has the following format:
56+
57+
::
58+
59+
<prefix><year-month-day-hour-minute-second>-<16 bytes unique-id>
60+
61+
For example:
62+
63+
::
64+
65+
fish/2024-08-06-09-40-09-TI9ROKN05DD4HPQF
66+
67+
Partitioned
68+
```````````
69+
has the following format:
70+
71+
::
72+
73+
<prefix><bucket owner>/<source region>/<bucket name>/<year>/<month>/<day>/<year-month-day-hour-minute-second>-<16 bytes unique-id>
74+
75+
For example:
76+
77+
::
78+
79+
fish/testid//all-log/2024/08/06/2024-08-06-10-11-18-1HMU3UMWOJKNQJ0X
80+
81+
Log Records
82+
~~~~~~~~~~~
83+
84+
The log records are space separated string columns and have the following possible formats:
85+
86+
Journal
87+
```````
88+
minimum amount of data used for journaling bucket changes (this is a Ceph extension).
89+
90+
- bucket owner (or dash if empty)
91+
- bucket name (or dash if empty)
92+
- time in the following format: ``[day/month/year:hour:minute:second timezone]``
93+
- object key (or dash if empty)
94+
- operation in the following format: ``WEBSITE/REST.<HTTP method>.<resource>``
95+
- object size (or dash if empty)
96+
- version id (dash if empty or question mark if unknown)
97+
- eTag
98+
99+
For example:
100+
101+
::
102+
103+
testid fish [06/Aug/2024:09:40:09 +0000] myfile - REST.PUT.OBJECT 4cfdfc1f58e762d3e116787cb92fac60
104+
testid fish [06/Aug/2024:09:40:28 +0000] myfile REST.DELETE.OBJECT 4cfdfc1f58e762d3e116787cb92fac60
105+
106+
107+
Standard
108+
````````
109+
based on `AWS Logging Record Format`_.
110+
111+
- bucket owner (or dash if empty)
112+
- bucket name (or dash if empty)
113+
- time
114+
- remote IP (not supported, always a dash)
115+
- user or account (or dash if empty)
116+
- request ID
117+
- operation in the following format: ``WEBSITE/REST.<HTTP method>.<resource>``
118+
- object key (or dash if empty)
119+
- request URI in the following format: ``"<HTTP method> <URI> <HTTP version>"``
120+
- HTTP status (or dash if zero). Note that in most cases log is written before the status is known
121+
- error code (or dash if empty)
122+
- bytes sent (or dash if zero)
123+
- object size (or dash if zero)
124+
- total time (not supported, always a dash)
125+
- turnaround time (not supported, always a dash)
126+
- referrer (not supported, always a dash)
127+
- user agent (not supported, always a dash)
128+
- version id (or dash if empty)
129+
- host id taken from "x-amz-id-2" (or dash if empty)
130+
- signature version (not supported, always a dash)
131+
- cipher suite (not supported, always a dash)
132+
- authentication type (not supported, always a dash)
133+
- host header (or dash if empty)
134+
- TLS version (not supported, always a dash)
135+
- access point ARN (not supported, always a dash)
136+
- ACL flag ("Yes" if the request is an ACL operation, otherwise dash)
137+
138+
For example:
139+
140+
::
141+
142+
testid fish [06/Aug/2024:09:30:25 +0000] - testid 9e369a15-5f43-4f07-b638-de920b22f91b.4179.15085270386962380710 REST.PUT.OBJECT myfile "PUT /fish/myfile HTTP/1.1" 200 - 512 512 - - - - - - - - - localhost - -
143+
testid fish [06/Aug/2024:09:30:51 +0000] - testid 9e369a15-5f43-4f07-b638-de920b22f91b.4179.7046073853138417766 REST.GET.OBJECT myfile "GET /fish/myfile HTTP/1.1" 200 - - 512 - - - - - - - - - localhost - -
144+
testid fish [06/Aug/2024:09:30:56 +0000] - testid 9e369a15-5f43-4f07-b638-de920b22f91b.4179.10723158448701085570 REST.DELETE.OBJECT myfile "DELETE /fish/myfile1 HTTP/1.1" 200 - - 512 - - - - - - - - - localhost - -
145+
146+
147+
.. _AWS Logging Record Format: https://docs.aws.amazon.com/AmazonS3/latest/userguide/LogFormat.html
148+
.. _Bucket Operations: ../s3/bucketops

‎doc/radosgw/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,3 +89,5 @@ Cluster with one API and then retrieve that data with the other API.
8989
Cloud Transition <cloud-transition>
9090
Metrics <metrics>
9191
UADK Acceleration for Compression <uadk-accel>
92+
Bucket Logging <bucket_logging>
93+

‎doc/radosgw/s3.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ The following table describes the support status for current Amazon S3 functiona
8282
+---------------------------------+-----------------+----------------------------------------+
8383
| **Storage Class** | Supported | See :ref:`storage_classes` |
8484
+---------------------------------+-----------------+----------------------------------------+
85+
| **Bucket Logging** | Supported | |
86+
+---------------------------------+-----------------+----------------------------------------+
8587

8688
Unsupported Header Fields
8789
-------------------------

‎doc/radosgw/s3/bucketops.rst‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -705,3 +705,192 @@ HTTP Response
705705
+---------------+-----------------------+----------------------------------------------------------+
706706

707707
.. _S3 Notification Compatibility: ../../s3-notification-compatibility
708+
709+
Enable Bucket Logging
710+
---------------------
711+
712+
Enable logging for a bucket.
713+
714+
Syntax
715+
~~~~~~
716+
717+
::
718+
719+
PUT /{bucket}?logging HTTP/1.1
720+
721+
722+
Request Entities
723+
~~~~~~~~~~~~~~~~
724+
725+
Parameters are XML encoded in the body of the request, in the following format:
726+
727+
::
728+
729+
<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
730+
<LoggingEnabled>
731+
<TargetBucket>string</TargetBucket>
732+
<TargetGrants>
733+
<Grant>
734+
<Grantee>
735+
<DisplayName>string</DisplayName>
736+
<EmailAddress>string</EmailAddress>
737+
<ID>string</ID>
738+
<xsi:type>string</xsi:type>
739+
<URI>string</URI>
740+
</Grantee>
741+
<Permission>string</Permission>
742+
</Grant>
743+
</TargetGrants>
744+
<TargetObjectKeyFormat>
745+
<PartitionedPrefix>
746+
<PartitionDateSource>DeliveryTime|EventTime</PartitionDateSource>
747+
</PartitionedPrefix>
748+
<SimplePrefix>
749+
</SimplePrefix>
750+
</TargetObjectKeyFormat>
751+
<TargetPrefix>string</TargetPrefix>
752+
<LoggingType>Standard|Journal</LoggingType>
753+
<ObjectRollTime>integer</ObjectRollTime>
754+
</LoggingEnabled>
755+
</BucketLoggingStatus>
756+
757+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
758+
| Name | Type | Description | Required |
759+
+===============================+===========+======================================================================================+==========+
760+
| ``BucketLoggingStatus`` | Container | Enabling/Disabling logging configuration for the bucket. | Yes |
761+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
762+
| ``LoggingEnabled`` | Container | Holding the logging configuration for the bucket. | Yes |
763+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
764+
| ``TargetBucket`` | String | The bucket where the logs are stored. The log bucket cannot have bucket logging | Yes |
765+
| | | enabled. | |
766+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
767+
| ``TargetGrants`` | Container | Not supported. The owner of the log bucket is the owner of the log objects. | No |
768+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
769+
| ``TargetObjectKeyFormat`` | Container | The format of the log object key. Contains either ``PartitionedPrefix`` or | No |
770+
| | | ``SimplePrefix`` entities. | |
771+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
772+
| ``PartitionedPrefix`` | Container | Indicates a partitioned log object key format. Note that ``PartitionDateSource`` | No |
773+
| | | is ignored and hardcoded as ``DeliveryTime`` | |
774+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
775+
| ``SimplePrefix`` | Container | Indicates a simple log object key format (default format) | No |
776+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
777+
| ``TargetPrefix`` | String | The prefix for the log objects. Used in both formats. May be used to distinguish | No |
778+
| | | between different source buckets writing log records to the same log bucket. | |
779+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
780+
| ``LoggingType`` | String | The type of logging. Valid values are: | No |
781+
| | | ``Standard`` (default) all bucket operations are logged after being perfomed. | |
782+
| | | The log record will contain all fields. | |
783+
| | | ``Journal`` only PUT, COPY, MULTI/DELETE and MPU operations are logged. | |
784+
| | | Will record the minimum subset of fields in the log record that is needed | |
785+
| | | for journaling. | |
786+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
787+
| ``ObjectRollTime`` | Integer | The time in seconds after which a new log object is created, and the previous log | No |
788+
| | | object added to the log bucket. Default is 3600 seconds (1 hour). | |
789+
+-------------------------------+-----------+--------------------------------------------------------------------------------------+----------+
790+
791+
792+
HTTP Response
793+
~~~~~~~~~~~~~
794+
795+
+---------------+-----------------------+----------------------------------------------------------+
796+
| HTTP Status | Status Code | Description |
797+
+===============+=======================+==========================================================+
798+
| ``400`` | MalformedXML | The XML is not well-formed |
799+
+---------------+-----------------------+----------------------------------------------------------+
800+
| ``400`` | InvalidArgument | Missing mandatory value or invalid value |
801+
+---------------+-----------------------+----------------------------------------------------------+
802+
| ``404`` | NoSuchBucket | The bucket does not exist |
803+
+---------------+-----------------------+----------------------------------------------------------+
804+
805+
806+
Disable Bucket Logging
807+
----------------------
808+
809+
Disable bucket logging from a bucket.
810+
811+
Syntax
812+
~~~~~~
813+
814+
::
815+
816+
PUT /{bucket}?logging HTTP/1.1
817+
818+
819+
Request Entities
820+
~~~~~~~~~~~~~~~~
821+
822+
Parameters are XML encoded in the body of the request, in the following format:
823+
824+
::
825+
826+
<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
827+
</BucketLoggingStatus>
828+
829+
830+
HTTP Response
831+
~~~~~~~~~~~~~
832+
833+
+---------------+-----------------------+----------------------------------------------------------+
834+
| HTTP Status | Status Code | Description |
835+
+===============+=======================+==========================================================+
836+
| ``404`` | NoSuchBucket | The bucket does not exist |
837+
+---------------+-----------------------+----------------------------------------------------------+
838+
839+
Get Bucket Logging
840+
------------------
841+
842+
Get logging configured on a bucket.
843+
844+
Syntax
845+
~~~~~~
846+
847+
::
848+
849+
GET /{bucket}?logging HTTP/1.1
850+
851+
852+
Response Entities
853+
~~~~~~~~~~~~~~~~~
854+
855+
Response is XML encoded in the body of the request, in the following format:
856+
857+
::
858+
859+
<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
860+
<LoggingEnabled>
861+
<TargetBucket>string</TargetBucket>
862+
<TargetGrants>
863+
<Grant>
864+
<Grantee>
865+
<DisplayName>string</DisplayName>
866+
<EmailAddress>string</EmailAddress>
867+
<ID>string</ID>
868+
<xsi:type>string</xsi:type>
869+
<URI>string</URI>
870+
</Grantee>
871+
<Permission>string</Permission>
872+
</Grant>
873+
</TargetGrants>
874+
<TargetObjectKeyFormat>
875+
<PartitionedPrefix>
876+
<PartitionDateSource>DeliveryTime|EventTime</PartitionDateSource>
877+
</PartitionedPrefix>
878+
<SimplePrefix>
879+
</SimplePrefix>
880+
</TargetObjectKeyFormat>
881+
<TargetPrefix>string</TargetPrefix>
882+
<LoggingType>Standard|Journal</LoggingType>
883+
<ObjectRollTime>integer</ObjectRollTime>
884+
</LoggingEnabled>
885+
</BucketLoggingStatus>
886+
887+
888+
HTTP Response
889+
~~~~~~~~~~~~~
890+
891+
+---------------+-----------------------+----------------------------------------------------------+
892+
| HTTP Status | Status Code | Description |
893+
+===============+=======================+==========================================================+
894+
| ``404`` | NoSuchBucket | The bucket does not exist |
895+
+---------------+-----------------------+----------------------------------------------------------+
896+

0 commit comments

Comments
 (0)