@skediprof/telemetry 1.0.0 → 1.1.1

package/README.md

@@ -0,0 +1,200 @@
+# @skediprof/telemetry
+
+Biblioteca compartilhada de OpenTelemetry para os microserviços da Skedi.
+Encapsula o SDK do OTel e exporta **traces + métricas** via OTLP/HTTP
+diretamente para o New Relic (sem OTel Collector).
+
+```bash
+npm install @skediprof/telemetry
+```
+
+> Requer **Node.js >= 18**.
+
+---
+
+## Como os microserviços usam
+
+Cada serviço escolhe **um** dos dois padrões abaixo, conforme o runtime.
+
+### 1. Cloud Run / servidor persistente (`runtime: 'server'`)
+
+Chame `initTelemetry()` **no topo absoluto** do entrypoint, **antes** de
+qualquer `import` de Express, Firebase ou bibliotecas HTTP. A
+auto-instrumentação funciona via monkey-patching — se os módulos forem
+importados antes, os patches não se aplicam.
+
+```ts
+// index.ts — PRIMEIRA coisa do arquivo
+import { initTelemetry } from '@skediprof/telemetry';
+
+initTelemetry({
+  serviceName: 'skedi-students-imdb',
+  serviceVersion: process.env.SERVICE_VERSION,
+  runtime: 'server',
+});
+
+// só DEPOIS importe o resto
+import express from 'express';
+import { shutdownTelemetry } from '@skediprof/telemetry';
+
+const app = express();
+// ... suas rotas ...
+app.listen(8080);
+
+// flush dos dados pendentes no encerramento gracioso
+process.on('SIGTERM', async () => {
+  await shutdownTelemetry();
+  process.exit(0);
+});
+```
+
+### 2. Cloud Functions (`runtime: 'function'`)
+
+Use o wrapper `withTelemetry()`. Ele inicializa no cold start e faz **flush
+após cada invocação** (crítico em Functions — sem isso, dados se perdem
+quando a instância congela).
+
+```ts
+import { withTelemetry } from '@skediprof/telemetry';
+
+export const handler = withTelemetry(
+  { serviceName: 'ms-skedi-notifications', runtime: 'function' },
+  async (req, res) => {
+    // ... sua lógica ...
+    res.send('ok');
+  }
+);
+```
+
+Em JavaScript puro (ex: `whatsapp-bot-skedi`) o uso é idêntico com `require`:
+
+```js
+const { withTelemetry } = require('@skediprof/telemetry');
+
+exports.handler = withTelemetry(
+  { serviceName: 'whatsapp-bot-skedi', runtime: 'function' },
+  async (req, res) => { /* ... */ }
+);
+```
+
+---
+
+## Configuração (`TelemetryConfig`)
+
+| Campo | Tipo | Default | Descrição |
+|-------|------|---------|-----------|
+| `serviceName` | `string` | **(obrigatório)** | Nome do serviço; vira o *entity name* no New Relic. |
+| `serviceVersion` | `string` | `'0.0.0'` | Versão do serviço. |
+| `environment` | `string` | `NODE_ENV` ou `'production'` | `production` \| `staging` \| `development`. |
+| `runtime` | `'server' \| 'function'` | `'server'` | Estratégia de flush/shutdown. |
+| `apiKey` | `string` | `NEW_RELIC_LICENSE_KEY` | License key do New Relic. |
+| `otlpEndpoint` | `string` | `https://otlp.nr-data.net:4318` | Endpoint OTLP. |
+| `metricExportInterval` | `number` | `60000` (server) / `10000` (function) | Intervalo de export de métricas (ms). |
+| `autoInstrumentHttp` | `boolean` | `true` | Auto-instrumenta HTTP/Express. |
+| `autoInstrumentFirestore` | `boolean` | `true` | Auto-instrumenta Firestore/gRPC. |
+
+### Variáveis de ambiente
+
+| Variável | Efeito |
+|----------|--------|
+| `NEW_RELIC_LICENSE_KEY` | License key usada se `apiKey` não for passado. **Sem chave = telemetria desligada** (apenas avisa, não quebra). |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Sobrescreve o endpoint OTLP. |
+| `TELEMETRY_ENABLED=false` | Desativa **toda** a telemetria (nenhum SDK é carregado). |
+
+---
+
+## Métricas customizadas
+
+Convenção de nomes: **`skedi.<domínio>.<métrica>`** (ex: `skedi.classes.created`).
+
+```ts
+import { createCounter, createHistogram, createGauge } from '@skediprof/telemetry';
+
+const classesCreated = createCounter(
+  'skedi.classes.created',
+  'Total de aulas criadas'
+);
+classesCreated.add(1, { tenant: 'acme' });
+
+const apiLatency = createHistogram(
+  'skedi.api.latency',
+  'Latência das requisições da API',
+  'ms'
+);
+apiLatency.record(123, { route: '/students' });
+
+const queueDepth = createGauge(
+  'skedi.queue.depth',
+  'Mensagens pendentes na fila'
+);
+queueDepth.addCallback((result) => result.observe(getQueueSize()));
+```
+
+---
+
+## Correlação de logs com traces
+
+Use `getTraceContext()` para injetar `traceId`/`spanId` nos logs (Winston/Pino),
+ligando cada linha de log ao trace correspondente no New Relic.
+
+```ts
+import { getTraceContext } from '@skediprof/telemetry';
+
+const ctx = getTraceContext(); // null se não houver span ativo
+logger.info('processando aula', {
+  ...(ctx && { 'trace.id': ctx.traceId, 'span.id': ctx.spanId }),
+});
+```
+
+---
+
+## Encerramento (flush)
+
+`shutdownTelemetry()` faz flush de spans/métricas pendentes e encerra os
+exporters (timeout de 5s). É chamado automaticamente pelo `withTelemetry()`
+em Cloud Functions; em servidores, chame-o no handler de `SIGTERM`/`SIGINT`.
+
+```ts
+import { shutdownTelemetry } from '@skediprof/telemetry';
+
+process.on('SIGTERM', async () => {
+  await shutdownTelemetry();
+  process.exit(0);
+});
+```
+
+---
+
+## Consumidores
+
+| Serviço | Runtime | Linguagem | `runtime` |
+|---------|---------|-----------|-----------|
+| `zico` | Cloud Functions | TypeScript | `'function'` |
+| `skedi-students-imdb` | Cloud Run | TypeScript | `'server'` |
+| `ms-skedi-notifications` | Cloud Functions | TypeScript | `'function'` |
+| `whatsapp-bot-skedi` | Cloud Functions | JavaScript | `'function'` |
+
+---
+
+## API pública
+
+| Export | Descrição |
+|--------|-----------|
+| `initTelemetry(config)` | Inicializa traces + métricas. Idempotente. |
+| `withTelemetry(config, handler)` | Wrapper para Cloud Functions (init + flush por invocação). |
+| `createCounter(name, description)` | Cria um contador monotônico. |
+| `createHistogram(name, description, unit?)` | Cria um histograma. |
+| `createGauge(name, description)` | Cria um gauge observável (via callback). |
+| `getTraceContext()` | Retorna `{ traceId, spanId, traceFlags }` do span ativo, ou `null`. |
+| `shutdownTelemetry()` | Flush + encerramento dos exporters. |
+| `TelemetryConfig`, `TraceContext` | Tipos TypeScript exportados. |
+
+---
+
+## Versionamento
+
+Versões seguem semver e são publicadas no npm. Cada consumidor fixa uma versão:
+
+```json
+{ "dependencies": { "@skediprof/telemetry": "^1.0.0" } }
+```

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { initTelemetry, withTelemetry } from './init';
 export { createCounter, createHistogram, createGauge } from './metrics';
