refactor(instr-aws-sdk): use exported strings for attributes (#2142)

* refactor(instr-aws-sdk): use exported strings for attributes * update SpanAttributes to Attributes * add semantic conventions to readme
open-telemetry · Apr 24, 2024 · 931318c · 931318c
1 parent 77452c1
commit 931318c
Show file tree

Hide file tree

Showing 17 changed files with 460 additions and 441 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/plugins/node/opentelemetry-instrumentation-aws-lambda/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-aws-lambda/src/instrumentation.ts
@@ -44,8 +44,9 @@ import {
   AWSXRayPropagator,
 } from '@opentelemetry/propagator-aws-xray';
 import {
-  SemanticAttributes,
-  SemanticResourceAttributes,
+  SEMATTRS_FAAS_EXECUTION,
+  SEMRESATTRS_CLOUD_ACCOUNT_ID,
+  SEMRESATTRS_FAAS_ID,
 } from '@opentelemetry/semantic-conventions';
 
 import {
@@ -201,9 +202,9 @@ export class AwsLambdaInstrumentation extends InstrumentationBase {
         {
           kind: SpanKind.SERVER,
           attributes: {
-            [SemanticAttributes.FAAS_EXECUTION]: context.awsRequestId,
-            [SemanticResourceAttributes.FAAS_ID]: context.invokedFunctionArn,
-            [SemanticResourceAttributes.CLOUD_ACCOUNT_ID]:
+            [SEMATTRS_FAAS_EXECUTION]: context.awsRequestId,
+            [SEMRESATTRS_FAAS_ID]: context.invokedFunctionArn,
+            [SEMRESATTRS_CLOUD_ACCOUNT_ID]:
               AwsLambdaInstrumentation._extractAccountId(
                 context.invokedFunctionArn
               ),

diff --git a/...ns/node/opentelemetry-instrumentation-aws-lambda/test/integrations/lambda-handler.test.ts b/...ns/node/opentelemetry-instrumentation-aws-lambda/test/integrations/lambda-handler.test.ts
@@ -33,8 +33,9 @@ import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import { Context } from 'aws-lambda';
 import * as assert from 'assert';
 import {
-  SemanticAttributes,
-  SemanticResourceAttributes,
+  SEMATTRS_EXCEPTION_MESSAGE,
+  SEMATTRS_FAAS_EXECUTION,
+  SEMRESATTRS_FAAS_NAME,
 } from '@opentelemetry/semantic-conventions';
 import {
   Context as OtelContext,
@@ -56,7 +57,7 @@ const assertSpanSuccess = (span: ReadableSpan) => {
   assert.strictEqual(span.kind, SpanKind.SERVER);
   assert.strictEqual(span.name, 'my_function');
   assert.strictEqual(
-    span.attributes[SemanticAttributes.FAAS_EXECUTION],
+    span.attributes[SEMATTRS_FAAS_EXECUTION],
     'aws_request_id'
   );
   assert.strictEqual(span.attributes['faas.id'], 'my_arn');
@@ -68,15 +69,15 @@ const assertSpanFailure = (span: ReadableSpan) => {
   assert.strictEqual(span.kind, SpanKind.SERVER);
   assert.strictEqual(span.name, 'my_function');
   assert.strictEqual(
-    span.attributes[SemanticAttributes.FAAS_EXECUTION],
+    span.attributes[SEMATTRS_FAAS_EXECUTION],
     'aws_request_id'
   );
   assert.strictEqual(span.attributes['faas.id'], 'my_arn');
   assert.strictEqual(span.status.code, SpanStatusCode.ERROR);
   assert.strictEqual(span.status.message, 'handler error');
   assert.strictEqual(span.events.length, 1);
   assert.strictEqual(
-    span.events[0].attributes![SemanticAttributes.EXCEPTION_MESSAGE],
+    span.events[0].attributes![SEMATTRS_EXCEPTION_MESSAGE],
     'handler error'
   );
 };
@@ -841,10 +842,7 @@ describe('lambda handler', () => {
       it('sync - success', async () => {
         initializeHandler('lambda-test/async.handler', {
           requestHook: (span, { context }) => {
-            span.setAttribute(
-              SemanticResourceAttributes.FAAS_NAME,
-              context.functionName
-            );
+            span.setAttribute(SEMRESATTRS_FAAS_NAME, context.functionName);
           },
         });
 
@@ -853,7 +851,7 @@ describe('lambda handler', () => {
         const [span] = spans;
         assert.strictEqual(spans.length, 1);
         assert.strictEqual(
-          span.attributes[SemanticResourceAttributes.FAAS_NAME],
+          span.attributes[SEMRESATTRS_FAAS_NAME],
           ctx.functionName
         );
         assertSpanSuccess(span);

diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/README.md b/plugins/node/opentelemetry-instrumentation-aws-sdk/README.md
@@ -117,6 +117,54 @@ The instrumentation's config `preRequestHook`, `responseHook` and `sqsProcessHoo
 
 The `moduleVersionAttributeName` config option is removed. To add the aws-sdk package version to spans, use the `moduleVersion` attribute in hook info for `preRequestHook` and `responseHook` functions.
 
+## Semantic Conventions
+
+This package uses `@opentelemetry/semantic-conventions` version `1.22+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md)
+
+Attributes collected:
+
+| Attribute                                     | Short Description                                                                              | Service  |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------- |
+| `http.status_code`                            | (aws-sdk) HTTP response status code.                                                           |          |
+| `rpc.method`                                  | The name of the (logical) method being called.                                                 |          |
+| `rpc.service`                                 | The full (logical) name of the service being called.                                           |          |
+| `rpc.system`                                  | A string identifying the remoting system.                                                      |          |
+| `aws.dynamodb.attribute_definitions`          | The JSON-serialized value of each item in the `AttributeDefinitions` request field.            | dynamodb |
+| `aws.dynamodb.consistent_read`                | The value of the `ConsistentRead` request parameter.                                           | dynamodb |
+| `aws.dynamodb.consumed_capacity`              | The JSON-serialized value of each item in the `ConsumedCapacity` response field.               | dynamodb |
+| `aws.dynamodb.count`                          | The value of the `Count` response parameter.                                                   | dynamodb |
+| `aws.dynamodb.exclusive_start_table`          | The value of the `ExclusiveStartTableName` request parameter.                                  | dynamodb |
+| `aws.dynamodb.global_secondary_index_updates` | The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. | dynamodb |
+| `aws.dynamodb.global_secondary_indexes`       | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field.          | dynamodb |
+| `aws.dynamodb.index_name`                     | The value of the `IndexName` request parameter.                                                | dynamodb |
+| `aws.dynamodb.item_collection_metrics`        | The JSON-serialized value of the `ItemCollectionMetrics` response field.                       | dynamodb |
+| `aws.dynamodb.limit`                          | The value of the `Limit` request parameter.                                                    | dynamodb |
+| `aws.dynamodb.local_secondary_indexes`        | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field.           | dynamodb |
+| `aws.dynamodb.projection`                     | The value of the `ProjectionExpression` request parameter.                                     | dynamodb |
+| `aws.dynamodb.provisioned_read_capacity`      | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter.                  | dynamodb |
+| `aws.dynamodb.provisioned_write_capacity`     | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter.                 | dynamodb |
+| `aws.dynamodb.scan_forward`                   | The value of the `ScanIndexForward` request parameter.                                         | dynamodb |
+| `aws.dynamodb.scanned_count`                  | The value of the `ScannedCount` response parameter.                                            | dynamodb |
+| `aws.dynamodb.segment`                        | The value of the `Segment` request parameter.                                                  | dynamodb |
+| `aws.dynamodb.select`                         | The value of the `Select` request parameter.                                                   | dynamodb |
+| `aws.dynamodb.table_count`                    | The number of items in the `TableNames` response parameter.                                    | dynamodb |
+| `aws.dynamodb.table_names`                    | The keys in the `RequestItems` object field.                                                   | dynamodb |
+| `aws.dynamodb.total_segments`                 | The value of the `TotalSegments` request parameter.                                            | dynamodb |
+| `db.name`                                     | The name of the database being accessed.                                                       | dynamodb |
+| `db.operation`                                | The name of the operation being executed.                                                      | dynamodb |
+| `db.statement`                                | The database statement being executed.                                                         | dynamodb |
+| `db.system`                                   | An identifier for the database management system (DBMS) product being used.                    | dynamodb |
+| `faas.execution`                              | The execution ID of the current function execution.                                            | lambda   |
+| `faas.invoked_name`                           | The name of the invoked function.                                                              | lambda   |
+| `faas.invoked_provider`                       | The cloud provider of the invoked function.                                                    | lambda   |
+| `faas.invoked_region`                         | The cloud region of the invoked function.                                                      | lambda   |
+| `messaging.destination`                       | The message destination name.                                                                  | sns, sqs |
+| `messaging.destination_kind`                  | The kind of message destination.                                                               | sns, sqs |
+| `messaging.system`                            | A string identifying the messaging system.                                                     | sns, sqs |
+| `messaging.operation`                         | A string identifying the kind of message consumption.                                          | sqs      |
+| `messaging.message_id`                        | A value used by the messaging system as an identifier for the message.                         | sqs      |
+| `messaging.url`                               | The connection string.                                                                         | sqs      |
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/package.json b/plugins/node/opentelemetry-instrumentation-aws-sdk/package.json
@@ -47,7 +47,7 @@
     "@opentelemetry/core": "^1.8.0",
     "@opentelemetry/instrumentation": "^0.50.0",
     "@opentelemetry/propagation-utils": "^0.30.8",
-    "@opentelemetry/semantic-conventions": "^1.0.0"
+    "@opentelemetry/semantic-conventions": "^1.22.0"
   },
   "devDependencies": {
     "@aws-sdk/client-dynamodb": "3.85.0",

diff --git a/plugins/node/opentelemetry-instrumentation-aws-sdk/src/aws-sdk.ts b/plugins/node/opentelemetry-instrumentation-aws-sdk/src/aws-sdk.ts
@@ -58,7 +58,7 @@ import {
 } from './utils';
 import { propwrap } from './propwrap';
 import { RequestMetadata } from './services/ServiceExtension';
-import { SemanticAttributes } from '@opentelemetry/semantic-conventions';
+import { SEMATTRS_HTTP_STATUS_CODE } from '@opentelemetry/semantic-conventions';
 
 const V3_CLIENT_CONFIG_KEY = Symbol(
   'opentelemetry.instrumentation.aws-sdk.client.config'
@@ -369,10 +369,7 @@ export class AwsInstrumentation extends InstrumentationBase<any> {
 
         const httpStatusCode = response.httpResponse?.statusCode;
         if (httpStatusCode) {
-          span.setAttribute(
-            SemanticAttributes.HTTP_STATUS_CODE,
-            httpStatusCode
-          );
+          span.setAttribute(SEMATTRS_HTTP_STATUS_CODE, httpStatusCode);
         }
         span.end();
       });
@@ -526,7 +523,7 @@ export class AwsInstrumentation extends InstrumentationBase<any> {
                     response.output?.$metadata?.httpStatusCode;
                   if (httpStatusCode) {
                     span.setAttribute(
-                      SemanticAttributes.HTTP_STATUS_CODE,
+                      SEMATTRS_HTTP_STATUS_CODE,
                       httpStatusCode
                     );
                   }