@aws/durable-execution-sdk-js-otel 0.0.1 → 0.1.1

package/README.md

@@ -1,5 +1,7 @@
 # AWS Durable Execution SDK - OpenTelemetry Plugin
 
+> **⚠️ Experimental Beta:** This plugin is currently in experimental beta. Functionality may change without notice between releases. It is not recommended for production workloads at this time.
+
 OpenTelemetry instrumentation plugin for AWS Durable Execution SDK. Emits distributed traces that correlate across multiple Lambda invocations of a single durable execution, producing deterministic span and trace IDs so that spans from different invocations are stitched into a single coherent trace.
 
 ## Features
@@ -11,19 +13,100 @@ OpenTelemetry instrumentation plugin for AWS Durable Execution SDK. Emits distri
 - **Configurable Sampling**: Control trace volume via environment variable or plugin options
 - **Self-Contained Setup**: No manual TracerProvider configuration required
 
-## Prerequisites
+## Installation
+
+```bash
+npm install @aws/durable-execution-sdk-js-otel
+```
+
+## Quick Start using Xray/CloudWatch Tracing
+
+1. Add the ADOT Lambda Layer to your function and set `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`
+2. Enable X-Ray Active Tracing on the function
+3. Pass `OtelPlugin` to your handler's `plugins` array
+4. Add Xray Write Permissions
 
