fg-tracker-sdk 0.9.0 → 0.11.0

package/dist/tracker.js

@@ -1,14 +1,27 @@
+import { randomBytes } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import { EventLoopMonitor } from './event-loop.js';
-import { als, formatTraceparent, newSpanId, newTraceId, TRACEPARENT_HEADER } from './context.js';
+import { als, newSpanId, newTraceId, traceContextHeaders } from './context.js';
 import { toSpanError } from './normalize.js';
-import { DEFAULT_SCRUB_FIELDS, matchesAny, scrubAttributes } from './scrub.js';
+import { DEFAULT_SCRUB_FIELDS, matchesAny, scrubAttributes, testPattern } from './scrub.js';
 import { API_KEY_HEADER, DEFAULT_ENDPOINT, readEnv } from './constants.js';
+import { registerExitFlush } from './exit-hooks.js';
 import { InfraAggregator } from './infra/aggregator.js';
+import { byteLength, DEFAULT_MAX_BODY_BYTES, DEFAULT_REQUEST_TIMEOUT_MS, fitRecord, HttpSender, MIN_BODY_BYTES, safeStringify, Deadlines, truncateText, } from './transport.js';
 const DEFAULT_FLUSH_INTERVAL_MS = 2000;
 const DEFAULT_MAX_BATCH = 200;
 const DEFAULT_MAX_QUEUE = 5000;
+/** Teto de memória da fila de spans (JSON já serializado). */
+const DEFAULT_MAX_QUEUE_BYTES = 32 * 1024 * 1024;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
 const MAX_SPANS_PER_REQUEST = 1000;
+/**
+ * `attributes` e `error` acima de 64 KiB (JSON) fazem a API recusar o span
+ * (`attributes_too_large`/`error_too_large`, CONTRATO.md §4): o SDK corta antes, com margem.
+ */
+const MAX_SPAN_FIELD_BYTES = 60 * 1024;
+/** Raízes locais não amostradas com erro num descendente, guardadas até fecharem (só com `sendUnsampledErrors`). */
+const MAX_KEPT_ROOTS = 1000;
 /** Limites de agregados de infra (CONTRATO.md §27.4: ≤ 500 por requisição). */
 const MAX_INFRA_PER_REQUEST = 500;
 const MAX_INFRA_PENDING = 2000;
