autotel-aws 0.2.0

package/dist/sdk.d.cts

@@ -0,0 +1,155 @@
+import { Client } from '@aws-sdk/smithy-client';
+import { S as SDKInstrumentationConfig } from './config-C7zV8Zm6.cjs';
+import './types-3_ak5jhy.cjs';
+import '@opentelemetry/api';
+
+/**
+ * AWS SDK v3 auto-instrumentation
+ *
+ * Provides multiple approaches for instrumenting AWS SDK v3 clients:
+ * 1. `instrumentSDK()` - Wrap an existing client instance
+ * 2. `createTracedClient()` - Create a pre-instrumented client
+ * 3. `autoInstrumentAWS()` - Globally patch all AWS SDK clients
+ *
+ * @example Basic instrumentation
+ * ```typescript
+ * import { instrumentSDK } from 'autotel-aws/sdk';
+ * import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+ *
+ * const s3 = instrumentSDK(new S3Client({ region: 'us-east-1' }));
+ *
+ * // All send() calls are now traced
+ * await s3.send(new PutObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt' }));
+ * ```
+ */
+
+/**
+ * Instrument an existing AWS SDK v3 client
+ *
+ * Wraps the client's `send()` method to automatically create spans
+ * for all AWS API calls with proper semantic attributes.
+ *
+ * @param client - An AWS SDK v3 client instance
+ * @param config - Optional instrumentation configuration
+ * @returns The instrumented client (same instance, modified)
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { instrumentSDK } from 'autotel-aws/sdk';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3 = instrumentSDK(new S3Client({ region: 'us-east-1' }));
+ * ```
+ *
+ * @example With configuration
+ * ```typescript
+ * const s3 = instrumentSDK(new S3Client({}), {
+ *   service: 's3',
+ *   captureRequest: true,
+ *   captureResponse: true
+ * });
+ * ```
+ *
+ * @remarks
+ * Semantic attributes set automatically:
+ * - `rpc.system` - 'aws-api'
+ * - `rpc.service` - AWS service name (e.g., 'S3', 'DynamoDB')
+ * - `rpc.method` - Operation name (e.g., 'GetObject', 'PutItem')
+ * - `aws.request_id` - AWS request ID from response
+ * - `http.status_code` - HTTP status code
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/cloud-providers/aws-sdk/
+ */
+declare function instrumentSDK<T extends Client<unknown, unknown, unknown, unknown>>(client: T, config?: SDKInstrumentationConfig): T;
+/**
+ * Create a pre-instrumented AWS SDK v3 client
+ *
+ * Convenience factory that creates and instruments a client in one call.
+ *
+ * @param ClientClass - The AWS SDK client class constructor
+ * @param config - Client configuration merged with instrumentation config
+ * @returns A new instrumented client instance
+ *
+ * @example
+ * ```typescript
+ * import { createTracedClient } from 'autotel-aws/sdk';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ * import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+ *
+ * // Create instrumented clients
+ * const s3 = createTracedClient(S3Client, { region: 'us-east-1' });
+ * const dynamodb = createTracedClient(DynamoDBClient, {
+ *   region: 'us-east-1',
+ *   captureRequest: true
+ * });
+ * ```
+ */
+declare function createTracedClient<T extends new (...args: any[]) => Client<unknown, unknown, unknown, unknown>>(ClientClass: T, config?: SDKInstrumentationConfig & ConstructorParameters<T>[0]): InstanceType<T>;
+/**
+ * Auto-instrument all AWS SDK v3 clients globally
+ *
+ * Patches the AWS SDK's base Client class to automatically instrument
+ * all client instances created after this call. This is the most convenient
+ * approach but requires the AWS SDK to be installed.
+ *
+ * Call this once at application startup, before creating any clients.
+ *
+ * @param config - Optional default instrumentation configuration
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { autoInstrumentAWS } from 'autotel-aws/sdk';
+ *
+ * // Call once at startup
+ * autoInstrumentAWS();
+ *
+ * // All subsequent clients are automatically instrumented
+ * const s3 = new S3Client({ region: 'us-east-1' });
+ * const dynamodb = new DynamoDBClient({ region: 'us-east-1' });
+ *
+ * // Both are traced automatically
+ * await s3.send(new GetObjectCommand({ Bucket: 'b', Key: 'k' }));
+ * await dynamodb.send(new GetItemCommand({ TableName: 't', Key: {} }));
+ * ```
+ *
+ * @example With default configuration
+ * ```typescript
+ * autoInstrumentAWS({
+ *   captureRequest: false,
+ *   captureResponse: false
+ * });
+ * ```
+ *
+ * @remarks
+ * - This function is idempotent - calling it multiple times has no effect
+ * - Clients created before calling this function are NOT instrumented
+ * - Use `instrumentSDK()` for clients created before auto-instrumentation
+ * - Requires `@aws-sdk/smithy-client` to be installed (peer dependency)
+ *
+ * @throws Error if AWS SDK is not installed
+ */
+declare function autoInstrumentAWS(config?: SDKInstrumentationConfig): void;
+/**
+ * Disable global auto-instrumentation
+ *
+ * Restores the original AWS SDK behavior. Useful for testing or
+ * when you need to disable instrumentation temporarily.
+ *
+ * @example
+ * ```typescript
+ * import { autoInstrumentAWS, disableAutoInstrumentAWS } from 'autotel-aws/sdk';
+ *
+ * autoInstrumentAWS();
+ * // ... use instrumented clients ...
+ *
+ * disableAutoInstrumentAWS();
+ * // Subsequent operations are not traced
+ * ```
+ */
+declare function disableAutoInstrumentAWS(): void;
+/**
+ * Check if global auto-instrumentation is enabled
+ */
+declare function isAutoInstrumentEnabled(): boolean;
+
+export { SDKInstrumentationConfig, autoInstrumentAWS, createTracedClient, disableAutoInstrumentAWS, instrumentSDK, isAutoInstrumentEnabled };

