diff --git a/specs/agents/tracing-instrumentation-aws.md b/specs/agents/tracing-instrumentation-aws.md new file mode 100644 index 00000000..c42d6043 --- /dev/null +++ b/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 `. 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 `. 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 `. 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. diff --git a/specs/agents/tracing-instrumentation-db.md b/specs/agents/tracing-instrumentation-db.md index a934faee..0d19a4c3 100644 --- a/specs/agents/tracing-instrumentation-db.md +++ b/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.