fg-tracker-sdk 0.10.0 → 0.13.0

package/dist/infra/aws.js

@@ -1,3 +1,6 @@
+import { performance } from 'node:perf_hooks';
+import { isBedrockRuntime, startBedrockCall } from '../genai/bedrock.js';
+import { EVENTBRIDGE_MAX_REQUEST_BYTES, eventBridgeEntryBytes, injectEventBridgeContext, injectSqsContext, isValidationCode, isValidationError, metaContext, planReceive, readSqsMessage, ReceivedMessages, SQS_MAX_BATCH_BYTES, SQS_MAX_MESSAGE_BYTES, SQS_MIN_MESSAGE_BYTES, sqsAttributesMd5, sqsMessageBytes, stripReceivedMessage, uniqueLinks, } from './messaging.js';
 const PATCHED = Symbol.for('fg-tracker.aws.patched');
 const SERVICE_IDS = {
     sqs: 'sqs',
@@ -360,13 +363,205 @@ function httpStatus(value) {
     const status = obj(obj(value).$metadata).httpStatusCode;
     return typeof status === 'number' ? status : null;
 }
+const received = new WeakMap();
+/** Mensagens recebidas por clients instrumentados deste tracker (contexto lido antes de retirar os atributos). */
+export function receivedMessages(core) {
+    let store = received.get(core);
+    if (!store) {
+        store = new ReceivedMessages();
+        received.set(core, store);
+    }
+    return store;
+}
+/**
+ * Fila FIFO pelo nome (o sufixo `.fifo` é do QueueName): último segmento do caminho da URL (com ou
+ * sem barra final, query ou fragmento) ou do ARN. Na dúvida (URL que não dá para ler), o nome cru.
+ */
+export function isFifoQueue(queue) {
+    let name = queue;
+    if (queue.startsWith('arn:'))
+        name = queue.split(':').pop() ?? queue;
+    else {
+        try {
+            name = new URL(queue).pathname;
+        }
+        catch {
+            name = queue.split(/[?#]/)[0] ?? queue;
+        }
+        name = name.split('/').filter(Boolean).pop() ?? name;
+    }
+    return name.endsWith('.fifo');
+}
+function sqsPublishPlan(args, operation, ref, configured) {
+    const input = obj(args.input);
+    const queueName = ref?.resourceName ?? str(input.QueueUrl) ?? 'queue';
+    // FIFO: reenviar uma entrada recusada depois das aceitas mudaria a ordem do grupo. Sem o limite
+    // da fila declarado, o contexto só entra onde nenhuma fila o recusa (o mínimo do SQS, 1 KiB),
+    // e entradas de lote recusadas não são reenviadas fora de ordem.
+    const fifo = isFifoQueue(str(input.QueueUrl) ?? queueName);
+    const limits = { messageBytes: fifo && !configured.declared ? SQS_MIN_MESSAGE_BYTES : configured.messageBytes };
+    const base = {
+        'messaging.system': 'aws_sqs',
+        'messaging.operation.type': 'send',
+        'messaging.operation.name': operation,
+        'messaging.destination.name': queueName,
+        ...(ref?.resourceArn ? { 'aws.resourceArn': ref.resourceArn } : {}),
+    };
+    if (operation === 'SendMessage') {
+        return {
+            name: `SQS publish ${queueName}`,
+            attributes: base,
+            inject(ctx) {
+                const result = injectSqsContext(input, ctx, { messageBytes: limits.messageBytes, budgetBytes: Number.POSITIVE_INFINITY });
+                return {
+                    args: result.injected ? { ...args, input: result.entry } : args,
+                    injected: new Set(result.injected ? ['message'] : []),
+                    skipped: result.skipped && result.skipped !== 'present' ? [result.skipped] : [],
+                };
+            },
+            restore(output, injected) {
+                if (!injected.has('message'))
+                    return output;
+                const md5 = sqsAttributesMd5(input.MessageAttributes);
+                const out = { ...output };
+                if (md5)
+                    out.MD5OfMessageAttributes = md5;
+                else
+                    delete out.MD5OfMessageAttributes;
+                return out;
+            },
+        };
+    }
+    if (operation === 'SendMessageBatch') {
+        const entries = arr(input.Entries).map(obj);
+        const originals = new Map(entries.map((entry) => [String(entry.Id), entry]));
+        return {
+            name: `SQS publish ${queueName}`,
+            attributes: { ...base, 'messaging.batch.message_count': entries.length },
+            inject(ctx) {
+                // Orçamento agregado: a soma das entradas (atributos incluídos) também tem teto.
+                let remaining = SQS_MAX_BATCH_BYTES - entries.reduce((sum, entry) => sum + sqsMessageBytes(entry.MessageBody, entry.MessageAttributes), 0);
+                const injected = new Set();
+                const skipped = [];
+                const next = entries.map((entry) => {
+                    const result = injectSqsContext(entry, ctx, { messageBytes: limits.messageBytes, budgetBytes: Math.max(0, remaining) });
+                    if (result.injected) {
+                        remaining -= result.addedBytes;
+                        injected.add(String(entry.Id));
+                    }
+                    else if (result.skipped && result.skipped !== 'present')
+                        skipped.push(result.skipped);
+                    return result.entry;
+                });
+                return { args: injected.size > 0 ? { ...args, input: { ...input, Entries: next } } : args, injected, skipped };
+            },
+            restore(output, injected) {
+                if (injected.size === 0 || !Array.isArray(output.Successful))
+                    return output;
+                return {
+                    ...output,
+                    Successful: output.Successful.map((item) => {
+                        const ok = obj(item);
+                        const id = String(ok.Id);
+                        if (!injected.has(id))
+                            return item;
+                        const md5 = sqsAttributesMd5(originals.get(id)?.MessageAttributes);
+                        const out = { ...ok };
+                        if (md5)
+                            out.MD5OfMessageAttributes = md5;
+                        else
+                            delete out.MD5OfMessageAttributes;
+                        return out;
+                    }),
+                };
+            },
+            retryEntries(output, injected) {
+                if (fifo)
+                    return null;
+                const failed = arr(output.Failed).map(obj).filter((item) => injected.has(String(item.Id)) && item.SenderFault === true && isValidationCode(item.Code));
+                if (failed.length === 0)
+                    return null;
+                const retry = failed.map((item) => originals.get(String(item.Id))).filter(Boolean);
+                return {
+                    args: { ...args, input: { ...input, Entries: retry } },
+                    merge(first, retried) {
+                        const retriedIds = new Set([...arr(retried.Successful), ...arr(retried.Failed)].map((item) => String(obj(item).Id)));
+                        return {
+                            ...first,
+                            Successful: [...arr(first.Successful), ...arr(retried.Successful)],
+                            Failed: [...arr(first.Failed).filter((item) => !retriedIds.has(String(obj(item).Id))), ...arr(retried.Failed)],
+                        };
+                    },
+                };
+            },
+        };
+    }
+    return null;
+}
+function eventBridgePublishPlan(args, limits) {
+    const input = obj(args.input);
+    const entries = arr(input.Entries).map(obj);
+    if (entries.length === 0)
+        return null;
+    const bus = str(entries[0].EventBusName) ?? 'default';
+    const busName = bus.startsWith('arn:') ? bus.split('/').pop() || bus : bus;
+    return {
+        name: `EventBridge publish ${busName}`,
+        attributes: {
+            'messaging.system': 'aws_eventbridge',
+            'messaging.operation.type': 'send',
+            'messaging.operation.name': 'PutEvents',
+            'messaging.destination.name': busName,
+            'messaging.batch.message_count': entries.length,
+        },
+        inject(ctx) {
+            // "Menor que" o limite: sobra pelo menos 1 byte.
+            let remaining = limits.requestBytes - 1 - entries.reduce((sum, entry) => sum + eventBridgeEntryBytes(entry), 0);
+            const injected = new Set();
+            const skipped = [];
+            const next = entries.map((entry, index) => {
+                const result = injectEventBridgeContext(entry, ctx, Math.max(0, remaining));
+                if (result.injected) {
+                    remaining -= result.addedBytes;
+                    injected.add(String(index));
+                }
+                else if (result.skipped && result.skipped !== 'present')
+                    skipped.push(result.skipped);
+                return result.entry;
+            });
+            return { args: injected.size > 0 ? { ...args, input: { ...input, Entries: next } } : args, injected, skipped };
+        },
+        restore: (output) => output,
+        retryEntries(output, injected) {
+            const results = arr(output.Entries).map(obj);
+            const indexes = results.flatMap((result, index) => (injected.has(String(index)) && isValidationCode(result.ErrorCode) ? [index] : []));
+            if (indexes.length === 0)
+                return null;
+            return {
+                args: { ...args, input: { ...input, Entries: indexes.map((index) => entries[index]) } },
+                // Resultados por posição: troca só as posições reenviadas.
+                merge(first, retried) {
+                    const merged = arr(first.Entries).slice();
+                    const again = arr(retried.Entries);
+                    indexes.forEach((index, position) => {
+                        if (again[position] !== undefined)
+                            merged[index] = again[position];
+                    });
+                    return { ...first, Entries: merged, FailedEntryCount: merged.filter((item) => obj(item).ErrorCode).length };
+                },
+            };
+        },
+    };
+}
 /**
  * Adiciona o middleware `fgTrackerInfra` (step `initialize`) ao client.
  * - Agregados de infra (§27.4) para SQS, SNS, EventBridge, Kinesis, DynamoDB e Step Functions — nunca amostrados.
  * - Span `http.client` por chamada (qualquer serviço) quando há um trace em andamento; respeita amostragem.
  * - DynamoDB: injeta `ReturnConsumedCapacity: 'TOTAL'` quando não informado.
+ * - SQS/EventBridge (§16.1): span `custom` `SQS publish <fila>`/`EventBridge publish <barramento>` com o
+ *   contexto propagado nas mensagens; `ReceiveMessage` pede o contexto e o guarda para o `trackMessage`.
  */
-export function instrumentAwsClient(core, client) {
+export function instrumentAwsClient(core, client, options = {}) {
     const target = client;
     if (!core.enabled || target[PATCHED])
         return client;
@@ -375,12 +570,19 @@ export function instrumentAwsClient(core, client) {
         return client;
     }
     target[PATCHED] = true;
+    const propagation = options.propagation ?? core.options.propagateTraceTo !== false;
+    const sqsLimits = {
+        messageBytes: Math.min(SQS_MAX_MESSAGE_BYTES, Math.max(SQS_MIN_MESSAGE_BYTES, options.sqsMaxMessageBytes ?? SQS_MAX_MESSAGE_BYTES)),
+        declared: options.sqsMaxMessageBytes !== undefined,
+    };
+    const eventBridgeLimits = { requestBytes: Math.min(EVENTBRIDGE_MAX_REQUEST_BYTES, Math.max(1024, options.eventBridgeMaxRequestBytes ?? EVENTBRIDGE_MAX_REQUEST_BYTES)) };
     let regionPromise = null;
     let endpointPromise = null;
     const middleware = (next, context) => async (args) => {
         if (!core.enabled)
             return next(args);
         const { service, label } = detectService(client, context);
+        const bedrock = isBedrockRuntime(label);
         const operation = (context?.commandName ?? 'Unknown').replace(/Command$/, '');
         let info = {};
         let region;
@@ -401,22 +603,6 @@ export function instrumentAwsClient(core, client) {
         catch {
             info = {};
         }
-        const parent = core.currentContext();
-        const resource = info.primary;
-        const span = parent
-            ? core.startSpan('http.client', `AWS ${label} ${operation}${resource?.resourceName ? ` ${resource.resourceName}` : ''}`, {
-                'aws.service': label,
-                'aws.operation': operation,
-                ...(resource?.resourceArn ? { 'aws.resourceArn': resource.resourceArn } : {}),
-                ...(resource?.resourceName ? { 'aws.resourceName': resource.resourceName } : {}),
-                ...(region ? { 'aws.region': region } : {}),
-                ...(endpointHost ? { 'server.address': endpointHost, host: endpointHost } : {}),
-            })
-            : null;
-        if (span) {
-            span.method = 'POST';
-            span.route = `/${label}/${operation}`;
-        }
         const safeRecord = (output, error) => {
             try {
                 info.record?.(output, error);
@@ -425,24 +611,222 @@ export function instrumentAwsClient(core, client) {
                 /* agregação nunca quebra a chamada */
             }
         };
+        /** A chamada em si, com o span `http.client` quando há trace. Não registra agregados. */
+        /**
+         * `injected`: tentativa com o contexto que a instrumentação acrescentou. Se o serviço a recusa
+         * por validação, a culpa é da injeção (a chamada é repetida sem ela): o span registra a recusa
+         * sem `error`, para não virar issue da aplicação.
+         */
+        const call = async (finalArgs, decorate, injected = false) => {
+            const parent = core.currentContext();
+            const resource = info.primary;
+            const startedPerf = performance.now();
+            const span = parent
+                ? core.startSpan('http.client', `AWS ${label} ${operation}${resource?.resourceName ? ` ${resource.resourceName}` : ''}`, {
+                    'aws.service': label,
+                    'aws.operation': operation,
+                    ...(resource?.resourceArn ? { 'aws.resourceArn': resource.resourceArn } : {}),
+                    ...(resource?.resourceName ? { 'aws.resourceName': resource.resourceName } : {}),
+                    ...(region ? { 'aws.region': region } : {}),
+                    ...(endpointHost ? { 'server.address': endpointHost, host: endpointHost } : {}),
+                })
+                : null;
+            if (span) {
+                span.method = 'POST';
+                span.route = `/${label}/${operation}`;
+            }
+            // Bedrock Converse/ConverseStream: atributos GenAI no próprio span; o fim do span passa a ser do observador.
+            let genAi = null;
+            const genAiConfig = span && bedrock ? core.genAiFor(span) : null;
+            if (span && genAiConfig) {
+                try {
+                    genAi = startBedrockCall(genAiConfig, span, operation, finalArgs?.input, startedPerf);
+                }
+                catch {
+                    genAi = null;
+                }
+            }
+            let handedOff = false;
+            try {
+                const result = span ? await core.runInSpan(span, () => next(finalArgs)) : await next(finalArgs);
+                const output = obj(result?.output);
+                if (span) {
+                    span.statusCode = httpStatus(output) ?? 200;
+                    try {
+                        decorate?.(span, output);
+                    }
+                    catch {
+                        /* atributos são best-effort */
+                    }
+                }
+                if (genAi && span) {
+                    handedOff = true;
+                    try {
+                        genAi.output(result);
+                    }
+                    catch {
+                        span.end();
+                    }
+                }
+                return result;
+            }
+            catch (err) {
+                if (span) {
+                    span.statusCode = httpStatus(err);
+                    if (genAi) {
+                        handedOff = true;
+                        try {
+                            genAi.error(err);
+                        }
+                        catch {
+                            span.end();
+                        }
+                    }
+                    else if (injected && isValidationError(err)) {
+                        span.setAttribute('messaging.propagation.rejected', true);
+                        const name = err?.name;
+                        if (typeof name === 'string')
+                            span.setAttribute('error.type', name);
+                    }
+                    else {
+                        span.setError(err);
+                    }
+                }
+                throw err;
+            }
+            finally {
+                // Com observador GenAI, quem fecha é ele (já fechou, ou fecha no fim do stream).
+                if (!handedOff)
+                    span?.end();
+            }
+        };
+        // ReceiveMessage: pede o contexto, guarda-o por mensagem e devolve a resposta como o chamador pediu.
+        if (propagation && service === 'sqs' && operation === 'ReceiveMessage') {
+            let plan = null;
+            try {
+                plan = planReceive(obj(callArgs.input));
+            }
+            catch {
+                plan = null;
+            }
+            if (plan) {
+                const store = receivedMessages(core);
+                try {
+                    // Os produtores das mensagens recebidas viram links do span da chamada (antes de ele fechar).
+                    const result = await call({ ...callArgs, input: plan.input }, (span, output) => {
+                        const contexts = arr(output.Messages).map((message) => metaContext(readSqsMessage(message)));
+                        const { links, dropped } = uniqueLinks(contexts);
+                        if (links.length > 0)
+                            span.setAttribute('links', links);
+                        if (dropped > 0)
+                            span.setAttribute('links.dropped', dropped);
+                    });
+                    const output = obj(result?.output);
+                    let finalResult = result;
+                    if (Array.isArray(output.Messages)) {
+                        const messages = output.Messages.map((message) => {
+                            const record = obj(message);
+                            try {
+                                store.remember(record, readSqsMessage(record));
+                                return stripReceivedMessage(record, plan);
+                            }
+                            catch {
+                                return message;
+                            }
+                        });
+                        finalResult = { ...result, output: { ...output, Messages: messages } };
+                    }
+                    safeRecord(obj(finalResult.output), null);
+                    return finalResult;
+                }
+                catch (err) {
+                    safeRecord(null, err);
+                    throw err;
+                }
+            }
+        }
+        let publish = null;
+        if (propagation && core.currentContext()) {
+            try {
+                if (service === 'sqs')
+                    publish = sqsPublishPlan(callArgs, operation, info.primary, sqsLimits);
+                else if (service === 'eventbridge' && operation === 'PutEvents')
+                    publish = eventBridgePublishPlan(callArgs, eventBridgeLimits);
+            }
+            catch {
+                publish = null;
+            }
+        }
+        if (!publish) {
+            try {
+                const result = await call(callArgs);
+                safeRecord(obj(result?.output), null);
+                return result;
+            }
+            catch (err) {
+                safeRecord(null, err);
+                throw err;
+            }
+        }
+        const plan = publish;
+        const publishSpan = core.startSpan('custom', plan.name, { ...plan.attributes, ...(region ? { 'aws.region': region } : {}) });
         try {
-            const result = span ? await core.runInSpan(span, () => next(callArgs)) : await next(callArgs);
+            const result = await core.runInSpan(publishSpan, async () => {
+                let injection;
+                try {
+                    injection = plan.inject(publishSpan.context());
+                }
+                catch {
+                    injection = { args: callArgs, injected: new Set(), skipped: [] };
+                }
+                publishSpan.setAttribute('messaging.propagation.injected', injection.injected.size);
+                if (injection.skipped.length > 0) {
+                    publishSpan.setAttribute('messaging.propagation.skipped', injection.skipped.length);
+                    publishSpan.setAttribute('messaging.propagation.skip_reasons', [...new Set(injection.skipped)]);
+                }
+                let res;
+                try {
+                    res = await call(injection.args, undefined, injection.injected.size > 0);
+                }
+                catch (err) {
+                    // Recusa de validação com o contexto: nada foi publicado; repete como o usuário montou.
+                    if (injection.injected.size === 0 || !isValidationError(err))
+                        throw err;
+                    publishSpan.setAttribute('messaging.propagation.fallback', 'request');
+                    const plain = await call(callArgs);
+                    return plain;
+                }
+                let output = obj(res?.output);
+                try {
+                    const retry = plan.retryEntries?.(output, injection.injected);
+                    if (retry) {
+                        publishSpan.setAttribute('messaging.propagation.fallback', 'entries');
+                        // Falha no reenvio: fica a resposta original, com as entradas recusadas.
+                        const again = await call(retry.args).then((value) => obj(value?.output), () => null);
+                        if (again)
+                            output = retry.merge(output, again);
+                    }
+                    output = plan.restore(output, injection.injected);
+                }
+                catch {
+                    /* a resposta original continua valendo */
+                }
+                return { ...res, output };
+            });
             const output = obj(result?.output);
             safeRecord(output, null);
-            if (span)
-                span.statusCode = httpStatus(output) ?? 200;
+            const messageId = str(output.MessageId);
+            if (messageId)
+                publishSpan.setAttribute('messaging.message.id', messageId);
             return result;
         }
         catch (err) {
             safeRecord(null, err);
-            if (span) {
-                span.statusCode = httpStatus(err);
-                span.setError(err);
-            }
+            publishSpan.setError(err);
             throw err;
         }
         finally {
-            span?.end();
+            publishSpan.end();
         }
     };
     client.middlewareStack.add(middleware, { step: 'initialize', name: 'fgTrackerInfra', override: true, tags: ['FG_TRACKER'] });
@@ -450,18 +834,60 @@ export function instrumentAwsClient(core, client) {
 }
 /**
  * Mede o processamento de uma mensagem consumida (`processingMsSum`, `processingMsMax`, `errors`)
- * e cria um span `custom` para os spans internos (AWS, db, fetch) formarem um trace.
+ * e cria um span `custom` `SQS process <fila>` para os spans internos (AWS, db, fetch) formarem um trace.
+ *
+ * Com `record`, o span continua o trace do produtor: raiz local com `remoteParentSpanId` (ou filho
+ * do span atual quando ele já está no mesmo trace, como no `wrapLambda` de uma mensagem só). Cada
+ * chamada tem o próprio contexto, inclusive em `Promise.all`; o contexto da invocação vira link.
  */
-export async function trackQueueMessage(core, queue, fn) {
+export async function trackQueueMessage(core, queue, fn, record) {
     if (!core.enabled)
         return fn();
     const ref = sqsQueueRef(queue, process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || undefined);
     core.infra?.learnAccount(ref.resourceArn);
-    const span = core.startSpan('custom', `SQS process ${ref.resourceName ?? queue}`, {
+    let meta;
+    if (record) {
+        try {
+            const own = readSqsMessage(record);
+            const stashed = receivedMessages(core).lookup(record);
+            meta = {
+                traceparent: own.traceparent ?? stashed?.traceparent,
+                tracestate: own.tracestate ?? stashed?.tracestate,
+                sentTimestamp: own.sentTimestamp ?? stashed?.sentTimestamp,
+                receiveCount: own.receiveCount ?? stashed?.receiveCount,
+                messageId: own.messageId ?? stashed?.messageId,
+            };
+        }
+        catch {
+            meta = undefined;
+        }
+    }
+    const attributes = {
         'messaging.system': 'aws_sqs',
+        'messaging.operation.type': 'process',
+        'messaging.destination.name': ref.resourceName ?? queue,
         ...(ref.resourceArn ? { 'aws.resourceArn': ref.resourceArn } : {}),
         ...(ref.region ? { 'aws.region': ref.region } : {}),
-    });
+    };
+    if (meta?.messageId)
+        attributes['messaging.message.id'] = meta.messageId;
+    if (meta?.sentTimestamp !== undefined)
+        attributes['messaging.message.receive.latency'] = Math.max(0, Date.now() - meta.sentTimestamp);
+    if (meta?.receiveCount !== undefined)
+        attributes['messaging.message.retry.count'] = Math.max(0, meta.receiveCount - 1);
+    const remote = metaContext(meta);
+    const current = core.currentContext();
+    const name = `SQS process ${ref.resourceName ?? queue}`;
+    let span;
+    if (remote && current?.traceId !== remote.traceId) {
+        // Lote de mensagens de produtores diferentes: a invocação fica no próprio trace, como link.
+        if (current)
+            attributes.links = [{ traceId: current.traceId, spanId: current.spanId }];
+        span = core.startRemoteRoot('custom', name, attributes, remote);
+    }
+    else {
+        span = core.startSpan('custom', name, attributes);
+    }
     const started = performance.now();
     let failed = false;
     try {