fg-tracker-sdk 0.4.0 → 0.5.0

package/dist/infra/ecs.js

@@ -0,0 +1,154 @@
+import { als } from '../context.js';
+import { detectArchitecture } from './aggregator.js';
+const DEFAULT_INTERVAL_MS = 10_000;
+const MB = 1024 * 1024;
+async function getJson(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reporter de infraestrutura do processo. Em ECS/Fargate lê `/task` uma vez e `/task/stats`
+ * periodicamente → agregado `ecs_task` (CPU, memória, rede e heartbeat com o ARN da task).
+ */
+export function startInfraReporter(core, options = {}) {
+    const noop = { stop() { } };
+    const infra = core.infra;
+    const metadataUri = process.env.ECS_CONTAINER_METADATA_URI_V4?.trim();
+    if (!infra || !core.enabled || options.ecs === false || !metadataUri) {
+        if (core.options.debug && options.ecs !== false && !metadataUri) {
+            console.info('[fg-tracker] startInfraReporter: ECS_CONTAINER_METADATA_URI_V4 ausente; nada a reportar.');
+        }
+        return noop;
+    }
+    let stopped = false;
+    let ref = null;
+    let task = null;
+    let previousNet = null;
+    let previousCpu = null;
+    let running = false;
+    const loadTask = async () => {
+        if (ref)
+            return true;
+        task = await getJson(`${metadataUri}/task`);
+        if (!task?.TaskARN)
+            return false;
+        const region = task.TaskARN.split(':')[3] || process.env.AWS_REGION || undefined;
+        const family = task.Containers?.map((c) => c.Labels?.['com.amazonaws.ecs.task-definition-family']).find(Boolean);
+        const serviceName = process.env.ECS_SERVICE_NAME?.trim() || task.ServiceName || family || task.Family;
+        ref = { kind: 'ecs_task', resourceArn: task.TaskARN, resourceName: serviceName, region };
+        infra.learnAccount(task.TaskARN);
+        return true;
+    };
+    const tick = async () => {
+        if (stopped || running)
+            return;
+        running = true;
+        try {
+            if (!(await loadTask()) || !ref || !task)
+                return;
+            const stats = await getJson(`${metadataUri}/task/stats`);
+            const r = ref;
+            infra.last(r, 'taskArn', task.TaskARN);
+            if (task.Cluster)
+                infra.last(r, 'clusterArn', task.Cluster);
+            if (r.resourceName)
+                infra.last(r, 'serviceName', r.resourceName);
+            if (task.LaunchType)
+                infra.last(r, 'launchType', task.LaunchType);
+            infra.last(r, 'architecture', detectArchitecture());
+            const cpuLimit = typeof task.Limits?.CPU === 'number' && task.Limits.CPU > 0 ? task.Limits.CPU : undefined;
+            if (cpuLimit)
+                infra.last(r, 'cpuUnits', Math.round(cpuLimit * 1024));
+            if (typeof task.Limits?.Memory === 'number' && task.Limits.Memory > 0)
+                infra.last(r, 'memoryLimitMb', task.Limits.Memory);
+            if (!stats)
+                return;
+            let cores = 0;
+            let cpuMeasured = false;
+            let memoryBytes = 0;
+            const net = new Map();
+            let aggTotal = 0;
+            let aggSystem = 0;
+            let aggOnline = 0;
+            for (const container of Object.values(stats)) {
+                if (!container)
+                    continue;
+                const cpu = container.cpu_stats;
+                const pre = container.precpu_stats;
+                const online = cpu?.online_cpus || 1;
+                const total = cpu?.cpu_usage?.total_usage ?? 0;
+                const system = cpu?.system_cpu_usage ?? 0;
+                aggTotal += total;
+                aggSystem = Math.max(aggSystem, system);
+                aggOnline = Math.max(aggOnline, online);
+                const cpuDelta = total - (pre?.cpu_usage?.total_usage ?? 0);
+                const systemDelta = system - (pre?.system_cpu_usage ?? 0);
+                if (pre?.system_cpu_usage && systemDelta > 0 && cpuDelta >= 0) {
+                    cores += (cpuDelta / systemDelta) * online;
+                    cpuMeasured = true;
+                }
+                const mem = container.memory_stats;
+                if (typeof mem?.usage === 'number') {
+                    const cache = mem.stats?.cache ?? mem.stats?.inactive_file ?? mem.stats?.total_inactive_file ?? 0;
+                    memoryBytes += Math.max(0, mem.usage - cache);
+                }
+                // Em awsvpc os containers compartilham a ENI: deduplica por interface.
+                for (const [iface, counters] of Object.entries(container.networks ?? {})) {
+                    const current = net.get(iface) ?? { rx: 0, tx: 0 };
+                    net.set(iface, { rx: Math.max(current.rx, counters.rx_bytes ?? 0), tx: Math.max(current.tx, counters.tx_bytes ?? 0) });
+                }
+            }
+            if (!cpuMeasured && previousCpu && aggSystem > previousCpu.system) {
+                // precpu_stats vazio: usa a leitura anterior deste reporter.
+                cores = ((aggTotal - previousCpu.total) / (aggSystem - previousCpu.system)) * aggOnline;
+                cpuMeasured = cores >= 0;
+            }
+            previousCpu = { total: aggTotal, system: aggSystem };
+            if (cpuMeasured) {
+                const percent = cpuLimit ? (cores / cpuLimit) * 100 : cores * 100;
+                infra.max(r, 'cpuPercent', Math.round(percent * 100) / 100);
+            }
+            if (memoryBytes > 0)
+                infra.max(r, 'memoryMb', Math.round((memoryBytes / MB) * 100) / 100);
+            let rx = 0;
+            let tx = 0;
+            for (const counters of net.values()) {
+                rx += counters.rx;
+                tx += counters.tx;
+            }
+            if (previousNet && rx >= previousNet.rx && tx >= previousNet.tx) {
+                infra.add(r, 'networkRxBytes', rx - previousNet.rx);
+                infra.add(r, 'networkTxBytes', tx - previousNet.tx);
+            }
+            if (net.size > 0)
+                previousNet = { rx, tx };
+        }
+        catch (err) {
+            if (core.options.debug)
+                console.warn(`[fg-tracker] startInfraReporter: ${err?.message ?? err}`);
+        }
+        finally {
+            running = false;
+        }
+    };
+    const timer = als.exit(() => setInterval(() => void tick(), Math.max(1000, options.intervalMs ?? DEFAULT_INTERVAL_MS)));
+    timer.unref?.();
+    als.exit(() => void tick());
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        unregister();
+    };
+    const unregister = core.onShutdown(stop);
+    return { stop };
+}
+//# sourceMappingURL=ecs.js.map

