Added AWS S3 semantic conventions (#3251)

open-telemetry · Mar 22, 2023 · 05cd8e0 · 05cd8e0
1 parent ed611c4
commit 05cd8e0
Show file tree

Hide file tree

Showing 2 changed files with 149 additions and 0 deletions.
diff --git a/semantic_conventions/trace/instrumentation/aws-sdk.yml b/semantic_conventions/trace/instrumentation/aws-sdk.yml
@@ -26,6 +26,12 @@ groups:
         examples:
           - GetItem
           - PutItem
+      - id: request_id
+        type: string
+        brief: "The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`."
+        examples:
+          - 79b9da39-b7ae-508a-a6bc-864b2829c622
+          - C9ER4AJX75574TDJ
 
   - id: dynamodb.all
     type: span
@@ -425,3 +431,86 @@ groups:
       - ref: aws.dynamodb.consumed_capacity
       - ref: aws.dynamodb.provisioned_read_capacity
       - ref: aws.dynamodb.provisioned_write_capacity
+
+  - id: aws.s3
+    extends: aws
+    prefix: aws.s3
+    type: span
+    brief: "Attributes that exist for S3 request types."
+    attributes:
+      - id: bucket
+        type: string
+        brief: "The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations."
+        examples:
+          - some-bucket-name
+        note: |
+            The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
+            This applies to almost all S3 operations except `list-buckets`.
+      - id: key
+        type: string
+        brief: "The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations."
+        examples:
+          - someFile.yml
+        note: |
+            The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
+            This applies in particular to the following operations:
+
+            - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
+            - [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html)
+            - [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html)
+            - [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html)
+            - [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html)
+            - [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html)
+            - [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html)
+            - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
+            - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
+            - [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html)
+            - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
+            - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+            - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
+      - id: copy_source
+        type: string
+        brief: "The source object (in the form `bucket`/`key`) for the copy operation."
+        examples:
+          - someFile.yml
+        note: |
+            The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
+            of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html).
+            This applies in particular to the following operations:
+
+            - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
+            - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
+      - id: upload_id
+        type: string
+        brief: "Upload ID that identifies the multipart upload."
+        examples:
+          - 'dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ'
+        note: |
+            The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
+            of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations.
+            This applies in particular to the following operations:
+
+            - [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
+            - [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
+            - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
+            - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+            - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
+      - id: delete
+        type: string
+        brief: "The delete request container that specifies the objects to be deleted."
+        examples:
+          - 'Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean'
+        note: |
+            The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
+            The `delete` attribute corresponds to the `--delete` parameter of the
+            [delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html).
+      - id: part_number
+        type: int
+        brief: "The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000."
+        examples:
+          - 3456
+        note: |
+            The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+            and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations.
+            The `part_number` attribute corresponds to the `--part-number` parameter of the
+            [upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html).
diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md
@@ -18,6 +18,7 @@ with the naming guidelines for RPC client spans.
 <!-- semconv aws -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
+| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | Recommended |
 | [`rpc.method`](../rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended |
 | [`rpc.service`](../rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended |
 | [`rpc.system`](../rpc.md) | string | The value `aws-api`. | `aws-api` | Required |
@@ -186,3 +187,62 @@ These attributes are filled in for all DynamoDB request types.
 | `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended |
 | `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended |
 <!-- endsemconv -->
+
+## S3
+
+<!-- semconv aws.s3 -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `aws.s3.bucket` | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | Recommended |
+| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [2] | `someFile.yml` | Recommended |
+| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [3] | `someFile.yml` | Recommended |
+| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [4] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | Recommended |
+| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [5] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | Recommended |
+| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [6] | `3456` | Recommended |
+
+**[1]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
+This applies to almost all S3 operations except `list-buckets`.
+
+**[2]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter.
+This applies in particular to the following operations:
+
+- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
+- [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html)
+- [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html)
+- [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html)
+- [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html)
+- [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html)
+- [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html)
+- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
+- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
+- [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html)
+- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
+- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
+
+**[3]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter
+of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html).
+This applies in particular to the following operations:
+
+- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html)
+- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
+
+**[4]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter
+of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations.
+This applies in particular to the following operations:
+
+- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html)
+- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html)
+- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html)
+- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html)
+
+**[5]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation.
+The `delete` attribute corresponds to the `--delete` parameter of the
+[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html).
+
+**[6]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html)
+and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations.
+The `part_number` attribute corresponds to the `--part-number` parameter of the
+[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html).
+<!-- endsemconv -->