package/dist/sdk.d.ts

@@ -0,0 +1,155 @@
+import { Client } from '@aws-sdk/smithy-client';
+import { S as SDKInstrumentationConfig } from './config-DxjTT8jd.js';
+import './types-3_ak5jhy.js';
+import '@opentelemetry/api';
+
+/**
+ * AWS SDK v3 auto-instrumentation
+ *
+ * Provides multiple approaches for instrumenting AWS SDK v3 clients:
+ * 1. `instrumentSDK()` - Wrap an existing client instance
+ * 2. `createTracedClient()` - Create a pre-instrumented client
+ * 3. `autoInstrumentAWS()` - Globally patch all AWS SDK clients
+ *
+ * @example Basic instrumentation
+ * ```typescript
+ * import { instrumentSDK } from 'autotel-aws/sdk';
+ * import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+ *
+ * const s3 = instrumentSDK(new S3Client({ region: 'us-east-1' }));
+ *
+ * // All send() calls are now traced
+ * await s3.send(new PutObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt' }));
+ * ```
+ */
+
+/**
+ * Instrument an existing AWS SDK v3 client
+ *
+ * Wraps the client's `send()` method to automatically create spans
+ * for all AWS API calls with proper semantic attributes.
+ *
+ * @param client - An AWS SDK v3 client instance
+ * @param config - Optional instrumentation configuration
+ * @returns The instrumented client (same instance, modified)
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { instrumentSDK } from 'autotel-aws/sdk';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3 = instrumentSDK(new S3Client({ region: 'us-east-1' }));
+ * ```
+ *
+ * @example With configuration
+ * ```typescript
+ * const s3 = instrumentSDK(new S3Client({}), {
+ *   service: 's3',
+ *   captureRequest: true,
+ *   captureResponse: true
+ * });
+ * ```
+ *
+ * @remarks
+ * Semantic attributes set automatically:
+ * - `rpc.system` - 'aws-api'
+ * - `rpc.service` - AWS service name (e.g., 'S3', 'DynamoDB')
+ * - `rpc.method` - Operation name (e.g., 'GetObject', 'PutItem')
+ * - `aws.request_id` - AWS request ID from response
+ * - `http.status_code` - HTTP status code
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/cloud-providers/aws-sdk/
+ */
+declare function instrumentSDK<T extends Client<unknown, unknown, unknown, unknown>>(client: T, config?: SDKInstrumentationConfig): T;
+/**
+ * Create a pre-instrumented AWS SDK v3 client
+ *
+ * Convenience factory that creates and instruments a client in one call.
+ *
+ * @param ClientClass - The AWS SDK client class constructor
+ * @param config - Client configuration merged with instrumentation config
+ * @returns A new instrumented client instance
+ *
+ * @example
+ * ```typescript
+ * import { createTracedClient } from 'autotel-aws/sdk';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ * import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+ *
+ * // Create instrumented clients
+ * const s3 = createTracedClient(S3Client, { region: 'us-east-1' });
+ * const dynamodb = createTracedClient(DynamoDBClient, {
+ *   region: 'us-east-1',
+ *   captureRequest: true
+ * });
+ * ```
+ */
+declare function createTracedClient<T extends new (...args: any[]) => Client<unknown, unknown, unknown, unknown>>(ClientClass: T, config?: SDKInstrumentationConfig & ConstructorParameters<T>[0]): InstanceType<T>;
+/**
+ * Auto-instrument all AWS SDK v3 clients globally
+ *
+ * Patches the AWS SDK's base Client class to automatically instrument
+ * all client instances created after this call. This is the most convenient
+ * approach but requires the AWS SDK to be installed.
+ *
+ * Call this once at application startup, before creating any clients.
+ *
+ * @param config - Optional default instrumentation configuration
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { autoInstrumentAWS } from 'autotel-aws/sdk';
+ *
+ * // Call once at startup
+ * autoInstrumentAWS();
+ *
+ * // All subsequent clients are automatically instrumented
+ * const s3 = new S3Client({ region: 'us-east-1' });
+ * const dynamodb = new DynamoDBClient({ region: 'us-east-1' });
+ *
+ * // Both are traced automatically
+ * await s3.send(new GetObjectCommand({ Bucket: 'b', Key: 'k' }));
+ * await dynamodb.send(new GetItemCommand({ TableName: 't', Key: {} }));
+ * ```
+ *
+ * @example With default configuration
+ * ```typescript
+ * autoInstrumentAWS({
+ *   captureRequest: false,
+ *   captureResponse: false
+ * });
+ * ```
+ *
+ * @remarks
+ * - This function is idempotent - calling it multiple times has no effect
+ * - Clients created before calling this function are NOT instrumented
+ * - Use `instrumentSDK()` for clients created before auto-instrumentation
+ * - Requires `@aws-sdk/smithy-client` to be installed (peer dependency)
+ *
+ * @throws Error if AWS SDK is not installed
+ */
+declare function autoInstrumentAWS(config?: SDKInstrumentationConfig): void;
+/**
+ * Disable global auto-instrumentation
+ *
+ * Restores the original AWS SDK behavior. Useful for testing or
+ * when you need to disable instrumentation temporarily.
+ *
+ * @example
+ * ```typescript
+ * import { autoInstrumentAWS, disableAutoInstrumentAWS } from 'autotel-aws/sdk';
+ *
+ * autoInstrumentAWS();
+ * // ... use instrumented clients ...
+ *
+ * disableAutoInstrumentAWS();
+ * // Subsequent operations are not traced
+ * ```
+ */
+declare function disableAutoInstrumentAWS(): void;
+/**
+ * Check if global auto-instrumentation is enabled
+ */
+declare function isAutoInstrumentEnabled(): boolean;
+
+export { SDKInstrumentationConfig, autoInstrumentAWS, createTracedClient, disableAutoInstrumentAWS, instrumentSDK, isAutoInstrumentEnabled };

