fg-tracker-sdk 0.10.0 → 0.11.0

package/dist/infra/aws.d.ts

@@ -1,5 +1,6 @@
 import type { TrackerCore } from '../tracker.js';
 import type { InfraResourceRef } from './aggregator.js';
+import { ReceivedMessages } from './messaging.js';
 /**
  * Instrumentação do AWS SDK v3 por middleware (CONTRATO.md §27.8).
  * Tipos estruturais: o SDK não depende de `@aws-sdk/*`.
@@ -36,16 +37,57 @@ export declare function parseArn(arn: string): {
  * Também aceita um ARN pronto.
  */
 export declare function sqsQueueRef(queue: string, fallbackRegion?: string): InfraResourceRef;
+export interface AwsInstrumentationOptions {
+    /**
+     * Propaga o contexto do trace nas mensagens: `traceparent`/`tracestate` em `MessageAttributes`
+     * (SQS `SendMessage`/`SendMessageBatch`) e no `Detail` (EventBridge `PutEvents`), e pede esses
+     * atributos no `ReceiveMessage`. Default `true` (salvo `propagateTraceTo: false` no tracker).
+     */
+    propagation?: boolean;
+    /**
+     * Limite de bytes por mensagem SQS usado para decidir se o contexto cabe. Default 1 MiB (cota do
+     * SQS). Use o `MaximumMessageSize` da fila se ele for menor; mesmo sem isso, numa fila padrão,
+     * uma recusa por tamanho com o contexto é repetida sem ele. Em fila FIFO (`.fifo`), sem esta
+     * opção o contexto só vai em mensagens de até 1 KiB (o menor `MaximumMessageSize` possível):
+     * reenviar uma entrada recusada do lote depois das aceitas mudaria a ordem do grupo.
+     */
+    sqsMaxMessageBytes?: number;
+    /** Limite do pedido `PutEvents` (soma das entradas). Default 1 MiB. */
+    eventBridgeMaxRequestBytes?: number;
+}
+/** Mensagens recebidas por clients instrumentados deste tracker (contexto lido antes de retirar os atributos). */
+export declare function receivedMessages(core: TrackerCore): ReceivedMessages;
+/**
+ * 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 declare function isFifoQueue(queue: string): boolean;
 /**
  * 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 declare function instrumentAwsClient<T extends AwsClientLike>(core: TrackerCore, client: T): T;
+export declare function instrumentAwsClient<T extends AwsClientLike>(core: TrackerCore, client: T, options?: AwsInstrumentationOptions): T;
+/** Forma da mensagem aceita pelo `trackMessage`: record do evento da Lambda ou `Message` do AWS SDK. */
+export type QueueMessageLike = object;
+export interface TrackMessageOptions {
+    /**
+     * A mensagem processada (record do evento SQS da Lambda ou `Message` do `ReceiveMessage`): o
+     * processamento continua o trace do produtor (pai remoto da própria mensagem), com o atraso de
+     * fila e as tentativas. Sem ela, o processamento é medido só localmente.
+     */
+    record?: QueueMessageLike;
+}
 /**
  * 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 declare function trackQueueMessage<T>(core: TrackerCore, queue: string, fn: () => T | Promise<T>): Promise<T>;
+export declare function trackQueueMessage<T>(core: TrackerCore, queue: string, fn: () => T | Promise<T>, record?: QueueMessageLike): Promise<T>;
 //# sourceMappingURL=aws.d.ts.map

package/dist/infra/aws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aws.d.ts","sourceRoot":"","sources":["../../src/infra/aws.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAA8B,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEpF;;;GAGG;AAEH,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE;QACf,GAAG,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC/H,CAAC;IACF,MAAM,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7E;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE5J,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA2ED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAIlG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAgBpF;AAuPD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CA+E5F;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA0BjH"}
+{"version":3,"file":"aws.d.ts","sourceRoot":"","sources":["../../src/infra/aws.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAA8B,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,EAUL,gBAAgB,EAWjB,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AAEH,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE;QACf,GAAG,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC/H,CAAC;IACF,MAAM,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7E;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE5J,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA2ED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAIlG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAgBpF;AAuPD,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAID,kHAAkH;AAClH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,gBAAgB,CAOpE;AAoBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAYlD;AAqJD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAE,yBAA8B,GAAG,CAAC,CA0NrI;AAED,wGAAwG;AACxG,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CA0D5I"}

package/dist/infra/aws.js

@@ -1,3 +1,4 @@
+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 +361,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,6 +568,12 @@ 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) => {
@@ -401,22 +600,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 +608,189 @@ 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 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}`;
+            }
+            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 */
+                    }
+                }
+                return result;
+            }
+            catch (err) {
+                if (span) {
+                    span.statusCode = httpStatus(err);
+                    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 {
+                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 +798,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 {