+export { emitLogRecord } from './logging';
 export { getTraceContext } from './context';
 export { shutdownTelemetry } from './shutdown';
 export type { TelemetryConfig, TraceContext } from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shutdownTelemetry = exports.getTraceContext = exports.createGauge = exports.createHistogram = exports.createCounter = exports.withTelemetry = exports.initTelemetry = void 0;
+exports.shutdownTelemetry = exports.getTraceContext = exports.emitLogRecord = exports.createGauge = exports.createHistogram = exports.createCounter = exports.withTelemetry = exports.initTelemetry = void 0;
 var init_1 = require("./init");
 Object.defineProperty(exports, "initTelemetry", { enumerable: true, get: function () { return init_1.initTelemetry; } });
 Object.defineProperty(exports, "withTelemetry", { enumerable: true, get: function () { return init_1.withTelemetry; } });
@@ -8,6 +8,8 @@ var metrics_1 = require("./metrics");
 Object.defineProperty(exports, "createCounter", { enumerable: true, get: function () { return metrics_1.createCounter; } });
 Object.defineProperty(exports, "createHistogram", { enumerable: true, get: function () { return metrics_1.createHistogram; } });
 Object.defineProperty(exports, "createGauge", { enumerable: true, get: function () { return metrics_1.createGauge; } });
