aws-sdk.yml

groups:
  - id: aws
    prefix: aws
    type: span
    brief: >
      The `aws` conventions apply to operations using the AWS SDK. They map request or response parameters
      in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based
      on feedback from AWS users of tracing and will continue to evolve as new interesting conventions
      are found.

      Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on
      these APIs.
    attributes:
      - ref: rpc.system
        brief: "The value `aws-api`."
        requirement_level: required
        examples:
          - aws-api
      - ref: rpc.service
        brief: "The name of the service to which a request is made, as returned by the AWS SDK."
        examples:
          - DynamoDB
          - S3
      - ref: rpc.method
        brief: "The name of the operation corresponding to the request, as returned by the AWS SDK"
        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
    brief: "Attributes always filled for all DynamoDB request types."
    attributes:
      - ref: db.system
        brief: "The value `dynamodb`."
        requirement_level: required
        examples:
          - dynamodb

  - id: dynamodb.shared
    extends: aws
    prefix: aws.dynamodb
    type: span
    brief: "Attributes that exist for multiple DynamoDB request types."
    attributes:
      - ref: db.operation
        brief: "The same value as `rpc.method`."
        examples:
          - GetItem
          - PutItem
      - id: table_names
        type: string[]
        brief: The keys in the `RequestItems` object field.
        examples:
          - Users
          - Cats
      - id: consumed_capacity
        type: string[]
        brief: "The JSON-serialized value of each item in the `ConsumedCapacity` response field."
        examples:
          - '{
              "CapacityUnits": number,
              "GlobalSecondaryIndexes": {
                 "string" : {
                    "CapacityUnits": number,
                    "ReadCapacityUnits": number,
                    "WriteCapacityUnits": number
                 }
              },
              "LocalSecondaryIndexes": {
                 "string" : {
                    "CapacityUnits": number,
                    "ReadCapacityUnits": number,
                    "WriteCapacityUnits": number
                 }
              },
              "ReadCapacityUnits": number,
              "Table": {
                 "CapacityUnits": number,
                 "ReadCapacityUnits": number,
                 "WriteCapacityUnits": number
              },
              "TableName": "string",
              "WriteCapacityUnits": number
            }'
      - id: item_collection_metrics
        type: string
        brief: "The JSON-serialized value of the `ItemCollectionMetrics` response field."
        examples:
          - '{
              "string" : [
                 {
                    "ItemCollectionKey": {
                       "string" : {
                          "B": blob,
                          "BOOL": boolean,
                          "BS": [ blob ],
                          "L": [
                             "AttributeValue"
                          ],
                          "M": {
                             "string" : "AttributeValue"
                          },
                          "N": "string",
                          "NS": [ "string" ],
                          "NULL": boolean,
                          "S": "string",
                          "SS": [ "string" ]
                       }
                    },
                    "SizeEstimateRangeGB": [ number ]
                 }
              ]
             }'
      - id: provisioned_read_capacity
        type: double
        brief: "The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter."
        examples:
          - 1.0
          - 2.0
      - id: provisioned_write_capacity
        type: double
        brief: "The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter."
        examples:
          - 1.0
          - 2.0
      - id: consistent_read
        type: boolean
        brief: "The value of the `ConsistentRead` request parameter."
      - id: projection
        type: string
        brief: "The value of the `ProjectionExpression` request parameter."
        examples:
          - Title
          - Title, Price, Color
          - Title, Description, RelatedItems, ProductReviews
      - id: limit
        type: int
        brief: "The value of the `Limit` request parameter."
        examples:
          - 10
      - id: attributes_to_get
        type: string[]
        brief: "The value of the `AttributesToGet` request parameter."
        examples:
          - lives
          - id
      - id: index_name
        type: string
        brief: "The value of the `IndexName` request parameter."
        examples:
          - name_to_group
      - id: select
        type: string
        brief: "The value of the `Select` request parameter."
        examples:
          - ALL_ATTRIBUTES
          - COUNT

  - id: dynamodb.batchgetitem
    brief: DynamoDB.BatchGetItem
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
      - ref: aws.dynamodb.consumed_capacity

  - id: dynamodb.batchwriteitem
    brief: DynamoDB.BatchWriteItem
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.item_collection_metrics

  - id: dynamodb.createtable
    brief: DynamoDB.CreateTable
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - id: global_secondary_indexes
        type: string[]
        brief: "The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field"
        examples:
          - '{
              "IndexName": "string",
              "KeySchema": [
                {
                  "AttributeName": "string",
                  "KeyType": "string"
                }
              ],
              "Projection": {
                "NonKeyAttributes": [ "string" ],
                "ProjectionType": "string"
              },
              "ProvisionedThroughput": {
                "ReadCapacityUnits": number,
                "WriteCapacityUnits": number
              }
            }'
      - id: local_secondary_indexes
        type: string[]
        brief: "The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field."
        examples:
          - '{
              "IndexArn": "string",
              "IndexName": "string",
              "IndexSizeBytes": number,
              "ItemCount": number,
              "KeySchema": [
                {
                  "AttributeName": "string",
                  "KeyType": "string"
                }
              ],
              "Projection": {
                "NonKeyAttributes": [ "string" ],
                "ProjectionType": "string"
              }
            }'
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.item_collection_metrics
      - ref: aws.dynamodb.provisioned_read_capacity
      - ref: aws.dynamodb.provisioned_write_capacity

  - id: dynamodb.deleteitem
    brief: DynamoDB.DeleteItem
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.item_collection_metrics

  - id: dynamodb.deletetable
    brief: DynamoDB.DeleteTable
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users

  - id: dynamodb.describetable
    brief: DynamoDB.DescribeTable
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users

  - id: dynamodb.getitem
    brief: DynamoDB.GetItem
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.consistent_read
      - ref: aws.dynamodb.projection

  - id: dynamodb.listtables
    brief: DynamoDB.ListTables
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - id: exclusive_start_table
        type: string
        brief: "The value of the `ExclusiveStartTableName` request parameter."
        examples:
          - Users
          - CatsTable
      - id: table_count
        type: int
        brief: "The the number of items in the `TableNames` response parameter."
        examples:
          - 20
      - ref: aws.dynamodb.limit

  - id: dynamodb.putitem
    brief: DynamoDB.PutItem
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.item_collection_metrics

  - id: dynamodb.query
    brief: DynamoDB.Query
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - id: scan_forward
        type: boolean
        brief: "The value of the `ScanIndexForward` request parameter."
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.consistent_read
      - ref: aws.dynamodb.limit
      - ref: aws.dynamodb.projection
      - ref: aws.dynamodb.attributes_to_get
      - ref: aws.dynamodb.index_name
      - ref: aws.dynamodb.select

  - id: dynamodb.scan
    brief: DynamoDB.Scan
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - id: segment
        type: int
        brief: "The value of the `Segment` request parameter."
        examples:
          - 10
      - id: total_segments
        type: int
        brief: "The value of the `TotalSegments` request parameter."
        examples:
          - 100
      - id: count
        type: int
        brief: "The value of the `Count` response parameter."
        examples:
          - 10
      - id: scanned_count
        type: int
        brief: "The value of the `ScannedCount` response parameter."
        examples:
          - 50
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.consistent_read
      - ref: aws.dynamodb.limit
      - ref: aws.dynamodb.projection
      - ref: aws.dynamodb.attributes_to_get
      - ref: aws.dynamodb.index_name
      - ref: aws.dynamodb.select

  - id: dynamodb.updateitem
    brief: DynamoDB.UpdateItem
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users
      - ref: aws.dynamodb.consumed_capacity
      - ref: aws.dynamodb.item_collection_metrics

  - id: dynamodb.updatetable
    brief: DynamoDB.UpdateTable
    extends: aws
    prefix: aws.dynamodb
    type: span
    attributes:
      - id: attribute_definitions
        type: string[]
        brief: "The JSON-serialized value of each item in the `AttributeDefinitions` request field."
        examples:
          - '{
              "AttributeName": "string",
              "AttributeType": "string"
             }'
      - id: global_secondary_index_updates
        type: string[]
        brief: "The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field."
        examples:
          - '{
              "Create": {
                "IndexName": "string",
                "KeySchema": [
                  {
                    "AttributeName": "string",
                    "KeyType": "string"
                  }
                ],
                "Projection": {
                  "NonKeyAttributes": [ "string" ],
                  "ProjectionType": "string"
                },
                "ProvisionedThroughput": {
                  "ReadCapacityUnits": number,
                  "WriteCapacityUnits": number
                }
              }'
      - ref: aws.dynamodb.table_names
        brief: "A single-element array with the value of the TableName request parameter."
        examples:
          - Users
      - 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).