@@ -66,6 +79,15 @@ export function resolveOptions(options) {
         flushIntervalMs: Math.max(100, options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS),
         maxBatchSize: Math.max(1, options.maxBatchSize ?? DEFAULT_MAX_BATCH),
         maxQueueSize: Math.max(10, options.maxQueueSize ?? DEFAULT_MAX_QUEUE),
+        maxQueueBytes: Math.max(1024 * 1024, options.maxQueueBytes ?? DEFAULT_MAX_QUEUE_BYTES),
+        maxBatchBytes: Math.min(DEFAULT_MAX_BODY_BYTES, Math.max(MIN_BODY_BYTES, options.maxBatchBytes ?? DEFAULT_MAX_BODY_BYTES)),
+        requestTimeoutMs: Math.max(100, options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS),
+        shutdownTimeoutMs: Math.max(0, options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS),
+        // Com `fetch` próprio o corpo continua string (compatível com quem lê `init.body`), salvo pedido explícito.
+        compression: options.compression ?? (options.fetch ? 'none' : 'gzip'),
+        exitHooks: options.exitHooks ?? true,
+        sendUnsampledErrors: options.sendUnsampledErrors ?? false,
+        respectUpstreamSampling: options.respectUpstreamSampling ?? true,
         enabled: (options.enabled ?? true) && Boolean(options.apiKey),
         debug: options.debug ?? false,
         fetch: options.fetch ?? globalThis.fetch,
@@ -84,7 +106,7 @@ export function shouldPropagate(targets, url) {
         return false;
     return targets.some((target) => {
         if (target instanceof RegExp)
-            return target.test(url.href);
+            return testPattern(target, url.href);
         const pattern = target.trim();
         if (!pattern)
             return false;
@@ -97,20 +119,52 @@ export function shouldPropagate(targets, url) {
  * Núcleo do tracker: constrói spans, mantém a fila e faz o envio em lote.
  * As integrações (express, pg, next, fetch) ficam em arquivos separados e só
  * usam `startSpan` / `runInSpan`.
+ *
+ * Envio (CONTRATO.md §4.3): lotes limitados por bytes (`maxBatchBytes`) e por 1000 spans, uma
+ * requisição por vez, timeout de 10 s, backoff exponencial com jitter e `Retry-After` em
+ * rede/408/429/5xx, 413 divide o lote, outro 4xx descarta. Spans recusados num 202 parcial não
+ * são reenviados (a recusa se repetiria); agregados de infra em `retryableIds` voltam para a fila.
  */
 export class TrackerCore {
     options;
     queue = [];
+    queueBytes = 0;
     timer = null;
     flushing = null;
     warnedFailure = false;
+    warnedRejected = false;
     stopped = false;
+    /** Prazo do encerramento em andamento (epoch ms): nenhum envio passa dele. */
+    /** Prazos de encerramento ativos; vale o menor (`deadline`). */
+    deadlines = new Deadlines();
+    get deadline() {
+        return this.deadlines.current;
+    }
+    /** Spans descartados por limite de fila ou por 4xx desde o último aviso. */
+    dropped = 0;
+    sender;
+    /** Teto atual do corpo: começa em `maxBatchBytes` e cai pela metade a cada 413. */
+    batchBytes;
+    /** Teto de itens por lote: só cai quando um 413 chega com o teto de bytes já no mínimo. */
+    batchItems = Number.POSITIVE_INFINITY;
+    /** Enfileiramentos desde a última tentativa de envio na saída do processo. */
+    enqueuedSinceExit = 0;
+    unregisterExit;
+    /**
+     * Raízes locais (por `spanId`) de traces não amostrados em que um descendente falhou: quando
+     * fecham, também são enviadas (`sendUnsampledErrors`). A chave é a raiz, não o trace: duas
+     * requisições do mesmo trace distribuído têm raízes locais diferentes.
+     */
+    keptRoots = new Set();
     /** Spans ainda abertos, por spanId — permite `currentSpan()` a partir do contexto assíncrono. */
     active = new Map();
     /** Agregados de infra (nunca amostrados); `null` quando `infra.enabled === false`. */
     infra;
     /** Agregados já fechados aguardando envio (retentativa após falha). */
     infraPending = [];
+    /** Identidade dos agregados deste processo: `<emissor>:<sequência>` (dedupe no servidor). */
+    emitterId = randomBytes(8).toString('hex');
+    infraSeq = 0;
     /** A janela de infra venceu: o próximo flush fecha o agregador e envia junto dos spans. */
     infraDue = false;
     infraTimer = null;
@@ -124,10 +178,26 @@ export class TrackerCore {
     eventLoop;
     constructor(options) {
         this.options = resolveOptions(options);
+        this.batchBytes = this.options.maxBatchBytes;
+        this.sender = new HttpSender({
+            fetch: (input, init) => this.options.fetch(input, init),
+            url: `${this.options.endpoint}/v1/ingest`,
+            headers: { [API_KEY_HEADER]: this.options.apiKey },
+            timeoutMs: this.options.requestTimeoutMs,
+            compression: this.options.compression,
+        });
         this.eventLoop = this.options.enabled && this.options.measureEventLoopLag ? new EventLoopMonitor() : null;
         this.infra =
-            this.options.enabled && this.options.infraEnabled ? new InfraAggregator({ onRecord: () => this.ensureInfraTimer() }) : null;
+            this.options.enabled && this.options.infraEnabled
+                ? new InfraAggregator({
+                    onRecord: () => {
+                        this.enqueuedSinceExit += 1;
+                        this.ensureInfraTimer();
+                    },
+                })
+                : null;
         if (!this.options.enabled) {
+            this.unregisterExit = () => undefined;
             if (!options.apiKey && (options.enabled ?? true)) {
                 console.warn('[fg-tracker] apiKey ausente: tracker desabilitado.');
             }
@@ -139,10 +209,18 @@ export class TrackerCore {
         // Não segura o processo vivo só por causa do timer.
         if (typeof this.timer === 'object' && this.timer && 'unref' in this.timer)
             this.timer.unref();
+        this.unregisterExit = this.options.exitHooks ? registerExitFlush(this) : () => undefined;
     }
     get enabled() {
         return this.options.enabled && !this.stopped;
     }
+    /** Spans aguardando envio. */
+    get queueSize() {
+        return this.queue.length;
+    }
+    get exitTimeoutMs() {
+        return this.options.shutdownTimeoutMs;
+    }
     currentContext() {
         return als.getStore();
     }
@@ -153,11 +231,23 @@ export class TrackerCore {
         const parentSpanId = parentCtx?.spanId ?? null;
         const attrs = this.decorate(attributes);
         // Amostragem: decidida uma vez por trace (raiz) e herdada pelos filhos.
-        const sampled = parentCtx ? parentCtx.sampled !== false : this.decideSampling({ kind, name, attributes: attrs });
-        const span = new ActiveSpanImpl(this, traceId, newSpanId(), parentSpanId, kind, name, attrs, sampled);
+        // Excluído por `ignoreTransactions` (raiz ou herdado): nunca enviado, nem por `sendUnsampledErrors`.
+        // Decidido uma vez e reaproveitado pela amostragem.
+        const ignored = parentCtx ? parentCtx.ignored === true : matchesAny(name, this.options.ignoreTransactions);
+        const sampled = parentCtx ? parentCtx.sampled !== false : !ignored && this.decideSampling({ kind, name, attributes: attrs }, true);
+        const spanId = newSpanId();
+        const localRootId = parentCtx ? (parentCtx.localRootId ?? this.localRootOf(parentCtx.spanId)) : spanId;
+        const span = new ActiveSpanImpl(this, traceId, spanId, parentSpanId, kind, name, attrs, sampled, ignored, localRootId);
+        if (parentCtx?.traceState)
+            span.traceState = parentCtx.traceState;
         this.active.set(span.spanId, span);
         return span;
     }
+    /** Raiz local de um span ainda aberto (sobe pelos pais abertos); senão o próprio id. */
+    localRootOf(spanId) {
+        const open = this.active.get(spanId);
+        return open ? open.localRootId : spanId;
+    }
     decorate(attributes) {
         const attrs = { ...attributes };
         if (this.options.serviceName && attrs.serviceName === undefined)
@@ -169,11 +259,14 @@ export class TrackerCore {
         // Dentro de uma Lambda, todo span diz de qual função veio: o diagrama liga as chamadas (Neon, R2, APIs) à função certa.
         if (LAMBDA_FUNCTION_NAME && attrs['faas.name'] === undefined)
             attrs['faas.name'] = LAMBDA_FUNCTION_NAME;
+        // Semconv OTel em paralelo ao atributo histórico (aditivo; `environment` continua sendo o lido pela API).
+        if (typeof attrs.environment === 'string' && attrs['deployment.environment.name'] === undefined)
+            attrs['deployment.environment.name'] = attrs.environment;
         return attrs;
     }
     /** `ignoreTransactions` → nunca; `tracesSampler` → fração/boolean; senão `tracesSampleRate`. */
-    decideSampling(context) {
-        if (matchesAny(context.name, this.options.ignoreTransactions))
+    decideSampling(context, exclusionChecked = false) {
+        if (!exclusionChecked && matchesAny(context.name, this.options.ignoreTransactions))
             return false;
         let rate = this.options.tracesSampleRate;
         if (this.options.tracesSampler) {
@@ -195,13 +288,20 @@ export class TrackerCore {
     /**
      * Continua um trace recebido de outro serviço: mesmo `traceId`, mas o span nasce como
      * raiz local (`parentSpanId` null) e guarda o pai remoto em `attributes.remoteParentSpanId`,
-     * para as métricas por requisição continuarem contando este serviço.
+     * para as métricas por requisição continuarem contando este serviço. Não herda o contexto
+     * assíncrono atual: cada mensagem de um lote tem o próprio pai remoto.
+     * A flag `00` do `traceparent` vale aqui, salvo `respectUpstreamSampling: false`.
      */
     startRemoteRoot(kind, name, attributes, remote) {
         const attrs = this.decorate({ ...attributes, remoteParentSpanId: remote.spanId });
         // A decisão do serviço a montante (flag do traceparent) vale aqui, salvo `ignoreTransactions`.
-        const sampled = remote.sampled === false ? false : this.decideSampling({ kind, name, attributes: attrs, parentSampled: remote.sampled });
-        const span = new ActiveSpanImpl(this, remote.traceId, newSpanId(), null, kind, name, attrs, sampled);
+        const ignored = matchesAny(name, this.options.ignoreTransactions);
+        const upstreamDropped = remote.sampled === false && this.options.respectUpstreamSampling;
+        const sampled = upstreamDropped || ignored ? false : this.decideSampling({ kind, name, attributes: attrs, parentSampled: remote.sampled }, true);
+        const spanId = newSpanId();
+        const span = new ActiveSpanImpl(this, remote.traceId, spanId, null, kind, name, attrs, sampled, ignored, spanId);
+        if (remote.traceState)
+            span.traceState = remote.traceState;
         this.active.set(span.spanId, span);
         return span;
     }
@@ -248,14 +348,44 @@ export class TrackerCore {
     /** Headers de propagação para o contexto corrente. */
     traceHeaders() {
         const ctx = als.getStore();
-        return ctx ? { [TRACEPARENT_HEADER]: formatTraceparent(ctx) } : {};
+        return ctx ? traceContextHeaders(ctx) : {};
     }
     /** Chamado por ActiveSpanImpl.end(): amostragem, ignoreErrors, scrubbing e beforeSend. */
     finishSpan(span, payload) {
         this.active.delete(span.spanId);
-        if (!span.sampled)
+        if (span.sampled) {
+            this.emit(payload);
             return;
-        this.emit(payload);
+        }
+        if (!this.options.sendUnsampledErrors || span.ignored)
+            return;
+        // Trace não amostrado: só o que falhou (e a raiz local dele, que fecha depois) é enviado.
+        // O que já fechou antes do erro foi descartado e não volta.
+        if (this.isFailure(payload)) {
+            if (span.parentSpanId !== null)
+                this.keepRoot(span.localRootId);
+            else
+                this.keptRoots.delete(span.spanId);
+            this.emit(markKeptByError(payload));
+        }
+        else if (span.parentSpanId === null && this.keptRoots.delete(span.spanId)) {
+            this.emit(markKeptByError(payload));
+        }
+    }
+    isFailure(payload) {
+        if ((payload.statusCode ?? 0) >= 500)
+            return true;
+        if (!payload.error)
+            return false;
+        return !matchesAny(`${payload.error.name}: ${payload.error.message}`, this.options.ignoreErrors);
+    }
+    keepRoot(localRootId) {
+        this.keptRoots.add(localRootId);
+        if (this.keptRoots.size > MAX_KEPT_ROOTS) {
+            const oldest = this.keptRoots.values().next().value;
+            if (oldest !== undefined)
+                this.keptRoots.delete(oldest);
+        }
     }
     /**
      * Registra um span que já terminou, sem ter existido um `ActiveSpanImpl`
@@ -267,9 +397,14 @@ export class TrackerCore {
      * nada vira trace órfão.
      */
     recordSpan(input) {
-        if (!this.enabled || input.parent.sampled === false)
+        if (!this.enabled)
+            return;
+        if (input.parent.ignored === true)
+            return;
+        const unsampled = input.parent.sampled === false;
+        if (unsampled && (input.error === undefined || !this.options.sendUnsampledErrors))
             return;
-        this.emit({
+        const payload = {
             traceId: input.parent.traceId,
             spanId: newSpanId(),
             parentSpanId: input.parent.spanId,
@@ -283,7 +418,14 @@ export class TrackerCore {
             durationMs: input.durationMs,
             attributes: this.decorate(input.attributes ?? {}),
             error: input.error === undefined ? null : toSpanError(input.error),
-        });
+        };
+        if (!unsampled) {
+            this.emit(payload);
+        }
+        else if (this.isFailure(payload)) {
+            this.keepRoot(input.parent.localRootId ?? this.localRootOf(input.parent.spanId));
+            this.emit(markKeptByError(payload));
+        }
     }
     /** ignoreErrors, scrubbing e beforeSend antes de entrar na fila. */
     emit(payload) {
@@ -291,8 +433,16 @@ export class TrackerCore {
         if (out.error && matchesAny(`${out.error.name}: ${out.error.message}`, this.options.ignoreErrors)) {
             out = { ...out, error: null, attributes: { ...out.attributes, ignoredError: out.error.name } };
         }
-        if (this.options.scrubFields.length > 0)
-            out = { ...out, attributes: scrubAttributes(out.attributes, this.options.scrubFields) };
+        if (this.options.scrubFields.length > 0) {
+            try {
+                out = { ...out, attributes: scrubAttributes(out.attributes, this.options.scrubFields) };
+            }
+            catch (err) {
+                this.dropped += 1;
+                this.warnOnce(`span descartado: falha ao limpar atributos (${err?.message ?? err})`);
+                return;
+            }
+        }
         if (this.options.beforeSend) {
             try {
                 const result = this.options.beforeSend(out);
@@ -308,22 +458,40 @@ export class TrackerCore {
     }
     /** Executa `fn` com `span` como contexto pai das operações internas. */
     runInSpan(span, fn) {
-        return als.run({ traceId: span.traceId, spanId: span.spanId, sampled: span.sampled }, fn);
+        return als.run(span.context(), fn);
     }
     enqueue(span) {
         if (!this.enabled)
             return;
-        this.queue.push(span);
-        if (this.queue.length > this.options.maxQueueSize) {
-            // Descarta os mais antigos para não crescer sem limite.
-            this.queue.splice(0, this.queue.length - this.options.maxQueueSize);
+        let item;
+        try {
+            item = serializeSpan(span);
+        }
+        catch (err) {
+            // Roda no `span.end()`, dentro da operação da aplicação: nunca lança para ela.
+            this.dropped += 1;
+            this.warnOnce(`span descartado: não foi possível serializar (${err?.message ?? err})`);
+            return;
         }
+        this.queue.push(item);
+        this.queueBytes += item.bytes;
+        this.enqueuedSinceExit += 1;
+        this.trimQueue();
         if (this.queue.length >= this.options.maxBatchSize)
             void this.flush(false);
     }
+    /** Acima dos limites (spans ou bytes), descarta os mais antigos para não crescer sem limite. */
+    trimQueue() {
+        while (this.queue.length > 1 && (this.queue.length > this.options.maxQueueSize || this.queueBytes > this.options.maxQueueBytes)) {
+            const removed = this.queue.shift();
+            this.queueBytes -= removed.bytes;
+            this.dropped += 1;
+        }
+    }
     /**
      * Envia a fila. `includeInfra` (default `true`) também fecha a janela de infra e envia os
      * agregados no mesmo lote; o timer de spans chama com `false` para respeitar a janela de 60 s/5 s.
+     * Não espera o backoff: em backoff, volta na hora e o próximo flush tenta.
      */
     async flush(includeInfra = true) {
         if (!this.options.enabled)
@@ -338,41 +506,192 @@ export class TrackerCore {
             this.infraDue = false;
             return;
         }
-        this.flushing = this.doFlush().finally(() => {
+        this.flushing = this.drain(false).finally(() => {
             this.flushing = null;
         });
         return this.flushing;
     }
+    /**
+     * Envia o que der até `deadline`, sem esperar backoff (fim de invocação da Lambda). Aborta a
+     * requisição em andamento no prazo: nada fica pendurado no congelamento do ambiente.
+     */
+    async flushUntil(deadline) {
+        if (!this.options.enabled)
+            return;
+        const release = this.deadlines.add(deadline);
+        this.sender.abortAt(this.deadline ?? deadline);
+        try {
+            await this.flush(true);
+        }
+        finally {
+            release();
+        }
+    }
     hasInfraToSend() {
         return this.infraPending.length > 0 || (this.infraDue && Boolean(this.infra?.hasData()));
     }
-    async doFlush() {
+    /**
+     * Laço de envio. `waitBackoff` (encerramento) espera o backoff enquanto couber no prazo;
+     * sem ele, uma falha devolve o lote à fila e encerra o laço.
+     */
+    async drain(waitBackoff) {
         for (;;) {
             if (this.infraDue && this.infra) {
                 this.infraDue = false;
                 if (this.infra.hasData())
                     this.pushInfraPending(this.infra.drain());
             }
-            const batch = this.queue.splice(0, MAX_SPANS_PER_REQUEST);
-            const infra = this.infraPending.splice(0, MAX_INFRA_PER_REQUEST);
-            if (batch.length === 0 && infra.length === 0)
+            if (this.queue.length === 0 && this.infraPending.length === 0)
+                return;
+            const now = Date.now();
+            if (this.deadline !== null && now >= this.deadline)
+                return;
+            const wait = this.sender.waitMs(now);
+            if (wait > 0) {
+                if (!waitBackoff || this.deadline === null || now + wait >= this.deadline)
+                    return;
+                await this.deadlines.sleep(wait);
+                continue;
+            }
+            const batch = this.takeBatch();
+            const result = await this.sender.post(batch.body, this.deadline ?? undefined);
+            if (!this.handleResult(batch, result) && !waitBackoff)
                 return;
-            const ok = await this.send(batch, infra);
-            if (!ok) {
-                // Devolve para a frente da fila e tenta no próximo flush.
-                this.queue.unshift(...batch);
-                if (this.queue.length > this.options.maxQueueSize) {
-                    this.queue.splice(0, this.queue.length - this.options.maxQueueSize);
+        }
+    }
+    /**
+     * Monta o próximo lote: agregados (até 500) e depois spans (até 1000), todos dentro do teto de
+     * bytes e do teto de itens (este só cai depois de 413 com o teto de bytes no mínimo). Sempre leva
+     * pelo menos um item.
+     */
+    takeBatch() {
+        // Tamanho exato do corpo de `buildIngestBody`: `{"traces":[` + grupos + `]` + `,"infra":[…]` + `}`.
+        let bytes = 13;
+        let items = 0;
+        const fits = (size) => items === 0 || (bytes + size <= this.batchBytes && items < this.batchItems);
+        const infraJsons = [];
+        while (infraJsons.length < this.infraPending.length && infraJsons.length < MAX_INFRA_PER_REQUEST) {
+            const json = safeStringify(this.infraPending[infraJsons.length]);
+            // Primeiro agregado: `,"infra":[` + json + `]`; os seguintes: `,` + json.
+            const size = byteLength(json) + (infraJsons.length === 0 ? 11 : 1);
+            if (!fits(size))
+                break;
+            bytes += size;
+            items += 1;
+            infraJsons.push(json);
+        }
+        const infra = this.infraPending.splice(0, infraJsons.length);
+        const traces = new Set();
+        let count = 0;
+        while (count < this.queue.length && count < MAX_SPANS_PER_REQUEST) {
+            const next = this.queue[count];
+            // Span novo num trace já presente: `,<json>`; trace novo: `,{"traceId":"…","spans":[<json>]}`.
+            const size = traces.has(next.traceId) ? next.bytes + 1 : next.bytes + byteLength(JSON.stringify(next.traceId)) + 26;
+            if (!fits(size))
+                break;
+            bytes += size;
+            items += 1;
+            traces.add(next.traceId);
+            count += 1;
+        }
+        const spans = this.queue.splice(0, count);
+        for (const span of spans)
+            this.queueBytes -= span.bytes;
+        const body = buildIngestBody(spans, infraJsons.length > 0 ? `[${infraJsons.join(',')}]` : '');
+        return { spans, infra, body, bytes: byteLength(body) };
+    }
+    /** Aplica o resultado do envio. Devolve `false` quando o lote voltou para a fila (backoff). */
+    handleResult(batch, result) {
+        switch (result.type) {
+            case 'ok':
+                if (this.warnedFailure) {
+                    this.warnedFailure = false;
+                    if (this.options.debug)
+                        console.info('[fg-tracker] envio restabelecido.');
                 }
-                if (infra.length > 0) {
-                    this.infraPending.unshift(...infra);
-                    this.trimInfraPending();
+                if (this.options.debug) {
+                    console.info(`[fg-tracker] enviados ${batch.spans.length} spans${batch.infra.length > 0 ? ` e ${batch.infra.length} agregados de infra` : ''} (${batch.bytes} bytes).`);
                 }
-                return;
+                if (this.readIngestResponse(batch, result.body)) {
+                    // Agregados com falha transitória na API (banco): voltam para a fila e esperam o
+                    // backoff, que continua crescendo enquanto a falha durar (o 2xx não zera a sequência).
+                    this.sender.noteFailure({ type: 'retry', status: result.status, retryAfterMs: null, reason: 'infra retryable' });
+                    return false;
+                }
+                this.sender.noteSuccess();
+                return true;
+            case 'too_large': {
+                const items = batch.spans.length + batch.infra.length;
+                if (items <= 1) {
+                    this.dropped += batch.spans.length;
+                    this.warnOnce(`ingest respondeu 413 para um item de ${batch.bytes} bytes (descartado).`);
+                    return true;
+                }
+                // Divide: o mesmo lote volta para a fila e sai em pedaços de metade do tamanho (spans e
+                // agregados contam). Abaixo do mínimo de bytes, divide pela metade em número de itens: cada
+                // 413 encolhe o lote, então o laço termina, e só um item sozinho acima do limite se perde.
+                const half = Math.floor(batch.bytes / 2);
+                if (half >= MIN_BODY_BYTES)
+                    this.batchBytes = Math.min(this.batchBytes, half);
+                else
+                    this.batchItems = Math.max(1, Math.min(this.batchItems, Math.floor(items / 2)));
+                this.requeue(batch);
+                return true;
             }
+            case 'rejected':
+                // 4xx = configuração (chave inválida, payload malformado): reenviar daria o mesmo erro.
+                this.sender.noteSuccess();
+                this.dropped += batch.spans.length;
+                this.warnOnce(`ingest respondeu ${result.status} (lote descartado)`);
+                return true;
+            case 'retry': {
+                const delay = this.sender.noteFailure(result);
+                this.warnOnce(`falha ao enviar para ${this.options.endpoint}/v1/ingest: ${result.reason} (nova tentativa em ${Math.round(delay / 1000)} s)`);
+                this.requeue(batch);
+                return false;
+            }
+        }
+    }
+    /** Devolve o lote para a frente da fila (os limites de memória continuam valendo). */
+    requeue(batch) {
+        this.queue.unshift(...batch.spans);
+        for (const span of batch.spans)
+            this.queueBytes += span.bytes;
+        this.trimQueue();
+        if (batch.infra.length > 0) {
+            this.infraPending.unshift(...batch.infra);
+            this.trimInfraPending();
+        }
+    }
+    /**
+     * 202 da ingestão: `live`/`liveIntervalMs` (infra ao vivo), spans recusados (não reenvia: a
+     * recusa se repetiria) e agregados de infra com falha transitória (`retryableIds`, reenvia só
+     * esses). Devolve `true` quando algum agregado voltou para a fila.
+     */
+    readIngestResponse(batch, body) {
+        if (!body || typeof body !== 'object')
+            return false;
+        const response = body;
+        if (typeof response.rejected === 'number' && response.rejected > 0 && !this.warnedRejected) {
+            this.warnedRejected = true;
+            const first = Array.isArray(response.errors) ? response.errors[0]?.reason : undefined;
+            console.warn(`[fg-tracker] a API recusou ${response.rejected} span(s)${typeof first === 'string' ? ` (ex.: ${first})` : ''}; recusas não são reenviadas.`);
         }
+        this.readLiveFlag(response);
+        const retryable = response.infra?.retryableIds;
+        if (!Array.isArray(retryable) || retryable.length === 0 || batch.infra.length === 0)
+            return false;
+        const ids = new Set(retryable.filter((id) => typeof id === 'string'));
+        const again = batch.infra.filter((aggregate) => aggregate.id !== undefined && ids.has(aggregate.id));
+        if (again.length === 0)
+            return false;
+        this.infraPending.unshift(...again);
+        this.trimInfraPending();
+        return true;
     }
     pushInfraPending(items) {
+        for (const item of items)
+            item.id ??= `${this.emitterId}:${++this.infraSeq}`;
         this.infraPending.push(...items);
         this.trimInfraPending();
     }
@@ -408,17 +727,8 @@ export class TrackerCore {
             this.infraTimer.unref();
     }
     /** Lê `live`/`liveIntervalMs` da resposta da ingestão (piggyback, sem chamada extra). */
-    async readLiveFlag(res) {
-        if (!this.infra || res.status === 204 || typeof res.json !== 'function')
-            return;
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            return;
-        }
-        if (!body || typeof body !== 'object')
+    readLiveFlag(body) {
+        if (!this.infra)
             return;
         const { live, liveIntervalMs } = body;
         if (typeof live !== 'boolean')
@@ -451,55 +761,61 @@ export class TrackerCore {
             return null;
         }
     }
-    async send(spans, infra = []) {
-        const byTrace = new Map();
-        for (const span of spans) {
-            const { traceId, ...rest } = span;
-            let list = byTrace.get(traceId);
-            if (!list) {
-                list = [];
-                byTrace.set(traceId, list);
-            }
-            list.push(rest);
-        }
-        const traces = [...byTrace].map(([traceId, s]) => ({ traceId, spans: s }));
-        // Sem agregados o body continua idêntico ao das versões anteriores.
-        const body = JSON.stringify(infra.length > 0 ? { traces, infra } : { traces });
-        try {
-            const res = await this.options.fetch(`${this.options.endpoint}/v1/ingest`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json', [API_KEY_HEADER]: this.options.apiKey },
-                body,
-            });
-            if (!res.ok) {
-                // 4xx = problema de configuração (chave inválida, payload rejeitado): não faz sentido reenviar.
-                const retry = res.status >= 500 || res.status === 429;
-                this.warnOnce(`ingest respondeu ${res.status}${retry ? ' (vai tentar de novo)' : ' (lote descartado)'}`);
-                return !retry;
-            }
-            if (this.warnedFailure) {
-                this.warnedFailure = false;
-                if (this.options.debug)
-                    console.info('[fg-tracker] envio restabelecido.');
-            }
-            await this.readLiveFlag(res);
-            if (this.options.debug) {
-                console.info(`[fg-tracker] enviados ${spans.length} spans em ${byTrace.size} traces${infra.length > 0 ? ` e ${infra.length} agregados de infra` : ''}.`);
-            }
-            return true;
-        }
-        catch (err) {
-            this.warnOnce(`falha ao enviar para ${this.options.endpoint}/v1/ingest: ${err?.message ?? err}`);
-            return false;
-        }
-    }
     warnOnce(message) {
         if (this.warnedFailure)
             return;
         this.warnedFailure = true;
         console.warn(`[fg-tracker] ${message}`);
     }
-    async shutdown() {
+    hasPendingForExit() {
+        if (!this.enabled)
+            return false;
+        // Um lote já saiu da fila e está em voo: a saída espera ele (até o prazo).
+        if (this.flushing)
+            return true;
+        return this.enqueuedSinceExit > 0 && (this.queue.length > 0 || this.hasInfraToSend() || this.infra?.hasData() === true);
+    }
+    /** Saída do processo sem `shutdown()` (`beforeExit`, SIGTERM/SIGINT): envia com prazo, sem parar o tracker. */
+    async flushForExit(deadline) {
+        this.enqueuedSinceExit = 0;
+        try {
+            await this.sendUntil(deadline);
+        }
+        catch {
+            /* a saída nunca lança */
+        }
+    }
+    /**
+     * Envia tudo o que der até `deadline`, esperando backoff/`Retry-After` quando cabe no prazo.
+     * A requisição em andamento é abortada no prazo.
+     */
+    async sendUntil(deadline) {
+        if (!this.options.enabled)
+            return;
+        const release = this.deadlines.add(deadline);
+        this.sender.abortAt(this.deadline ?? deadline);
+        try {
+            // Outro envio (flush, saída do processo) em andamento: espera, sem iniciar um segundo laço.
+            while (this.flushing)
+                await this.flushing;
+            if (this.infra?.hasData())
+                this.infraDue = true;
+            if (this.queue.length === 0 && !this.hasInfraToSend())
+                return;
+            this.flushing = this.drain(true).finally(() => {
+                this.flushing = null;
+            });
+            await this.flushing;
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Para os timers e envia o que restou em até `timeoutMs` (default `shutdownTimeoutMs`, 10 s).
+     * Com a API muda ou fora, volta no prazo; o que não saiu é descartado (e contado em `dropped`).
+     */
+    async shutdown(options = {}) {
         if (this.timer) {
             clearInterval(this.timer);
             this.timer = null;
@@ -518,10 +834,73 @@ export class TrackerCore {
             }
         }
         this.disposers.clear();
-        await this.flush(true);
+        this.unregisterExit();
+        const timeoutMs = Math.max(0, options.timeoutMs ?? this.options.shutdownTimeoutMs);
+        await this.sendUntil(Date.now() + timeoutMs);
+        if (this.queue.length > 0 && this.options.enabled) {
+            this.dropped += this.queue.length;
+            this.warnOnce(`encerrado com ${this.queue.length} span(s) sem enviar.`);
+        }
         this.stopped = true;
     }
 }
+/** Atributos do span enviado só porque falhou num trace não amostrado (`sendUnsampledErrors`). */
+function markKeptByError(span) {
+    return { ...span, attributes: { ...span.attributes, 'sampling.kept': 'error' } };
+}
+/** JSON do span (sem `traceId`), com `attributes`/`error` cortados abaixo do limite da API. */
+function serializeSpan(span) {
+    const { traceId, ...rest } = span;
+    let json = safeStringify(rest);
+    let bytes = byteLength(json);
+    // Só um span grande pode ter `attributes` ou `error` acima do limite: o resto não paga a checagem.
+    if (bytes > MAX_SPAN_FIELD_BYTES) {
+        json = safeStringify({ ...rest, attributes: fitRecord(rest.attributes ?? {}, MAX_SPAN_FIELD_BYTES), error: fitError(rest.error) });
+        bytes = byteLength(json);
+    }
+    return { traceId, json, bytes };
+}
+/**
+ * Corta `error` até o JSON serializado caber no limite (o servidor mede `JSON.stringify(error)`:
+ * aspas, barras e controles crescem ao escapar). Encolhe primeiro o stack, depois a mensagem, e
+ * confere o tamanho final a cada passo.
+ */
+function fitError(error) {
+    if (!error || byteLength(safeStringify(error)) <= MAX_SPAN_FIELD_BYTES)
+        return error;
+    const name = truncateText(String(error.name), 256);
+    const message = String(error.message);
+    const stack = typeof error.stack === 'string' ? error.stack : undefined;
+    let messageBytes = 8 * 1024;
+    let stackBytes = stack === undefined ? 0 : MAX_SPAN_FIELD_BYTES - 10 * 1024;
+    for (;;) {
+        const out = { name, message: truncateText(message, messageBytes), truncated: true };
+        if (stack !== undefined && stackBytes > 0)
+            out.stack = truncateText(stack, stackBytes);
+        if (byteLength(safeStringify(out)) <= MAX_SPAN_FIELD_BYTES)
+            return out;
+        if (stackBytes > 0)
+            stackBytes = stackBytes > 256 ? Math.floor(stackBytes / 2) : 0;
+        else if (messageBytes > 0)
+            messageBytes = messageBytes > 64 ? Math.floor(messageBytes / 2) : 0;
+        else
+            return { name: truncateText(name, 64), message: '', truncated: true };
+    }
+}
+/** `{"traces":[{"traceId":…,"spans":[…]}…]}` a partir do JSON já pronto de cada span. */
+function buildIngestBody(spans, infraJson) {
+    const groups = new Map();
+    for (const span of spans) {
+        const list = groups.get(span.traceId);
+        if (list)
+            list.push(span.json);
+        else
+            groups.set(span.traceId, [span.json]);
+    }
+    const traces = [...groups].map(([traceId, jsons]) => `{"traceId":${JSON.stringify(traceId)},"spans":[${jsons.join(',')}]}`).join(',');
+    // Sem agregados o body continua idêntico ao das versões anteriores.
+    return infraJson ? `{"traces":[${traces}],"infra":${infraJson}}` : `{"traces":[${traces}]}`;
+}
 export function userAttributes(user) {
     if (!user)
         return { 'user.id': undefined, 'user.email': undefined, 'user.name': undefined };
@@ -539,6 +918,8 @@ export class ActiveSpanImpl {
     parentSpanId;
     kind;
     sampled;
+    ignored;
+    localRootId;
     name;
     method = null;
     route = null;
@@ -548,13 +929,21 @@ export class ActiveSpanImpl {
     startedAt;
     startedPerf;
     ended = false;
-    constructor(core, traceId, spanId, parentSpanId, kind, name, attributes, sampled = true) {
+    /** `tracestate` herdado do serviço a montante (repassado na propagação). */
+    traceState;
+    constructor(core, traceId, spanId, parentSpanId, kind, name, attributes, sampled = true, 
+    /** Trace excluído por `ignoreTransactions`: nunca enviado (nem com `sendUnsampledErrors`). */
+    ignored = false, 
+    /** `spanId` da raiz local deste ramo (o próprio, quando o span é raiz local). */
+    localRootId = spanId) {
         this.core = core;
         this.traceId = traceId;
         this.spanId = spanId;
         this.parentSpanId = parentSpanId;
         this.kind = kind;
         this.sampled = sampled;
+        this.ignored = ignored;
+        this.localRootId = localRootId;
         this.name = name;
         this.attributes = attributes;
         this.startedAt = new Date();
@@ -566,6 +955,17 @@ export class ActiveSpanImpl {
     setAttribute(key, value) {
         this.attributes[key] = value;
     }
+    /** Contexto deste span para o `AsyncLocalStorage` e para a propagação. */
+    context() {
+        return {
+            traceId: this.traceId,
+            spanId: this.spanId,
+            sampled: this.sampled,
+            localRootId: this.localRootId,
+            ...(this.ignored ? { ignored: true } : {}),
+            ...(this.traceState ? { traceState: this.traceState } : {}),
+        };
+    }
     setError(err) {
         this.error = toSpanError(err);
     }
@@ -587,6 +987,13 @@ export class ActiveSpanImpl {
             this.core.closeRootSpan(this, this.startedPerf, endedPerf);
         const durationMs = Math.round((endedPerf - this.startedPerf) * 1000) / 1000;
         const endedAt = new Date(this.startedAt.getTime() + durationMs);
+        // Semconv OTel em paralelo às colunas `method`/`statusCode` (aditivo).
+        if (this.kind === 'http.server' || this.kind === 'http.client') {
+            if (this.method && this.attributes['http.request.method'] === undefined)
+                this.attributes['http.request.method'] = this.method;
+            if (this.statusCode !== null && this.attributes['http.response.status_code'] === undefined)
+                this.attributes['http.response.status_code'] = this.statusCode;
+        }
         this.core.finishSpan(this, {
             traceId: this.traceId,
             spanId: this.spanId,