chore(instrumentation-aws-lambda): update semconv usage to ATTR_ exports (#3049)

Refs: #2377

Author: trentm

packages/instrumentation-aws-lambda/src/instrumentation.ts

@@ -39,13 +39,9 @@ import {
   ROOT_CONTEXT,
   Attributes,
 } from '@opentelemetry/api';
-import {
-  ATTR_URL_FULL,
-  SEMATTRS_FAAS_EXECUTION,
-  SEMRESATTRS_CLOUD_ACCOUNT_ID,
-  SEMRESATTRS_FAAS_ID,
-} from '@opentelemetry/semantic-conventions';
-import { ATTR_FAAS_COLDSTART } from './semconv';
+import { ATTR_URL_FULL } from '@opentelemetry/semantic-conventions';
+import { ATTR_CLOUD_ACCOUNT_ID, ATTR_FAAS_COLDSTART } from './semconv';
+import { ATTR_FAAS_EXECUTION, ATTR_FAAS_ID } from './semconv-obsolete';
 
 import {
   APIGatewayProxyEventHeaders,
@@ -239,12 +235,11 @@ export class AwsLambdaInstrumentation extends InstrumentationBase<AwsLambdaInstr
         {
           kind: SpanKind.SERVER,
           attributes: {
-            [SEMATTRS_FAAS_EXECUTION]: context.awsRequestId,
-            [SEMRESATTRS_FAAS_ID]: context.invokedFunctionArn,
-            [SEMRESATTRS_CLOUD_ACCOUNT_ID]:
-              AwsLambdaInstrumentation._extractAccountId(
-                context.invokedFunctionArn
-              ),
+            [ATTR_FAAS_EXECUTION]: context.awsRequestId,
+            [ATTR_FAAS_ID]: context.invokedFunctionArn,
+            [ATTR_CLOUD_ACCOUNT_ID]: AwsLambdaInstrumentation._extractAccountId(
+              context.invokedFunctionArn
+            ),
             [ATTR_FAAS_COLDSTART]: requestIsColdStart,
             ...AwsLambdaInstrumentation._extractOtherEventFields(event),
           },

packages/instrumentation-aws-lambda/src/semconv-obsolete.ts

@@ -0,0 +1,53 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * This file contains constants for values that where replaced/removed from
+ * Semantic Conventions long enough ago that they do not have `ATTR_*`
+ * constants in the `@opentelemetry/semantic-conventions` package. Eventually
+ * it is expected that this instrumention will be updated to emit telemetry
+ * using modern Semantic Conventions, dropping the need for the constants in
+ * this file.
+ */
+
+/**
+ * The execution ID of the current function execution.
+ *
+ * @deprecated Use ATTR_FAAS_INVOCATION_ID in [incubating entry-point]({@link https://github.com/open-telemetry/opentelemetry-js/blob/main/semantic-conventions/README.md#unstable-semconv}).
+ */
+export const ATTR_FAAS_EXECUTION = 'faas.execution' as const;
+
+/**
+* The unique ID of the single function that this runtime instance executes.
+*
+* Note: Depending on the cloud provider, use:
+
+* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
+Take care not to use the "invoked ARN" directly but replace any
+[alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) with the resolved function version, as the same runtime instance may be invokable with multiple
+different aliases.
+* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names)
+* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id).
+
+On some providers, it may not be possible to determine the full ID at startup,
+which is why this field cannot be made required. For example, on AWS the account ID
+part of the ARN is not available without calling another AWS API
+which may be deemed too slow for a short-running lambda function.
+As an alternative, consider setting `faas.id` as a span attribute instead.
+*
+* @deprecated Use ATTR_CLOUD_RESOURCE_ID in [incubating entry-point]({@link https://github.com/open-telemetry/opentelemetry-js/blob/main/semantic-conventions/README.md#unstable-semconv}).
+*/
+export const ATTR_FAAS_ID = 'faas.id' as const;

packages/instrumentation-aws-lambda/src/semconv.ts

@@ -20,9 +20,46 @@
  * @see https://github.com/open-telemetry/opentelemetry-js/tree/main/semantic-conventions#unstable-semconv
  */
 
+/**
+ * The cloud account ID the resource is assigned to.
+ *
+ * @example 111111111111
+ * @example opentelemetry
+ *
+ * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const ATTR_CLOUD_ACCOUNT_ID = 'cloud.account.id' as const;
+
 /**
  * A boolean that is true if the serverless function is executed for the first time (aka cold-start).
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_FAAS_COLDSTART = 'faas.coldstart';
+export const ATTR_FAAS_COLDSTART = 'faas.coldstart' as const;
+
+/**
+ * The name of the single function that this runtime instance executes.
+ *
+ * @example my-function
+ * @example myazurefunctionapp/some-function-name
+ *
+ * @note This is the name of the function as configured/deployed on the FaaS
+ * platform and is usually different from the name of the callback
+ * function (which may be stored in the
+ * [`code.namespace`/`code.function.name`](/docs/general/attributes.md#source-code-attributes)
+ * span attributes).
+ *
+ * For some cloud providers, the above definition is ambiguous. The following
+ * definition of function name **MUST** be used for this attribute
+ * (and consequently the span name) for the listed cloud providers/products:
+ *
+ *   - **Azure:**  The full name `<FUNCAPP>/<FUNC>`, i.e., function app name
+ *     followed by a forward slash followed by the function name (this form
+ *     can also be seen in the resource JSON for the function).
+ *     This means that a span attribute **MUST** be used, as an Azure function
+ *     app can host multiple functions that would usually share
+ *     a TracerProvider (see also the `cloud.resource_id` attribute).
+ *
+ * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ */
+export const ATTR_FAAS_NAME = 'faas.name' as const;

packages/instrumentation-aws-lambda/test/integrations/lambda-handler.test.ts

@@ -34,11 +34,10 @@ import { Context } from 'aws-lambda';
 import * as assert from 'assert';
 import {
   ATTR_URL_FULL,
-  SEMATTRS_EXCEPTION_MESSAGE,
-  SEMATTRS_FAAS_COLDSTART,
-  SEMATTRS_FAAS_EXECUTION,
-  SEMRESATTRS_FAAS_NAME,
+  ATTR_EXCEPTION_MESSAGE,
 } from '@opentelemetry/semantic-conventions';
+import { ATTR_FAAS_COLDSTART, ATTR_FAAS_NAME } from '../../src/semconv';
+import { ATTR_FAAS_EXECUTION } from '../../src/semconv-obsolete';
 import {
   Context as OtelContext,
   context,
@@ -60,10 +59,7 @@ const memoryExporter = new InMemorySpanExporter();
 const assertSpanSuccess = (span: ReadableSpan) => {
   assert.strictEqual(span.kind, SpanKind.SERVER);
   assert.strictEqual(span.name, 'my_function');
-  assert.strictEqual(
-    span.attributes[SEMATTRS_FAAS_EXECUTION],
-    'aws_request_id'
-  );
+  assert.strictEqual(span.attributes[ATTR_FAAS_EXECUTION], 'aws_request_id');
   assert.strictEqual(span.attributes['faas.id'], 'my_arn');
   assert.strictEqual(span.status.code, SpanStatusCode.UNSET);
   assert.strictEqual(span.status.message, undefined);
@@ -72,16 +68,13 @@ const assertSpanSuccess = (span: ReadableSpan) => {
 const assertSpanFailure = (span: ReadableSpan) => {
   assert.strictEqual(span.kind, SpanKind.SERVER);
   assert.strictEqual(span.name, 'my_function');
-  assert.strictEqual(
-    span.attributes[SEMATTRS_FAAS_EXECUTION],
-    'aws_request_id'
-  );
+  assert.strictEqual(span.attributes[ATTR_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![SEMATTRS_EXCEPTION_MESSAGE],
+    span.events[0].attributes![ATTR_EXCEPTION_MESSAGE],
     'handler error'
   );
 };
@@ -299,12 +292,12 @@ describe('lambda handler', () => {
       assert.strictEqual(result1, 'ok');
       assertSpanSuccess(span1);
       assert.strictEqual(span1.parentSpanContext?.spanId, undefined);
-      assert.strictEqual(span1.attributes[SEMATTRS_FAAS_COLDSTART], true);
+      assert.strictEqual(span1.attributes[ATTR_FAAS_COLDSTART], true);
 
       assert.strictEqual(result2, 'ok');
       assertSpanSuccess(span2);
       assert.strictEqual(span2.parentSpanContext?.spanId, undefined);
-      assert.strictEqual(span2.attributes[SEMATTRS_FAAS_COLDSTART], false);
+      assert.strictEqual(span2.attributes[ATTR_FAAS_COLDSTART], false);
     });
 
     it('should record coldstart with provisioned concurrency', async () => {
@@ -331,7 +324,7 @@ describe('lambda handler', () => {
       assert.strictEqual(spans.length, 1);
       assertSpanSuccess(span);
       assert.strictEqual(span.parentSpanContext?.spanId, undefined);
-      assert.strictEqual(span.attributes[SEMATTRS_FAAS_COLDSTART], false);
+      assert.strictEqual(span.attributes[ATTR_FAAS_COLDSTART], false);
     });
 
     it('should record coldstart with proactive initialization', async () => {
@@ -358,7 +351,7 @@ describe('lambda handler', () => {
       assert.strictEqual(spans.length, 1);
       assertSpanSuccess(span);
       assert.strictEqual(span.parentSpanContext?.spanId, undefined);
-      assert.strictEqual(span.attributes[SEMATTRS_FAAS_COLDSTART], false);
+      assert.strictEqual(span.attributes[ATTR_FAAS_COLDSTART], false);
     });
 
     it('should record error', async () => {
@@ -638,18 +631,15 @@ describe('lambda handler', () => {
       it('sync - success', async () => {
         initializeHandler('lambda-test/async.handler', {
           requestHook: (span, { context }) => {
-            span.setAttribute(SEMRESATTRS_FAAS_NAME, context.functionName);
+            span.setAttribute(ATTR_FAAS_NAME, context.functionName);
           },
         });
 
         await lambdaRequire('lambda-test/async').handler('arg', ctx);
         const spans = memoryExporter.getFinishedSpans();
         const [span] = spans;
         assert.strictEqual(spans.length, 1);
-        assert.strictEqual(
-          span.attributes[SEMRESATTRS_FAAS_NAME],
-          ctx.functionName
-        );
+        assert.strictEqual(span.attributes[ATTR_FAAS_NAME], ctx.functionName);
         assertSpanSuccess(span);
       });
     });