AWS services spec

specs/agents/tracing-instrumentation-aws.md

@@ -0,0 +1,63 @@
+## AWS services spans
+
+We describe how to instrument some of AWS' services in this document.
+Some of the services can use existing specs. When there are differences or additions, they have been noted below.
+
+### S3 (Simple Storage Service)
+
+AWS Simple Storage Service offers object storage via a REST API. The objects are organized into buckets, which are 
+themselves organized into regions.
+
+- `span.name`: The span name should follow this pattern: `S3 <OperationName> <bucket-name>`. For example,
+`S3 GetObject my-bucket`. Note that the operation name is in CamelCase.
+- `span.type`: `storage`
+- `span.subtype`: `s3`
+- `span.action`: The operation name in CamelCase. For example ‘GetObject’.
+
+#### Span context fields
+
+- **`context.destination.address`**: optional. Not available in some cases. Only set if the actual connection is available.
+- **`context.destination.port`**: optional. Not available in some cases. Only set if the actual connection is available.
+- **`context.destination.region`**: mandatory. The AWS region where the bucket is.
+- **`context.destination.service.name`**: mandatory. Use `s3`
+- **`context.destination.service.resource`**: optional. The bucket name, if available. The s3 API allows either the
+bucket name or an Access Point to be provided when referring to a bucket. Access Points can use either slashes or colons.
+When an Access Point is provided, the access point name preceded by `accesspoint/` or `accesspoint:` should be extracted.
+For example, given an Access Point such as `arn:aws:s3:us-west-2:123456789012:accesspoint/myendpointslashes`, the agent
+extracts `accesspoint/myendpointslashes`. Given an Access Point such as
+`arn:aws:s3:us-west-2:123456789012:accesspoint:myendpointcolons`, the agent extracts `accesspoint:myendpointcolons`.
+- **`context.destination.service.type`**: mandatory. Use `storage`.
+
+### DynamoDB
+
+AWS DynamoDB is a document database so instrumenting it will follow the [db spec](tracing-instrumentation-db.md).
+The follow specifications supersede those of the db spec.
+
+- **`span.name`**: The span name should capture the operation name in CamelCase and the table name, if available.
+The format should be `DynamoDB <ActionName> <TableName>`. So for example, `DynamoDB UpdateItem my_table`.
+
+#### Span context fields
+- **`context.db.instance`**: mandatory. The AWS region where the table is.
+- **`context.db.statement`**: optional. For a DynamoDB `Query` operation, capture the `KeyConditionExpression` in this field.
+- **`context.destination.cloud.region`**: mandatory. The AWS region where the table is, if available.
+
+### SQS (Simple Queue Service)
+
+AWS Simple Queue Service is a message queuing service. The [messaging spec](tracing-instrumentation-messaging.md) can 
+be used for instrumenting SQS, but the follow specifications supersede those of the messaging spec.
+
+- **`context.destination.cloud.region`**: mandatory. The AWS region where the queue is.
+
+For distributed tracing, the SQS API has "message attributes" that can be used in lieu of headers.
+
+### SNS (AWS Simple Notification Service)
+
+The AWS Simple Notification Service can be instrumented using the [messaging spec](tracing-instrumentation-messaging.md), 
+but the only action that is instrumented is `PUBLISH`. These specifications supersede those of the messaging spec: 
+
+- `span.name`: The span name should follow this pattern: `SNS PUBLISH <TOPIC-NAME>`. For example,
+`SNS PUBLISH MyTopic`.
+
+- **`context.destination.cloud.region`**: mandatory. The AWS region where the topic is.
+
+For distributed tracing, the SNS API has "message attributes" that can be used in lieu of headers.

specs/agents/tracing-instrumentation-db.md

@@ -2,7 +2,7 @@
 
 We capture spans for various types of database/data-stores operations, such as SQL queries, Elasticsearch queries, Redis commands, etc. We follow some of the same conventions defined by OpenTracing for capturing database-specific span context, including:
 
- - `db.instance`: database instance name, e.g. "customers"
+ - `db.instance`: database instance name, e.g. "customers". For DynamoDB, this is the region.
  - `db.statement`: statement/query, e.g. "SELECT * FROM foo"
  - `db.user`: username used for database access, e.g. "readonly_user"
  - `db.type`: database type/category, which should be "sql" for SQL databases, and the lower-cased database name otherwise.