package/dist/infra/ecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecs.js","sourceRoot":"","sources":["../../src/infra/ecs.ts"],"names":[],"mappings":"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"}

package/dist/infra/lambda.d.ts

@@ -0,0 +1,27 @@
+import type { TrackerCore } from '../tracker.js';
+/** Contexto mínimo da Lambda (tipo estrutural; sem `@types/aws-lambda`). */
+export interface LambdaContextLike {
+    awsRequestId?: string;
+    functionName?: string;
+    invokedFunctionArn?: string;
+    getRemainingTimeInMillis?: () => number;
+    [key: string]: unknown;
+}
+export type LambdaHandler<E = unknown, R = unknown, C extends LambdaContextLike = LambdaContextLike> = (event: E, context: C) => R | Promise<R>;
+export interface WrapLambdaOptions {
+    /** Tempo máximo esperando o `flush()` no fim da invocação. Default 1000 ms. */
+    flushTimeoutMs?: number;
+    /** Cria um span raiz `custom` por invocação (spans de AWS/db/fetch passam a formar um trace). Default `true`. */
+    span?: boolean;
+}
+/** Caminho do executável da camada `fg-tracker-lambda-extension`. */
+export declare const LAMBDA_EXTENSION_PATH = "/opt/extensions/fg-tracker-extension";
+export declare function hasLambdaExtension(): boolean;
+export declare function flushWithTimeout(core: TrackerCore, timeoutMs: number): Promise<void>;
+/**
+ * Envolve um handler async da Lambda. Sem a extensão do FG Tracker, aguarda o `flush()` (com timeout
+ * curto) ao fim de cada invocação para não perder spans no congelamento do ambiente; com a extensão,
+ * a fila sobrevive ao congelamento e é enviada no SIGTERM do encerramento.
+ */
+export declare function wrapLambdaHandler<E, R, C extends LambdaContextLike>(core: TrackerCore, handler: LambdaHandler<E, R, C>, options?: WrapLambdaOptions): LambdaHandler<E, R, C>;
+//# sourceMappingURL=lambda.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lambda.d.ts","sourceRoot":"","sources":["../../src/infra/lambda.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wBAAwB,CAAC,EAAE,MAAM,MAAM,CAAC;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,iBAAiB,GAAG,iBAAiB,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhJ,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iHAAiH;IACjH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,yCAAyC,CAAC;AAI5E,wBAAgB,kBAAkB,IAAI,OAAO,CAS5C;AAgBD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1F;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,iBAAiB,EACjE,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC/B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAiCxB"}