-### ADOT Lambda Layer
+### 1. ADOT Lambda Layer
 
 This plugin requires the [AWS Distro for OpenTelemetry (ADOT) Lambda layer](https://aws-otel.github.io/docs/getting-started/lambda) to export traces from your Lambda function.
 
-To find the latest ADOT layer ARN for your region:
+The layer ARN follows the format:
+
+```
+arn:aws:lambda:<region>:<awsAccountId>:layer:AWSOpenTelemetryDistroJs:<version>
+```
+
+Refer to the [ADOT Lambda Layer ARNs](https://aws-otel.github.io/docs/getting-started/lambda#aws-lambda-layer-for-opentelemetry-arns) page for the latest version number and supported regions.
+
+**AWS CLI:**
+
+```bash
+aws lambda update-function-configuration \
+  --function-name your-function-name \
+  --layers "arn:aws:lambda:<region>:<<awsAccountId>>:layer:AWSOpenTelemetryDistroJs:<version>"
+```
+
+You must also set the `AWS_LAMBDA_EXEC_WRAPPER` environment variable:
+
+```bash
+aws lambda update-function-configuration \
+  --function-name your-function-name \
+  --environment "Variables={AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument}"
+```
+
+> **Note:** Replace `<region>`, `<awsAccountId>` `<version>` with the latest layer information from the ADOT docs.
+
+**CloudFormation / SAM:**
+
+```yaml
+MyFunction:
+  Type: AWS::Serverless::Function
+  Properties:
+    Layers:
+      - !Sub arn:aws:lambda:${AWS::Region}:<awsAccountId>:layer:AWSOpenTelemetryDistroJs:<version>
+    Environment:
+      Variables:
+        AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
+```
+
+For raw CloudFormation (`AWS::Lambda::Function`):
+
+```yaml
+MyFunction:
+  Type: AWS::Lambda::Function
+  Properties:
+    Layers:
+      - !Sub arn:aws:lambda:${AWS::Region}:<awsAccountId>:layer:AWSOpenTelemetryDistroJs:<version>
+    Environment:
+      Variables:
+        AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
+```
+
+**CDK:**
+
+```typescript
+import * as lambda from "aws-cdk-lib/aws-lambda";
+
+const adotLayer = lambda.LayerVersion.fromLayerVersionArn(
+  this,
+  "AdotLayer",
+  `arn:aws:lambda:${this.region}:<awsAccountId>:layer:AWSOpenTelemetryDistroJs:<version>`,
+);
+
+const fn = new lambda.Function(this, "MyFunction", {
+  runtime: lambda.Runtime.NODEJS_22_X,
+  handler: "index.handler",
+  code: lambda.Code.fromAsset("lambda"),
+  layers: [adotLayer],
+  environment: {
+    AWS_LAMBDA_EXEC_WRAPPER: "/opt/otel-instrument",
+  },
+});
+```
 
-1. Visit the [ADOT Lambda Layer ARNs](https://aws-otel.github.io/docs/getting-started/lambda#aws-lambda-layer-for-opentelemetry-arns) for the list of supported regions and layer ARNs
-2. The Node.js layer name follows the format: `AWSOpenTelemetryDistroJs`
-3. Add the layer ARN to your Lambda function configuration
+> **Tip:** Pin the layer version to a specific number in production deployments to avoid unexpected behavior from automatic version changes.
 
-### AWS X-Ray Active Tracing
+### 2. AWS X-Ray Active Tracing
 
 Enable active tracing on your Lambda function so the `_X_AMZN_TRACE_ID` environment variable is populated at invocation time. The plugin uses this header to derive deterministic trace IDs that remain consistent across all invocations of the same durable execution.
 
@@ -55,29 +138,11 @@ new lambda.Function(this, "MyFunction", {
 });
 ```
 
-## Installation
-
-```bash
-npm install @aws/durable-execution-sdk-js-otel
-```
-
-### Peer Dependencies
-
-This package requires the following peer dependencies:
-
-| Package                                  | Version    |
-| ---------------------------------------- | ---------- |
-| `@aws/durable-execution-sdk-js`          | `*`        |
-| `@opentelemetry/api`                     | `^1.0.0`   |
-| `@opentelemetry/instrumentation`         | `^0.219.0` |
-| `@opentelemetry/instrumentation-aws-sdk` | `^0.74.0`  |
-| `@opentelemetry/sdk-trace-node`          | `^2.6.1`   |
-
-## Quick Start
+### 3. In your Lambda handler (index.js)
 
 ```typescript
 import { withDurableExecution } from "@aws/durable-execution-sdk-js";
-import { DurableExecutionOtelPlugin } from "@aws/durable-execution-sdk-js-otel";
+import { OtelPlugin } from "@aws/durable-execution-sdk-js-otel";
 
 export const handler = withDurableExecution(
   async (event, context) => {
@@ -93,28 +158,47 @@ export const handler = withDurableExecution(
 
     return result;
   },
-  { plugins: [new DurableExecutionOtelPlugin()] },
+  { plugins: [new OtelPlugin()] },
 );
 ```
 
 That's it. The plugin handles TracerProvider setup, deterministic ID generation, and span lifecycle internally.
 
+### 4. Grant Permissions
+
+The function's execution role needs the `AWSXRayDaemonWriteAccess` managed policy (or equivalent permissions) if using X-Ray as the tracing backend.
+
+### AWS Console
+
+See https://aws-otel.github.io/docs/getting-started/lambda#use-the-lambda-console.
+
+### Environment Variables for ADOT layer
+
+| Variable                      | Description                                                                                   | Default           |
+| ----------------------------- | --------------------------------------------------------------------------------------------- | ----------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint for the OTLP exporter (e.g., `http://localhost:4318` for the ADOT collector sidecar) | Set by ADOT layer |
+| `AWS_LAMBDA_EXEC_WRAPPER`     | Set to `/opt/otel-instrument` for the ADOT layer to instrument your function                  | —                 |
+| `OTEL_TRACES_SAMPLER`         | Sampler to use (e.g., `traceidratio` for ratio-based sampling)                                | `always_on`       |
+| `OTEL_TRACES_SAMPLER_ARG`     | Argument for the sampler (e.g., `0.3` to sample 30% of traces)                                | —                 |
+
+See the [ADOT sampling configuration](https://aws-otel.github.io/docs/getting-started/lambda#sampling-configuration) for more details.
+
 ## Configuration
 
 ### Plugin Options
 
 ```typescript
-import { DurableExecutionOtelPlugin } from "@aws/durable-execution-sdk-js-otel";
+import { OtelPlugin } from "@aws/durable-execution-sdk-js-otel";
 
-const plugin = new DurableExecutionOtelPlugin({
+const plugin = new OtelPlugin({
   // Use a custom context extractor (default: xRayContextExtractor)
-  contextExtractor: xRayContextExtractor,
+  contextExtractor?: xRayContextExtractor,
 
   // Provide your own TracerProvider if you already have one configured
-  tracerProvider: myTracerProvider,
+  tracerProvider?: myTracerProvider,
 
   // Custom instrumentation scope name (default: "aws-durable-execution-sdk-js")
-  instrumentationName: "my-service",
+  instrumentationName?: "my-service",
 });
 ```
 
@@ -124,73 +208,18 @@ The plugin supports multiple strategies for extracting upstream trace context:
 
 ```typescript
 import {
-  DurableExecutionOtelPlugin,
+  OtelPlugin,
   xRayContextExtractor,
   w3cClientContextExtractor,
 } from "@aws/durable-execution-sdk-js-otel";
 
 // Default: X-Ray trace header (recommended for most Lambda deployments)
-new DurableExecutionOtelPlugin({ contextExtractor: xRayContextExtractor });
+new OtelPlugin({ contextExtractor: xRayContextExtractor });
 
 // W3C Trace Context via clientContext (requires backend propagation support (TODO))
-new DurableExecutionOtelPlugin({ contextExtractor: w3cClientContextExtractor });
+new OtelPlugin({ contextExtractor: w3cClientContextExtractor });
 ```
 
-## Lambda Setup
-
-### SAM template setup
-
-#### 1. Add the ADOT Layer
-
-Add the ADOT Lambda layer to your function. The layer provides the OpenTelemetry collector that exports traces to your configured backend.
-
-```yaml
-# SAM template example
-MyFunction:
-  Type: AWS::Serverless::Function
-  Properties:
-    Layers:
-      - !Sub arn:aws:lambda:${AWS::Region}:615299751070:layer:AWSOpenTelemetryDistroJs:<version>
-```
-
-> **Note:** The layer ARN varies by region, account, and version. Refer to the [ADOT Lambda Layer ARNs](https://aws-otel.github.io/docs/getting-started/lambda#aws-lambda-layer-for-opentelemetry-arns) for the latest ARN in your region.
-
-#### 2. Set Environment Variables
-
-```yaml
-Environment:
-  Variables:
-    AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
-```
-
-#### 3. Enable X-Ray Active Tracing
-
-```yaml
-TracingConfig:
-  Mode: Active
-```
-
-This ensures the `_X_AMZN_TRACE_ID` environment variable is set on every invocation. The durable execution backend propagates the same Root trace ID to every invocation, so all invocations of the same execution share one trace.
-
-#### 4. Grant Permissions
-
-The function's execution role needs the `AWSXRayDaemonWriteAccess` managed policy (or equivalent permissions) if using X-Ray as the tracing backend.
-
-### AWS Console
-
-See https://aws-otel.github.io/docs/getting-started/lambda#use-the-lambda-console.
-
-### Environment Variables for ADOT layer
-
-| Variable                      | Description                                                                                   | Default           |
-| ----------------------------- | --------------------------------------------------------------------------------------------- | ----------------- |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint for the OTLP exporter (e.g., `http://localhost:4318` for the ADOT collector sidecar) | Set by ADOT layer |
-| `AWS_LAMBDA_EXEC_WRAPPER`     | Set to `/opt/otel-instrument` for the ADOT layer to instrument your function                  | —                 |
-| `OTEL_TRACES_SAMPLER`         | Sampler to use (e.g., `traceidratio` for ratio-based sampling)                                | `always_on`       |
-| `OTEL_TRACES_SAMPLER_ARG`     | Argument for the sampler (e.g., `0.3` to sample 30% of traces)                                | —                 |
-
-See the [ADOT sampling configuration](https://aws-otel.github.io/docs/getting-started/lambda#sampling-configuration) for more details.
-
 ## Verification
 
 After deploying your function with the plugin configured:
@@ -219,12 +248,12 @@ After deploying your function with the plugin configured:
 
 ## API Reference
 
-### `DurableExecutionOtelPlugin`
+### `OtelPlugin`
 
 The main plugin class. Implements `DurableInstrumentationPlugin` from `@aws/durable-execution-sdk-js`.
 
 ```typescript
-new DurableExecutionOtelPlugin(config?: DurableExecutionOtelPluginConfig)
+new OtelPlugin(config?: OtelPluginConfig)
 ```
 
 ### `DeterministicIdGenerator`