package/dist/sdk.js

@@ -0,0 +1,6 @@
+export { autoInstrumentAWS, createTracedClient, disableAutoInstrumentAWS, instrumentSDK, isAutoInstrumentEnabled } from './chunk-FKZOELBT.js';
+import './chunk-YG56NRIO.js';
+import './chunk-I4CKQ4RD.js';
+import './chunk-DGUM43GV.js';
+//# sourceMappingURL=sdk.js.map
+//# sourceMappingURL=sdk.js.map

package/dist/sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sdk.js"}

package/dist/sns.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+var chunkNQ65Y5AI_cjs = require('./chunk-NQ65Y5AI.cjs');
+require('./chunk-UZEJV2YD.cjs');
+require('./chunk-Q3DMMQ7K.cjs');
+require('./chunk-JEQ2X3Z6.cjs');
+
+
+
+Object.defineProperty(exports, "SNSPublisher", {
+  enumerable: true,
+  get: function () { return chunkNQ65Y5AI_cjs.SNSPublisher; }
+});
+Object.defineProperty(exports, "traceSNS", {
+  enumerable: true,
+  get: function () { return chunkNQ65Y5AI_cjs.traceSNS; }
+});
+//# sourceMappingURL=sns.cjs.map
+//# sourceMappingURL=sns.cjs.map