package/dist/infra/lambda.js

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs';
+/** Caminho do executável da camada `fg-tracker-lambda-extension`. */
+export const LAMBDA_EXTENSION_PATH = '/opt/extensions/fg-tracker-extension';
+let extensionDetected;
+export function hasLambdaExtension() {
+    if (extensionDetected === undefined) {
+        try {
+            extensionDetected = existsSync(LAMBDA_EXTENSION_PATH);
+        }
+        catch {
+            extensionDetected = false;
+        }
+    }
+    return extensionDetected;
+}
+let sigtermInstalled = false;
+/**
+ * Com a extensão registrada, a Lambda envia SIGTERM ao runtime no encerramento do ambiente:
+ * é a última chance de enviar a fila. Só instala quando ninguém mais trata SIGTERM.
+ */
+function installSigtermFlush(core, timeoutMs) {
+    if (sigtermInstalled || process.listenerCount('SIGTERM') > 0)
+        return;
+    sigtermInstalled = true;
+    process.once('SIGTERM', () => {
+        void flushWithTimeout(core, timeoutMs).finally(() => process.exit(0));
+    });
+}
+export async function flushWithTimeout(core, timeoutMs) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([core.flush(true).catch(() => undefined), timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+let coldStart = true;
+/**
+ * Envolve um handler async da Lambda. Sem a extensão do FG Tracker, aguarda o `flush()` (com timeout
+ * curto) ao fim de cada invocação para não perder spans no congelamento do ambiente; com a extensão,
+ * a fila sobrevive ao congelamento e é enviada no SIGTERM do encerramento.
+ */
+export function wrapLambdaHandler(core, handler, options = {}) {
+    const flushTimeoutMs = Math.max(50, options.flushTimeoutMs ?? 1000);
+    const withSpan = options.span ?? true;
+    return async function fgTrackerLambda(event, context) {
+        if (!core.enabled)
+            return handler(event, context);
+        const extension = hasLambdaExtension();
+        if (extension)
+            installSigtermFlush(core, flushTimeoutMs);
+        const functionName = context?.functionName ?? process.env.AWS_LAMBDA_FUNCTION_NAME ?? 'lambda';
+        const span = withSpan
+            ? core.startSpan('custom', `lambda ${functionName}`, {
+                'faas.name': functionName,
+                'faas.coldStart': coldStart,
+                ...(context?.awsRequestId ? { 'faas.requestId': context.awsRequestId } : {}),
+                ...(context?.invokedFunctionArn ? { 'aws.resourceArn': context.invokedFunctionArn } : {}),
+                ...(process.env.AWS_REGION ? { 'aws.region': process.env.AWS_REGION } : {}),
+            }, null)
+            : null;
+        coldStart = false;
+        try {
+            return await (span ? core.runInSpan(span, () => handler(event, context)) : handler(event, context));
+        }
+        catch (err) {
+            span?.setError(err);
+            throw err;
+        }
+        finally {
+            span?.end();
+            if (!extension)
+                await flushWithTimeout(core, flushTimeoutMs);
+        }
+    };
+}
+//# sourceMappingURL=lambda.js.map

package/dist/infra/lambda.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lambda.js","sourceRoot":"","sources":["../../src/infra/lambda.ts"],"names":[],"mappings":"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"}

package/dist/tracker.d.ts

@@ -1,4 +1,5 @@
 import { type SpanContext } from './context.js';
+import { InfraAggregator } from './infra/aggregator.js';
 import type { ActiveSpan, PropagationTargets, SamplingContext, Span, SpanError, SpanKind, TrackerOptions, UserRef } from './types.js';
 export interface ResolvedOptions {
     apiKey: string;
@@ -19,6 +20,8 @@ export interface ResolvedOptions {
     enabled: boolean;
     debug: boolean;
     fetch: typeof globalThis.fetch;
+    infraEnabled: boolean;
+    infraIdleIntervalMs: number;
 }
 /** Release detectada do ambiente (CONTRATO.md §15): `${serviceName}@${sha}` para SHAs de CI/hosting. */
 export declare function detectRelease(serviceName: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
@@ -40,6 +43,19 @@ export declare class TrackerCore {
     private stopped;
     /** Spans ainda abertos, por spanId — permite `currentSpan()` a partir do contexto assíncrono. */
     private readonly active;
+    /** Agregados de infra (nunca amostrados); `null` quando `infra.enabled === false`. */
+    readonly infra: InfraAggregator | null;
+    /** Agregados já fechados aguardando envio (retentativa após falha). */
+    private infraPending;
+    /** A janela de infra venceu: o próximo flush fecha o agregador e envia junto dos spans. */
+    private infraDue;
+    private infraTimer;
+    private infraTimerMs;
+    /** Última resposta da ingestão: há sessão de observação ativa no painel (§27.4). */
+    live: boolean;
+    liveIntervalMs: number;
+    /** Callbacks de encerramento (reporters, timers de pool). */
+    private readonly disposers;
     constructor(options: TrackerOptions);
     get enabled(): boolean;
     currentContext(): SpanContext | undefined;
@@ -65,8 +81,24 @@ export declare class TrackerCore {
     /** Executa `fn` com `span` como contexto pai das operações internas. */
     runInSpan<T>(span: ActiveSpanImpl, fn: () => T): T;
     enqueue(span: Span): void;
-    flush(): Promise<void>;
+    /**
+     * 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.
+     */
+    flush(includeInfra?: boolean): Promise<void>;
+    private hasInfraToSend;
     private doFlush;
+    private pushInfraPending;
+    /** Mesma política dos spans: acima do limite, descarta os agregados mais antigos. */
+    private trimInfraPending;
+    /** Intervalo atual da janela de infra: `liveIntervalMs` com o painel aberto, senão `idleIntervalMs`. */
+    infraIntervalMs(): number;
+    /** Arma (ou rearma, se o intervalo mudou) o timer que fecha a janela de infra. */
+    ensureInfraTimer(): void;
+    /** Lê `live`/`liveIntervalMs` da resposta da ingestão (piggyback, sem chamada extra). */
+    private readLiveFlag;
+    /** Registra uma função chamada no `shutdown()` (timers de reporters/pools). */
+    onShutdown(dispose: () => void): () => void;
     /** POST autenticado na API (ingest, check-ins, releases). Devolve a resposta ou `null` em falha de rede. */
     post(path: string, body: unknown, timeoutMs?: number): Promise<Response | null>;
     private send;

package/dist/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"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"}

package/dist/tracker.js

@@ -3,10 +3,17 @@ import { als, formatTraceparent, newSpanId, newTraceId, TRACEPARENT_HEADER } fro
 import { toSpanError } from './normalize.js';
 import { DEFAULT_SCRUB_FIELDS, matchesAny, scrubAttributes } from './scrub.js';
 import { API_KEY_HEADER, DEFAULT_ENDPOINT, readEnv } from './constants.js';
+import { InfraAggregator } from './infra/aggregator.js';
 const DEFAULT_FLUSH_INTERVAL_MS = 2000;
 const DEFAULT_MAX_BATCH = 200;
 const DEFAULT_MAX_QUEUE = 5000;
 const MAX_SPANS_PER_REQUEST = 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;
+const DEFAULT_INFRA_IDLE_INTERVAL_MS = 60_000;
+const DEFAULT_INFRA_LIVE_INTERVAL_MS = 5_000;
+const MIN_INFRA_INTERVAL_MS = 1_000;
 const RELEASE_ENV_VARS = [
     'VERCEL_GIT_COMMIT_SHA',
     'RAILWAY_GIT_COMMIT_SHA',
@@ -56,6 +63,8 @@ export function resolveOptions(options) {
         enabled: (options.enabled ?? true) && Boolean(options.apiKey),
         debug: options.debug ?? false,
         fetch: options.fetch ?? globalThis.fetch,
+        infraEnabled: options.infra?.enabled ?? true,
+        infraIdleIntervalMs: Math.max(MIN_INFRA_INTERVAL_MS, options.infra?.idleIntervalMs ?? DEFAULT_INFRA_IDLE_INTERVAL_MS),
     };
 }
 /** Decide se um destino recebe o `traceparent` (CONTRATO.md §16). */
@@ -89,8 +98,23 @@ export class TrackerCore {
     stopped = false;
     /** 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 = [];
+    /** A janela de infra venceu: o próximo flush fecha o agregador e envia junto dos spans. */
+    infraDue = false;
+    infraTimer = null;
+    infraTimerMs = 0;
+    /** Última resposta da ingestão: há sessão de observação ativa no painel (§27.4). */
+    live = false;
+    liveIntervalMs = DEFAULT_INFRA_LIVE_INTERVAL_MS;
+    /** Callbacks de encerramento (reporters, timers de pool). */
+    disposers = new Set();
     constructor(options) {
         this.options = resolveOptions(options);
+        this.infra =
+            this.options.enabled && this.options.infraEnabled ? new InfraAggregator({ onRecord: () => this.ensureInfraTimer() }) : null;
         if (!this.options.enabled) {
             if (!options.apiKey && (options.enabled ?? true)) {
                 console.warn('[fg-tracker] apiKey ausente: tracker desabilitado.');
@@ -98,7 +122,7 @@ export class TrackerCore {
             return;
         }
         this.timer = setInterval(() => {
-            void this.flush();
+            void this.flush(false);
         }, this.options.flushIntervalMs);
         // Não segura o processo vivo só por causa do timer.
         if (typeof this.timer === 'object' && this.timer && 'unref' in this.timer)
@@ -226,34 +250,123 @@ export class TrackerCore {
             this.queue.splice(0, this.queue.length - this.options.maxQueueSize);
         }
         if (this.queue.length >= this.options.maxBatchSize)
-            void this.flush();
+            void this.flush(false);
     }
-    async flush() {
+    /**
+     * 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.
+     */
+    async flush(includeInfra = true) {
         if (!this.options.enabled)
             return;
-        if (this.flushing)
-            return this.flushing;
-        if (this.queue.length === 0)
+        if (includeInfra && this.infra)
+            this.infraDue = true;
+        if (this.flushing) {
+            // Um envio em andamento pode já ter passado da checagem de infra: encadeia outro.
+            return includeInfra ? this.flushing.then(() => (this.hasInfraToSend() ? this.flush(true) : undefined)) : this.flushing;
+        }
+        if (this.queue.length === 0 && !this.hasInfraToSend()) {
+            this.infraDue = false;
             return;
+        }
         this.flushing = this.doFlush().finally(() => {
             this.flushing = null;
         });
         return this.flushing;
     }
+    hasInfraToSend() {
+        return this.infraPending.length > 0 || (this.infraDue && Boolean(this.infra?.hasData()));
+    }
     async doFlush() {
-        while (this.queue.length > 0) {
+        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 ok = await this.send(batch);
+            const infra = this.infraPending.splice(0, MAX_INFRA_PER_REQUEST);
+            if (batch.length === 0 && infra.length === 0)
+                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);
                 }
+                if (infra.length > 0) {
+                    this.infraPending.unshift(...infra);
+                    this.trimInfraPending();
+                }
                 return;
             }
         }
     }
+    pushInfraPending(items) {
+        this.infraPending.push(...items);
+        this.trimInfraPending();
+    }
+    /** Mesma política dos spans: acima do limite, descarta os agregados mais antigos. */
+    trimInfraPending() {
+        if (this.infraPending.length > MAX_INFRA_PENDING) {
+            this.infraPending.splice(0, this.infraPending.length - MAX_INFRA_PENDING);
+        }
+    }
+    /** Intervalo atual da janela de infra: `liveIntervalMs` com o painel aberto, senão `idleIntervalMs`. */
+    infraIntervalMs() {
+        return this.live ? this.liveIntervalMs : this.options.infraIdleIntervalMs;
+    }
+    /** Arma (ou rearma, se o intervalo mudou) o timer que fecha a janela de infra. */
+    ensureInfraTimer() {
+        if (!this.infra || !this.enabled)
+            return;
+        const interval = this.infraIntervalMs();
+        if (this.infraTimer && this.infraTimerMs === interval)
+            return;
+        if (this.infraTimer)
+            clearTimeout(this.infraTimer);
+        this.infraTimerMs = interval;
+        this.infraTimer = setTimeout(() => {
+            this.infraTimer = null;
+            void this.flush(true).finally(() => {
+                // Com painel aberto mantém o ritmo mesmo sem dados; ocioso, só rearma quando houver algo.
+                if (this.enabled && (this.live || this.infra?.hasData() || this.infraPending.length > 0))
+                    this.ensureInfraTimer();
+            });
+        }, interval);
+        if (typeof this.infraTimer === 'object' && this.infraTimer && 'unref' in this.infraTimer)
+            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')
+            return;
+        const { live, liveIntervalMs } = body;
+        if (typeof live !== 'boolean')
+            return;
+        const previousInterval = this.infraIntervalMs();
+        this.live = live;
+        if (typeof liveIntervalMs === 'number' && Number.isFinite(liveIntervalMs)) {
+            this.liveIntervalMs = Math.max(MIN_INFRA_INTERVAL_MS, liveIntervalMs);
+        }
+        if (this.infraIntervalMs() !== previousInterval || (live && !this.infraTimer))
+            this.ensureInfraTimer();
+    }
+    /** Registra uma função chamada no `shutdown()` (timers de reporters/pools). */
+    onShutdown(dispose) {
+        this.disposers.add(dispose);
+        return () => this.disposers.delete(dispose);
+    }
     /** POST autenticado na API (ingest, check-ins, releases). Devolve a resposta ou `null` em falha de rede. */
     async post(path, body, timeoutMs = 10_000) {
         try {
@@ -269,7 +382,7 @@ export class TrackerCore {
             return null;
         }
     }
-    async send(spans) {
+    async send(spans, infra = []) {
         const byTrace = new Map();
         for (const span of spans) {
             const { traceId, ...rest } = span;
@@ -280,7 +393,9 @@ export class TrackerCore {
             }
             list.push(rest);
         }
-        const body = JSON.stringify({ traces: [...byTrace].map(([traceId, s]) => ({ traceId, spans: s })) });
+        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',
@@ -298,8 +413,10 @@ export class TrackerCore {
                 if (this.options.debug)
                     console.info('[fg-tracker] envio restabelecido.');
             }
-            if (this.options.debug)
-                console.info(`[fg-tracker] enviados ${spans.length} spans em ${byTrace.size} traces.`);
+            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) {
@@ -318,7 +435,20 @@ export class TrackerCore {
             clearInterval(this.timer);
             this.timer = null;
         }
-        await this.flush();
+        if (this.infraTimer) {
+            clearTimeout(this.infraTimer);
+            this.infraTimer = null;
+        }
+        for (const dispose of this.disposers) {
+            try {
+                dispose();
+            }
+            catch {
+                /* encerramento nunca lança */
+            }
+        }
+        this.disposers.clear();
+        await this.flush(true);
         this.stopped = true;
     }
 }