+var logging_1 = require("./logging");
+Object.defineProperty(exports, "emitLogRecord", { enumerable: true, get: function () { return logging_1.emitLogRecord; } });
 var context_1 = require("./context");
 Object.defineProperty(exports, "getTraceContext", { enumerable: true, get: function () { return context_1.getTraceContext; } });
 var shutdown_1 = require("./shutdown");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+BAAsD;AAA7C,qGAAA,aAAa,OAAA;AAAE,qGAAA,aAAa,OAAA;AACrC,qCAAwE;AAA/D,wGAAA,aAAa,OAAA;AAAE,0GAAA,eAAe,OAAA;AAAE,sGAAA,WAAW,OAAA;AACpD,qCAA4C;AAAnC,0GAAA,eAAe,OAAA;AACxB,uCAA+C;AAAtC,6GAAA,iBAAiB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+BAAsD;AAA7C,qGAAA,aAAa,OAAA;AAAE,qGAAA,aAAa,OAAA;AACrC,qCAAwE;AAA/D,wGAAA,aAAa,OAAA;AAAE,0GAAA,eAAe,OAAA;AAAE,sGAAA,WAAW,OAAA;AACpD,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AACtB,qCAA4C;AAAnC,0GAAA,eAAe,OAAA;AACxB,uCAA+C;AAAtC,6GAAA,iBAAiB,OAAA"}

package/dist/init.d.ts

@@ -1,6 +1,6 @@
 import type { TelemetryConfig } from './types';
 /**
- * Inicializa toda a stack de telemetria (traces + metrics).
+ * Inicializa toda a stack de telemetria (traces + metrics + logs).
  * DEVE ser chamado ANTES de qualquer import de framework (Express, Firebase).
  */
 export declare function initTelemetry(config: TelemetryConfig): void;

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAM/C;;;GAGG;AAIH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAqE3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,SAAS,OAAO,EAAE,EACvB,OAAO,EAEP,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,GAC5C,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAetC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAM/C;;;GAGG;AAIH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAqF3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,SAAS,OAAO,EAAE,EACvB,OAAO,EAEP,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,GAC5C,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAetC"}

package/dist/init.js

@@ -5,7 +5,9 @@ exports.withTelemetry = withTelemetry;
 const sdk_node_1 = require("@opentelemetry/sdk-node");
 const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
 const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
+const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-http");
 const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
+const sdk_logs_1 = require("@opentelemetry/sdk-logs");
 const resources_1 = require("@opentelemetry/resources");
 const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
 const instrumentations_1 = require("./instrumentations");
@@ -15,7 +17,7 @@ const shutdown_1 = require("./shutdown");
 // on cold start. Do not switch to gRPC exporter. See ADR-002.
 const DEFAULT_ENDPOINT = 'https://otlp.nr-data.net:4318';
 /**
- * Inicializa toda a stack de telemetria (traces + metrics).
+ * Inicializa toda a stack de telemetria (traces + metrics + logs).
  * DEVE ser chamado ANTES de qualquer import de framework (Express, Firebase).
  */
 // AIDEV: initTelemetry MUST be called before any Express/Firebase import.
@@ -62,10 +64,24 @@ function initTelemetry(config) {
         exporter: metricExporter,
         exportIntervalMillis: metricInterval,
     });
+    // AIDEV: Third OTel pillar — logs. Without this, logger.error() calls only
+    // go to GCP Cloud Logging (console.error) but never reach New Relic,
+    // causing the "Logs ERROR" dashboard widget to show 0 while gcloud shows dozens.
+    const logExporter = new exporter_logs_otlp_http_1.OTLPLogExporter({
+        url: `${endpoint}/v1/logs`,
+        headers,
+    });
+    // AIDEV: For Cloud Functions (runtime='function'), use smaller batch + shorter
+    // delay to ensure logs are flushed before the function terminates.
+    const logProcessor = new sdk_logs_1.BatchLogRecordProcessor(logExporter, {
+        scheduledDelayMillis: runtime === 'function' ? 1000 : 5000,
+        maxExportBatchSize: runtime === 'function' ? 50 : 512,
+    });
     const sdk = new sdk_node_1.NodeSDK({
         resource,
         traceExporter,
         metricReader,
+        logRecordProcessors: [logProcessor],
         instrumentations: (0, instrumentations_1.buildInstrumentations)(config),
     });
     sdk.start();