package/dist/sns.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sns.cjs"}

package/dist/sns.d.cts

@@ -0,0 +1,256 @@
+import { TraceContext } from 'autotel';
+
+/**
+ * SNS-specific instrumentation
+ *
+ * Provides semantic helpers for tracing SNS operations with proper OpenTelemetry
+ * messaging semantic conventions. Automatically sets `messaging.*` attributes.
+ *
+ * @example Publish to topic
+ * ```typescript
+ * import { traceSNS } from 'autotel-aws/sns';
+ * import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
+ *
+ * const sns = new SNSClient({});
+ *
+ * export const publishNotification = traceSNS({
+ *   topicArn: 'arn:aws:sns:us-east-1:123456789:notifications'
+ * })(ctx => async (message: string, subject?: string) => {
+ *   const result = await sns.send(new PublishCommand({
+ *     TopicArn: 'arn:aws:sns:us-east-1:123456789:notifications',
+ *     Message: message,
+ *     Subject: subject
+ *   }));
+ *
+ *   if (result.MessageId) {
+ *     ctx.setAttribute('messaging.message.id', result.MessageId);
+ *   }
+ *
+ *   return result;
+ * });
+ *
+ * // Usage: await publishNotification('User signed up', 'New User');
+ * ```
+ *
+ * @example Publish to mobile endpoint
+ * ```typescript
+ * export const sendPushNotification = traceSNS({
+ *   operation: 'publish',
+ *   topicArn: 'arn:aws:sns:us-east-1:123456789:app/APNS/my-app'
+ * })(ctx => async (endpointArn: string, payload: object) => {
+ *   ctx.setAttribute('aws.sns.target_arn', endpointArn);
+ *   return await sns.send(new PublishCommand({
+ *     TargetArn: endpointArn,
+ *     Message: JSON.stringify(payload),
+ *     MessageStructure: 'json'
+ *   }));
+ * });
+ * ```
+ */
+
+/**
+ * SNS operation configuration
+ */
+interface TraceSNSConfig {
+    /**
+     * SNS topic ARN
+     * Sets `messaging.destination.name` attribute.
+     */
+    topicArn: string;
+    /**
+     * Operation type (defaults to 'publish')
+     */
+    operation?: 'publish' | 'subscribe' | 'unsubscribe';
+}
+/**
+ * Trace SNS operations with semantic attributes
+ *
+ * Creates a traced function that automatically sets SNS messaging semantic attributes
+ * following OpenTelemetry conventions.
+ *
+ * @param config - SNS operation configuration
+ * @returns A higher-order function that wraps your SNS operation with tracing
+ *
+ * @remarks
+ * Semantic attributes set automatically:
+ * - `messaging.system` - 'aws_sns'
+ * - `messaging.destination.name` - Topic ARN
+ * - `messaging.operation` - 'publish'
+ *
+ * Additional attributes you should set in your handler:
+ * - `messaging.message.id` - Message ID from response
+ * - `aws.sns.target_arn` - Target ARN for direct publishing
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/messaging/aws-sns/
+ */
+declare function traceSNS(config: TraceSNSConfig): <TArgs extends unknown[], TReturn>(fn: (ctx: TraceContext) => (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
+/**
+ * Configuration for SNS Publisher
+ */
+interface SNSPublisherConfig {
+    /**
+     * SNS Topic ARN
+     */
+    topicArn: string;
+    /**
+     * Inject W3C Trace Context into message attributes
+     * Enables distributed tracing to SNS subscribers (e.g., Lambda, SQS)
+     * @default true
+     */
+    injectTraceContext?: boolean;
+    /**
+     * Optional service name for tracing
+     */
+    service?: string;
+}
+/**
+ * Message to publish via SNS Publisher
+ */
+interface SNSPublishMessage {
+    /**
+     * Message body (string or JSON for message structure)
+     */
+    message: string;
+    /**
+     * Optional subject (for email/SMS subscriptions)
+     */
+    subject?: string;
+    /**
+     * Optional message attributes
+     */
+    attributes?: Record<string, {
+        StringValue: string;
+        DataType: string;
+    }>;
+    /**
+     * Optional target ARN for direct endpoint publishing
+     */
+    targetArn?: string;
+    /**
+     * Optional phone number for SMS
+     */
+    phoneNumber?: string;
+    /**
+     * Optional message structure ('json' for platform-specific messages)
+     */
+    messageStructure?: 'json';
+    /**
+     * Optional message group ID (for FIFO topics)
+     */
+    messageGroupId?: string;
+    /**
+     * Optional deduplication ID (for FIFO topics)
+     */
+    messageDeduplicationId?: string;
+}
+/**
+ * SNS Publisher with automatic trace context injection
+ *
+ * Wraps an SNS client to automatically:
+ * - Create spans for publish operations
+ * - Inject W3C Trace Context into message attributes
+ * - Set proper semantic attributes
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { SNSPublisher } from 'autotel-aws/sns';
+ * import { SNSClient } from '@aws-sdk/client-sns';
+ *
+ * const sns = new SNSClient({ region: 'us-east-1' });
+ * const publisher = new SNSPublisher(sns, {
+ *   topicArn: 'arn:aws:sns:us-east-1:123456789:my-topic'
+ * });
+ *
+ * // Publish with automatic trace context
+ * const result = await publisher.publish({
+ *   message: 'Order completed',
+ *   subject: 'Order #12345'
+ * });
+ * console.log('Message ID:', result.messageId);
+ * ```
+ *
+ * @example With custom attributes
+ * ```typescript
+ * await publisher.publish({
+ *   message: JSON.stringify({ orderId: '12345', status: 'completed' }),
+ *   attributes: {
+ *     'eventType': { StringValue: 'ORDER_COMPLETED', DataType: 'String' },
+ *     'priority': { StringValue: 'high', DataType: 'String' }
+ *   }
+ * });
+ * ```
+ *
+ * @example Batch publish
+ * ```typescript
+ * const results = await publisher.publishBatch([
+ *   { message: 'Event 1' },
+ *   { message: 'Event 2' },
+ *   { message: 'Event 3' }
+ * ]);
+ * console.log(`Published ${results.successful.length} messages`);
+ * ```
+ *
+ * @example Direct endpoint publish
+ * ```typescript
+ * await publisher.publishToEndpoint({
+ *   targetArn: 'arn:aws:sns:us-east-1:123456789:endpoint/APNS/my-app/device-token',
+ *   message: JSON.stringify({
+ *     APNS: JSON.stringify({ aps: { alert: 'Hello!' } })
+ *   }),
+ *   messageStructure: 'json'
+ * });
+ * ```
+ */
+declare class SNSPublisher<TClient extends {
+    send: (command: any) => Promise<any>;
+} = any> {
+    private client;
+    private config;
+    private topicName;
+    constructor(client: TClient, config: SNSPublisherConfig);
+    /**
+     * Inject trace context into message attributes
+     */
+    private injectContext;
+    /**
+     * Publish a message to the topic
+     *
+     * @param message - Message to publish
+     * @returns Promise with message ID and sequence number
+     */
+    publish(message: SNSPublishMessage): Promise<{
+        messageId?: string;
+        sequenceNumber?: string;
+    }>;
+    /**
+     * Publish multiple messages in a batch
+     *
+     * @param messages - Array of messages to publish (max 10)
+     * @returns Promise with successful and failed message results
+     */
+    publishBatch(messages: SNSPublishMessage[]): Promise<{
+        successful: Array<{
+            id: string;
+            messageId?: string;
+            sequenceNumber?: string;
+        }>;
+        failed: Array<{
+            id: string;
+            code?: string;
+            message?: string;
+        }>;
+    }>;
+    /**
+     * Publish to a specific endpoint (mobile push, etc.)
+     *
+     * @param message - Message with targetArn set
+     * @returns Promise with message ID
+     */
+    publishToEndpoint(message: Omit<SNSPublishMessage, 'targetArn'> & {
+        targetArn: string;
+    }): Promise<{
+        messageId?: string;
+    }>;
+}
+
+export { type SNSPublishMessage, SNSPublisher, type SNSPublisherConfig, type TraceSNSConfig, traceSNS };