autotel-aws 0.2.0

package/dist/kinesis.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var chunkHMTKKKKP_cjs = require('./chunk-HMTKKKKP.cjs');
+require('./chunk-UZEJV2YD.cjs');
+require('./chunk-Q3DMMQ7K.cjs');
+require('./chunk-JEQ2X3Z6.cjs');
+
+
+
+Object.defineProperty(exports, "KinesisConsumer", {
+  enumerable: true,
+  get: function () { return chunkHMTKKKKP_cjs.KinesisConsumer; }
+});
+Object.defineProperty(exports, "KinesisProducer", {
+  enumerable: true,
+  get: function () { return chunkHMTKKKKP_cjs.KinesisProducer; }
+});
+Object.defineProperty(exports, "traceKinesis", {
+  enumerable: true,
+  get: function () { return chunkHMTKKKKP_cjs.traceKinesis; }
+});
+//# sourceMappingURL=kinesis.cjs.map
+//# sourceMappingURL=kinesis.cjs.map

package/dist/kinesis.cjs.map

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

package/dist/kinesis.d.cts

@@ -0,0 +1,360 @@
+import { TraceContext } from 'autotel';
+
+/**
+ * Kinesis-specific instrumentation
+ *
+ * Provides semantic helpers for tracing Kinesis Data Streams operations with proper
+ * OpenTelemetry messaging semantic conventions.
+ *
+ * @example Put record to stream
+ * ```typescript
+ * import { traceKinesis } from 'autotel-aws/kinesis';
+ * import { KinesisClient, PutRecordCommand } from '@aws-sdk/client-kinesis';
+ *
+ * const kinesis = new KinesisClient({});
+ *
+ * export const putRecord = traceKinesis({
+ *   operation: 'put',
+ *   streamName: 'my-stream'
+ * })(ctx => async (data: object, partitionKey: string) => {
+ *   const result = await kinesis.send(new PutRecordCommand({
+ *     StreamName: 'my-stream',
+ *     Data: Buffer.from(JSON.stringify(data)),
+ *     PartitionKey: partitionKey
+ *   }));
+ *
+ *   ctx.setAttribute('aws.kinesis.shard_id', result.ShardId ?? '');
+ *   ctx.setAttribute('aws.kinesis.sequence_number', result.SequenceNumber ?? '');
+ *
+ *   return result;
+ * });
+ *
+ * // Usage: await putRecord({ event: 'click' }, 'user-123');
+ * ```
+ *
+ * @example Get records from shard
+ * ```typescript
+ * export const getRecords = traceKinesis({
+ *   operation: 'get',
+ *   streamName: 'my-stream'
+ * })(ctx => async (shardIterator: string, limit: number) => {
+ *   const result = await kinesis.send(new GetRecordsCommand({
+ *     ShardIterator: shardIterator,
+ *     Limit: limit
+ *   }));
+ *
+ *   ctx.setAttribute('messaging.batch.message_count', result.Records?.length ?? 0);
+ *   return result;
+ * });
+ * ```
+ */
+
+/**
+ * Kinesis operation configuration
+ */
+interface TraceKinesisConfig {
+    /**
+     * Kinesis operation type
+     * - 'put' - PutRecord, PutRecords
+     * - 'get' - GetRecords, GetShardIterator
+     */
+    operation: 'put' | 'get';
+    /**
+     * Kinesis stream name
+     * Sets `messaging.destination.name` attribute.
+     */
+    streamName: string;
+    /**
+     * Shard ID (if known at configuration time)
+     * Sets `aws.kinesis.shard_id` attribute.
+     */
+    shardId?: string;
+}
+/**
+ * Trace Kinesis operations with semantic attributes
+ *
+ * Creates a traced function that automatically sets Kinesis messaging semantic attributes
+ * following OpenTelemetry conventions.
+ *
+ * @param config - Kinesis operation configuration
+ * @returns A higher-order function that wraps your Kinesis operation with tracing
+ *
+ * @remarks
+ * Semantic attributes set automatically:
+ * - `messaging.system` - 'aws_kinesis'
+ * - `messaging.destination.name` - Stream name
+ * - `messaging.operation` - 'put' or 'get'
+ * - `aws.kinesis.shard_id` - Shard ID (if provided)
+ *
+ * Additional attributes you should set in your handler:
+ * - `aws.kinesis.sequence_number` - Record sequence number
+ * - `messaging.batch.message_count` - Number of records in batch
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/messaging/aws-kinesis/
+ */
+declare function traceKinesis(config: TraceKinesisConfig): <TArgs extends unknown[], TReturn>(fn: (ctx: TraceContext) => (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
+/**
+ * Configuration for Kinesis Producer
+ */
+interface KinesisProducerConfig {
+    /**
+     * Kinesis stream name or ARN
+     */
+    streamName: string;
+    /**
+     * Inject W3C Trace Context into record data
+     * Enables distributed tracing across producer/consumer
+     * @default true
+     */
+    injectTraceContext?: boolean;
+    /**
+     * Optional service name for tracing
+     */
+    service?: string;
+}
+/**
+ * Record to put via Kinesis Producer
+ */
+interface KinesisRecord {
+    /**
+     * Record data (will be serialized to JSON if object)
+     */
+    data: string | object;
+    /**
+     * Partition key for sharding
+     */
+    partitionKey: string;
+    /**
+     * Optional explicit hash key
+     */
+    explicitHashKey?: string;
+    /**
+     * Optional sequence number for ordering
+     */
+    sequenceNumberForOrdering?: string;
+}
+/**
+ * Kinesis Producer with automatic trace context injection
+ *
+ * Wraps a Kinesis client to automatically:
+ * - Create spans for put operations
+ * - Inject W3C Trace Context into record data
+ * - Set proper semantic attributes
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { KinesisProducer } from 'autotel-aws/kinesis';
+ * import { KinesisClient } from '@aws-sdk/client-kinesis';
+ *
+ * const kinesis = new KinesisClient({ region: 'us-east-1' });
+ * const producer = new KinesisProducer(kinesis, {
+ *   streamName: 'my-stream'
+ * });
+ *
+ * // Put with automatic trace context
+ * const result = await producer.putRecord({
+ *   data: { event: 'click', userId: '123' },
+ *   partitionKey: 'user-123'
+ * });
+ * console.log('Sequence:', result.sequenceNumber);
+ * ```
+ *
+ * @example Batch put
+ * ```typescript
+ * const results = await producer.putRecords([
+ *   { data: { event: 'click' }, partitionKey: 'user-1' },
+ *   { data: { event: 'view' }, partitionKey: 'user-2' },
+ *   { data: { event: 'scroll' }, partitionKey: 'user-3' }
+ * ]);
+ * console.log(`Put ${results.successful.length} records`);
+ * ```
+ */
+declare class KinesisProducer<TClient extends {
+    send: (command: any) => Promise<any>;
+} = any> {
+    private client;
+    private config;
+    constructor(client: TClient, config: KinesisProducerConfig);
+    /**
+     * Inject trace context into record data
+     */
+    private injectContext;
+    /**
+     * Put a single record to the stream
+     *
+     * @param record - Record to put
+     * @returns Promise with shard ID and sequence number
+     */
+    putRecord(record: KinesisRecord): Promise<{
+        shardId?: string;
+        sequenceNumber?: string;
+        encryptionType?: string;
+    }>;
+    /**
+     * Put multiple records in a batch
+     *
+     * @param records - Array of records to put (max 500)
+     * @returns Promise with successful and failed record results
+     */
+    putRecords(records: KinesisRecord[]): Promise<{
+        successful: Array<{
+            shardId?: string;
+            sequenceNumber?: string;
+        }>;
+        failed: Array<{
+            errorCode?: string;
+            errorMessage?: string;
+        }>;
+        failedRecordCount: number;
+    }>;
+}
+/**
+ * Configuration for Kinesis Consumer
+ */
+interface KinesisConsumerConfig {
+    /**
+     * Kinesis stream name or ARN
+     */
+    streamName: string;
+    /**
+     * Extract W3C Trace Context from record data
+     * Creates child spans linked to the producer
+     * @default true
+     */
+    extractTraceContext?: boolean;
+    /**
+     * Optional service name for tracing
+     */
+    service?: string;
+}
+/**
+ * Received Kinesis record with parsed data
+ */
+interface ReceivedKinesisRecord {
+    /**
+     * Sequence number
+     */
+    sequenceNumber: string;
+    /**
+     * Approximate arrival timestamp
+     */
+    approximateArrivalTimestamp?: Date;
+    /**
+     * Parsed data (JSON parsed if possible)
+     */
+    data: any;
+    /**
+     * Raw data as string
+     */
+    rawData: string;
+    /**
+     * Partition key
+     */
+    partitionKey: string;
+    /**
+     * Encryption type
+     */
+    encryptionType?: string;
+    /**
+     * Original AWS SDK record object
+     */
+    raw: any;
+}
+/**
+ * Record processor function type
+ */
+type KinesisRecordProcessor = (record: ReceivedKinesisRecord, ctx: TraceContext) => Promise<void>;
+/**
+ * Kinesis Consumer with automatic trace context extraction
+ *
+ * Wraps a Kinesis client to automatically:
+ * - Create spans for get operations
+ * - Extract W3C Trace Context from record data
+ * - Link consumer spans to producer spans
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { KinesisConsumer } from 'autotel-aws/kinesis';
+ * import { KinesisClient } from '@aws-sdk/client-kinesis';
+ *
+ * const kinesis = new KinesisClient({ region: 'us-east-1' });
+ * const consumer = new KinesisConsumer(kinesis, {
+ *   streamName: 'my-stream'
+ * });
+ *
+ * // Get shard iterator first
+ * const iterator = await consumer.getShardIterator('shardId-000000000000', 'LATEST');
+ *
+ * // Process records with automatic tracing
+ * const { nextIterator, records } = await consumer.getRecords(iterator, 100);
+ *
+ * for (const record of records) {
+ *   console.log('Record:', record.data);
+ * }
+ * ```
+ *
+ * @example With processor function
+ * ```typescript
+ * await consumer.processRecords(iterator, async (record, ctx) => {
+ *   ctx.setAttribute('event.type', record.data.event);
+ *   await handleEvent(record.data);
+ * });
+ * ```
+ */
+declare class KinesisConsumer<TClient extends {
+    send: (command: any) => Promise<any>;
+} = any> {
+    private client;
+    private config;
+    constructor(client: TClient, config: KinesisConsumerConfig);
+    /**
+     * Extract trace context from record data
+     */
+    private extractContext;
+    /**
+     * Parse raw record data
+     */
+    private parseRecord;
+    /**
+     * Get a shard iterator
+     *
+     * @param shardId - Shard ID
+     * @param type - Iterator type
+     * @param startingSequenceNumber - Starting sequence number (for AT_SEQUENCE_NUMBER, AFTER_SEQUENCE_NUMBER)
+     * @param timestamp - Starting timestamp (for AT_TIMESTAMP)
+     * @returns Shard iterator string
+     */
+    getShardIterator(shardId: string, type: 'AT_SEQUENCE_NUMBER' | 'AFTER_SEQUENCE_NUMBER' | 'TRIM_HORIZON' | 'LATEST' | 'AT_TIMESTAMP', startingSequenceNumber?: string, timestamp?: Date): Promise<string>;
+    /**
+     * Get records from a shard iterator
+     *
+     * @param shardIterator - Shard iterator
+     * @param limit - Maximum records to return (max 10000)
+     * @returns Records and next shard iterator
+     */
+    getRecords(shardIterator: string, limit?: number): Promise<{
+        records: ReceivedKinesisRecord[];
+        nextIterator?: string;
+        millisBehindLatest?: number;
+    }>;
+    /**
+     * Process records with automatic trace context extraction
+     *
+     * @param shardIterator - Shard iterator
+     * @param processor - Function to process each record
+     * @param limit - Maximum records to process
+     * @returns Next shard iterator and count of processed records
+     */
+    processRecords(shardIterator: string, processor: KinesisRecordProcessor, limit?: number): Promise<{
+        nextIterator?: string;
+        processedCount: number;
+    }>;
+    /**
+     * List shards for the stream
+     *
+     * @returns Array of shard IDs
+     */
+    listShards(): Promise<string[]>;
+}
+
+export { KinesisConsumer, type KinesisConsumerConfig, KinesisProducer, type KinesisProducerConfig, type KinesisRecord, type KinesisRecordProcessor, type ReceivedKinesisRecord, type TraceKinesisConfig, traceKinesis };