package/dist/init.js.map

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

package/dist/logging.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Severity levels matching Winston/console conventions.
+ * Maps to OTel SeverityNumber for proper level filtering in New Relic.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Emit a log record via OTel Logs API → OTLP/HTTP → New Relic.
+ *
+ * This is the bridge between the app's logger (Winston/console) and OTel.
+ * Call this alongside console.log/error — it doesn't replace stdout logging
+ * (which GCP Cloud Logging still captures), it adds the New Relic pipeline.
+ *
+ * @param level - Log severity (debug, info, warn, error)
+ * @param message - Log message body
+ * @param attributes - Optional structured attributes (key-value pairs)
+ */
+export declare function emitLogRecord(level: LogLevel, message: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Reset cached logger (needed for Cloud Functions warm-start re-init).
+ * Called by shutdownTelemetry().
+ */
+export declare function resetLoggerCache(): void;
+export {};
+//# sourceMappingURL=logging.d.ts.map

package/dist/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AASpD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,IAAI,CAqBN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/logging.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitLogRecord = emitLogRecord;
+exports.resetLoggerCache = resetLoggerCache;
+const api_logs_1 = require("@opentelemetry/api-logs");
+const context_1 = require("./context");
+const LOGGER_NAME = '@skediprof/telemetry';
+const LOGGER_VERSION = '1.0.0';
+// AIDEV: Cache the OTel logger instance. It's safe to cache because the
+// LoggerProvider is set globally by NodeSDK.start() and doesn't change.
+let cachedLogger = null;
+function getOTelLogger() {
+    if (!cachedLogger) {
+        cachedLogger = api_logs_1.logs.getLoggerProvider().getLogger(LOGGER_NAME, LOGGER_VERSION);
+    }
+    return cachedLogger;
+}
+const SEVERITY_MAP = {
+    debug: { number: api_logs_1.SeverityNumber.DEBUG, text: 'DEBUG' },
+    info: { number: api_logs_1.SeverityNumber.INFO, text: 'INFO' },
+    warn: { number: api_logs_1.SeverityNumber.WARN, text: 'WARN' },
+    error: { number: api_logs_1.SeverityNumber.ERROR, text: 'ERROR' },
+};
+/**
+ * Emit a log record via OTel Logs API → OTLP/HTTP → New Relic.
+ *
+ * This is the bridge between the app's logger (Winston/console) and OTel.
+ * Call this alongside console.log/error — it doesn't replace stdout logging
+ * (which GCP Cloud Logging still captures), it adds the New Relic pipeline.
+ *
+ * @param level - Log severity (debug, info, warn, error)
+ * @param message - Log message body
+ * @param attributes - Optional structured attributes (key-value pairs)
+ */
+function emitLogRecord(level, message, attributes) {
+    const severity = SEVERITY_MAP[level];
+    const logger = getOTelLogger();
+    // Build attributes, injecting trace context for log↔trace correlation
+    // AIDEV: FIX (11/06/2026) - Add 'level' attribute so New Relic maps it
+    // to the same field used by APM classic agents. Without this, OTel logs
+    // only populate severity.text and the dashboard WHERE level='error' misses them.
+    const attrs = { level, ...attributes };
+    const traceCtx = (0, context_1.getTraceContext)();
+    if (traceCtx) {
+        attrs['trace.id'] = traceCtx.traceId;
+        attrs['span.id'] = traceCtx.spanId;
+    }
+    logger.emit({
+        severityNumber: severity.number,
+        severityText: severity.text,
+        body: message,
+        attributes: attrs,
+    });
+}
+/**
+ * Reset cached logger (needed for Cloud Functions warm-start re-init).
+ * Called by shutdownTelemetry().
+ */
+function resetLoggerCache() {
+    cachedLogger = null;
+}
+//# sourceMappingURL=logging.js.map

package/dist/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":";;AA0CA,sCAyBC;AAMD,4CAEC;AA3ED,sDAA+D;AAE/D,uCAA4C;AAE5C,MAAM,WAAW,GAAG,sBAAsB,CAAC;AAC3C,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,wEAAwE;AACxE,wEAAwE;AACxE,IAAI,YAAY,GAAkB,IAAI,CAAC;AAEvC,SAAS,aAAa;IACpB,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,eAAI,CAAC,iBAAiB,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAQD,MAAM,YAAY,GAA+D;IAC/E,KAAK,EAAE,EAAE,MAAM,EAAE,yBAAc,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE;IACtD,IAAI,EAAG,EAAE,MAAM,EAAE,yBAAc,CAAC,IAAI,EAAG,IAAI,EAAE,MAAM,EAAE;IACrD,IAAI,EAAG,EAAE,MAAM,EAAE,yBAAc,CAAC,IAAI,EAAG,IAAI,EAAE,MAAM,EAAE;IACrD,KAAK,EAAE,EAAE,MAAM,EAAE,yBAAc,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE;CACvD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAC3B,KAAe,EACf,OAAe,EACf,UAAsD;IAEtD,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAE/B,sEAAsE;IACtE,uEAAuE;IACvE,wEAAwE;IACxE,iFAAiF;IACjF,MAAM,KAAK,GAA8C,EAAE,KAAK,EAAE,GAAG,UAAU,EAAE,CAAC;IAClF,MAAM,QAAQ,GAAG,IAAA,yBAAe,GAAE,CAAC;IACnC,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC;QACrC,KAAK,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,IAAI,CAAC;QACV,cAAc,EAAE,QAAQ,CAAC,MAAM;QAC/B,YAAY,EAAE,QAAQ,CAAC,IAAI;QAC3B,IAAI,EAAE,OAAO;QACb,UAAU,EAAE,KAAK;KAClB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB;IAC9B,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC"}

package/dist/shutdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAKH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBvD"}
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AAKH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAuBvD"}

package/dist/shutdown.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shutdownTelemetry = shutdownTelemetry;
 const _state_1 = require("./_state");
+const logging_1 = require("./logging");
 const SHUTDOWN_TIMEOUT_MS = 5000;
 /**
  * Faz flush de todos os spans/metricas pendentes e encerra exporters.
@@ -30,6 +31,7 @@ async function shutdownTelemetry() {
     finally {
         (0, _state_1.setSDK)(null);
         (0, _state_1.setInitialized)(false);
+        (0, logging_1.resetLoggerCache)();
     }
 }
 //# sourceMappingURL=shutdown.js.map

package/dist/shutdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":";;AAcA,8CAsBC;AApCD,qCAAyE;AAEzE,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,8EAA8E;AAC9E,iFAAiF;AACjF,iFAAiF;AACjF,0CAA0C;AACnC,KAAK,UAAU,iBAAiB;IACrC,MAAM,GAAG,GAAG,IAAA,eAAM,GAAE,CAAC;IACrB,IAAI,CAAC,GAAG,IAAI,CAAC,IAAA,sBAAa,GAAE,EAAE,CAAC;QAC7B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC;YACjB,GAAG,CAAC,QAAQ,EAAE;YACd,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC9B,UAAU,CACR,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,EAC7C,mBAAmB,CACpB,CACF;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAC;IAC/D,CAAC;YAAS,CAAC;QACT,IAAA,eAAM,EAAC,IAAI,CAAC,CAAC;QACb,IAAA,uBAAc,EAAC,KAAK,CAAC,CAAC;IACxB,CAAC;AACH,CAAC"}
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":";;AAeA,8CAuBC;AAtCD,qCAAyE;AACzE,uCAA6C;AAE7C,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,8EAA8E;AAC9E,iFAAiF;AACjF,iFAAiF;AACjF,0CAA0C;AACnC,KAAK,UAAU,iBAAiB;IACrC,MAAM,GAAG,GAAG,IAAA,eAAM,GAAE,CAAC;IACrB,IAAI,CAAC,GAAG,IAAI,CAAC,IAAA,sBAAa,GAAE,EAAE,CAAC;QAC7B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC;YACjB,GAAG,CAAC,QAAQ,EAAE;YACd,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC9B,UAAU,CACR,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,EAC7C,mBAAmB,CACpB,CACF;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAC;IAC/D,CAAC;YAAS,CAAC;QACT,IAAA,eAAM,EAAC,IAAI,CAAC,CAAC;QACb,IAAA,uBAAc,EAAC,KAAK,CAAC,CAAC;QACtB,IAAA,0BAAgB,GAAE,CAAC;IACrB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skediprof/telemetry",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Shared OpenTelemetry library for Skedi microservices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,12 +18,15 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.218.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/instrumentation-express": "^0.66.0",
     "@opentelemetry/instrumentation-grpc": "^0.218.0",
     "@opentelemetry/instrumentation-http": "^0.218.0",
     "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-logs": "^0.218.0",
     "@opentelemetry/sdk-metrics": "^2.7.1",
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-node": "^2.7.1",