AWS SDK common and dynamodb conventions

semantic_conventions/README.md

@@ -4,10 +4,14 @@ The YAML descriptions of semantic convention contained in this directory are int
 be used by the various OpenTelemetry language implementations to aid in automatic
 generation of semantics-related code.
 
+## Writing semantic conventions
+
+Refer to the [syntax](./syntax.md) for how to write the YAML files for semantic conventions.
+
 ## Generation
 
 These YAML files are used by the make target `table-generation` to generate consistently
-formattted Markdown tables for all semantic conventions in the specification. Run it from the root of this repository using the command
+formatted Markdown tables for all semantic conventions in the specification. Run it from the root of this repository using the command
 
 ```
 make table-generation

semantic_conventions/trace/instrumentation/aws-sdk.yml

@@ -0,0 +1,373 @@
+groups:
+  - id: aws
+    prefix: aws
+    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:
+      - id: service
+        type: string
+        brief: "The name of the service to which a request is made, as returned by the AWS SDK."
+        examples:
+          - DynamoDB
+          - S3
+      - id: operation
+        type: string
+        brief: "The name of the operation corresponding to the request, as returned by the AWS SDK"
+        examples:
+          - GetItem
+          - PutItem
+
+  - id: dynamodb.shared
+    extends: aws
+    prefix: aws.dynamodb
+    brief: "Attributes that exist for multiple DynamoDB request types."
+    attributes:
+      - id: table_names
+        type: string[]
+        brief: The keys in the `RequestItems` object field in a request operating on multiple tables.
+        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_throughput.read_capacity_units
+        type: number
+        brief: "The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter."
+        examples:
+          - 1
+          - 2
+      - id: provisioned_throughput.write_capacity_units
+        type: number
+        brief: "The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter."
+        examples:
+          - 1
+          - 2
+      - id: consistent_read
+        type: boolean
+        brief: "The value of the `ConsistentRead` request parameter."
+      - id: projection_expression
+        type: string
+        brief: "The value of the `ProjectionExpression` request parameter."
+        examples:
+          - Title
+          - Title, Price, Color
+          - Title, Description, RelatedItems, ProductReviews
+      - id: limit
+        type: number
+        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
+    attributes:
+      - ref: aws.dynamodb.table_names
+      - ref: aws.dynamodb.consumed_capacity
+
+  - id: dynamodb.batchwriteitem
+    brief: DynamoDB.BatchWriteItem
+    extends: aws
+    prefix: aws.dynamodb
+    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
+    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
+      - ref: aws.dynamodb.consumed_capacity
+      - ref: aws.dynamodb.item_collection_metrics
+      - ref: aws.dynamodb.provisioned_throughput.read_capacity_units
+      - ref: aws.dynamodb.provisioned_throughput.write_capacity_units
+
+  - id: dynamodb.deleteitem
+    brief: DynamoDB.DeleteItem
+    extends: aws
+    prefix: aws.dynamodb
+    attributes:
+      - ref: aws.dynamodb.table_names
+      - ref: aws.dynamodb.consumed_capacity
+      - ref: aws.dynamodb.item_collection_metrics
+
+  - id: dynamodb.deletetable
+    brief: DynamoDB.DeleteTable
+    extends: aws
+    prefix: aws.dynamodb
+    attributes:
+      - ref: db.name
+        brief: "The value of the TableName request parameter."
+
+  - id: dynamodb.describetable
+    brief: DynamoDB.DescribeTable
+    extends: aws
+    prefix: aws.dynamodb
+    attributes:
+      - ref: db.name
+        brief: "The value of the TableName request parameter."
+
+  - id: dynamodb.getitem
+    brief: DynamoDB.GetItem
+    extends: aws
+    prefix: aws.dynamodb
+    attributes:
+      - ref: db.name
+        brief: "The value of the TableName request parameter."
+      - ref: aws.dynamodb.consumed_capacity
+      - ref: aws.dynamodb.consistent_read
+      - ref: aws.dynamodb.projection_expression
+
+  - id: dynamodb.listtables
+    brief: DynamoDB.ListTables
+    extends: aws
+    prefix: aws.dynamodb
+    attributes:
+      - id: exclusive_start_table_name
+        type: string
+        brief: "The value of the `ExclusiveStartTableName` request parameter."
+        examples:
+          - Users
+          - CatsTable
+      - id: table_count
+        type: number
+        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
+    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
+    attributes:
+      - id: scan_index_forward
+        type: boolean
+        brief: "The value of the `ScanIndexForward` request parameter."
+      - ref: db.name
+        brief: "The value of the TableName request parameter."
+      - ref: aws.dynamodb.consumed_capacity
+      - ref: aws.dynamodb.consistent_read
+      - ref: aws.dynamodb.limit
+      - ref: aws.dynamodb.projection_expression
+      - 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
+    attributes:
+      - id: segment
+        type: number
+        brief: "The value of the `Segment` request parameter."
+        examples:
+          - 10
+      - id: total_segments
+        type: number
+        brief: "The value of the `TotalSegments` request parameter."
+        examples:
+          - 100
+      - id: count
+        type: number
+        brief: "The value of the `Count` response parameter."
+        examples:
+          - 10
+      - id: scanned_count
+        type: number
+        brief: "The value of the `ScannedCount` response parameter."
+        examples:
+          - 50
+      - ref: db.name
+        brief: "The value of the TableName request parameter."
+      - ref: aws.dynamodb.consumed_capacity
+      - ref: aws.dynamodb.consistent_read
+      - ref: aws.dynamodb.limit
+      - ref: aws.dynamodb.projection_expression
+      - 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
+    attributes:
+      - ref: aws.dynamodb.table_names
+      - ref: aws.dynamodb.consumed_capacity
+      - ref: aws.dynamodb.item_collection_metrics
+
+  - id: dynamodb.updatetable
+    brief: DynamoDB.UpdateTable
+    extends: aws
+    prefix: aws.dynamodb
+    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: db.name
+        brief: "The value of the TableName request parameter."
+      - ref: aws.dynamodb.consumed_capacity
+      - ref: aws.dynamodb.provisioned_throughput.read_capacity_units
+      - ref: aws.dynamodb.provisioned_throughput.write_capacity_units