PackmindHub
diff --git a/‎.gitignore‎
Lines changed: 4 additions & 0 deletions b/‎.gitignore‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎apps/api/docker-package.json‎
Lines changed: 10 additions & 0 deletions b/‎apps/api/docker-package.json‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎apps/api/src/instrument.ts‎
Lines changed: 27 additions & 1 deletion b/‎apps/api/src/instrument.ts‎
Lines changed: 27 additions & 1 deletion
diff --git a/‎apps/api/src/main.ts‎
Lines changed: 13 additions & 3 deletions b/‎apps/api/src/main.ts‎
Lines changed: 13 additions & 3 deletions
diff --git a/‎apps/api/src/otel.spec.ts‎
Lines changed: 68 additions & 0 deletions b/‎apps/api/src/otel.spec.ts‎
Lines changed: 68 additions & 0 deletions
@@ -48,6 +48,10 @@ DECISIONS.md
 LEARNINGS.md
 test-results/
 .env
+# Any .env variant too: ad-hoc backups (.env.bak-*, .env.local) hold real
+# credentials, and GitGuardian runs on CI. Negate explicitly if a committed
+# template is ever added.
+.env.*
 compose.env
 .mcp.json
 !scripts/michel/.mcp.json
 
@@ -19,6 +19,16 @@
     "@nestjs/jwt": "^11.0.2",
     "@nestjs/platform-express": "^11.1.17",
     "@nestjs/typeorm": "^11.0.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.79.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
+    "@opentelemetry/instrumentation-express": "^0.69.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.221.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
+    "@opentelemetry/winston-transport": "^0.31.0",
     "@sentry/nestjs": "^9.40.0",
     "@sentry/node": "^9.40.0",
     "@teppeis/multimaps": "^3.0.0",
 
@@ -1,13 +1,39 @@
+// MUST stay first: OpenTelemetry patches modules as they are required, so it
+// has to run before anything below pulls in winston, express or ioredis.
+import { otelStarted } from './otel';
+
 import { Configuration } from '@packmind/node-utils';
 import { PackmindLogger } from '@packmind/logger';
 import * as Sentry from '@sentry/nestjs';
 
 Configuration.getConfig('SENTRY_DSN_API').then((sentryDSN) => {
   if (sentryDSN) {
-    new PackmindLogger('Sentry').info('Initializing Sentry');
+    new PackmindLogger('Sentry').info('Initializing Sentry', {
+      skipOpenTelemetrySetup: otelStarted,
+    });
     Sentry.init({
       dsn: sentryDSN,
       environment: process.env.NODE_ENV || 'development',
+      // Sentry is OpenTelemetry-based and would register a tracer provider of
+      // its own, displacing the one ./otel already installed — leaving the API
+      // serving traffic with no traces and nothing in the logs to say so. So
+      // when OTLP export is on, OpenTelemetry owns tracing and Sentry is
+      // narrowed to error reporting.
+      //
+      // Deliberately NOT paired with Sentry's SentrySampler: it defers to the
+      // client's `tracesSampleRate`, which is unset here, and an unset rate
+      // means "tracing disabled" — measured, that drops every span, including
+      // the ones bound for OTLP. SentryPropagator and SentryContextManager are
+      // left out for the same reason, that tracing is not Sentry's job here:
+      // the default W3C propagator is what an OTLP backend expects.
+      //
+      // The cost is that Sentry issues carry no trace id, so there is no
+      // click-through between a Sentry issue and its trace.
+      //
+      // False when OTLP is off, which is production today: Sentry then sets up
+      // its own OpenTelemetry exactly as before, and nothing about this path
+      // changes.
+      skipOpenTelemetrySetup: otelStarted,
     });
   } else {
     new PackmindLogger('Sentry').info('Sentry not initialized');
 
@@ -19,6 +19,7 @@ import { NestFactory } from '@nestjs/core';
 import bodyParser from 'body-parser';
 import cookieParser from 'cookie-parser';
 import { AppModule } from './app/app.module';
+import { shutdownOtel } from './otel';
 import { PackmindLogger, LogLevel } from '@packmind/logger';
 import { Configuration, Cache } from '@packmind/node-utils';
 import { enableAmplitudeProxy } from '@packmind/editions';
@@ -185,16 +186,22 @@ async function bootstrap() {
             shutdownTime: new Date().toISOString(),
             totalUptime: process.uptime(),
           });
+
+          // Last, because it must be the final thing before process.exit:
+          // exiting with an export in flight drops the whole buffered batch.
+          await shutdownOtel();
           process.exit(0);
         })
-        .catch((error) => {
+        .catch(async (error) => {
           const errorMessage =
             error instanceof Error ? error.message : String(error);
           logger.error('❌ Error during graceful shutdown', {
             signal,
             error: errorMessage,
             shutdownTime: new Date().toISOString(),
           });
+
+          await shutdownOtel();
           process.exit(1);
         });
     };
@@ -211,7 +218,10 @@ async function bootstrap() {
         stack: error.stack,
         pid: process.pid,
       });
-      process.exit(1);
+      // Flush first: the trace and logs of a fatal error are the ones worth
+      // keeping. shutdownOtel never rejects and is time-bounded, so this
+      // cannot stall the exit.
+      void shutdownOtel().finally(() => process.exit(1));
     });
 
     process.on('unhandledRejection', (reason) => {
@@ -221,7 +231,7 @@ async function bootstrap() {
         reason: errorMessage,
         pid: process.pid,
       });
-      process.exit(1);
+      void shutdownOtel().finally(() => process.exit(1));
     });
 
     Logger.log(
 
@@ -0,0 +1,68 @@
+/**
+ * The gate matrix for `otelStarted`, which `instrument.ts` forwards as Sentry's
+ * `skipOpenTelemetrySetup`. Nothing about getting this wrong is loud: two tracer
+ * providers leave the API serving traffic with no traces and no error, which is
+ * exactly the failure this flag exists to prevent.
+ *
+ * `jest.isolateModulesAsync` because otel.ts decides everything at module load
+ * from `process.env`, so each case needs a fresh evaluation.
+ */
+describe('otelStarted', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env['OTEL_EXPORTER_OTLP_ENDPOINT'];
+    delete process.env['OTEL_RESOURCE_ATTRIBUTES'];
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    jest.clearAllMocks();
+  });
+
+  const loadOtel = async (): Promise<boolean> => {
+    let started = false;
+    await jest.isolateModulesAsync(async () => {
+      const otel = await import('./otel');
+      started = otel.otelStarted;
+      await otel.shutdownOtel();
+    });
+    return started;
+  };
+
+  describe('when no endpoint is configured', () => {
+    it('does not start the SDK', async () => {
+      await expect(loadOtel()).resolves.toBe(false);
+    });
+  });
+
+  describe('when an endpoint is configured with an environment', () => {
+    it('starts the SDK', async () => {
+      process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318';
+      process.env['OTEL_RESOURCE_ATTRIBUTES'] =
+        'deployment.environment.name=test';
+
+      await expect(loadOtel()).resolves.toBe(true);
+    });
+  });
+
+  describe('when an endpoint is configured without an environment', () => {
+    it('refuses to start rather than mislabel the deployment', async () => {
+      jest.spyOn(console, 'error').mockImplementation(() => undefined);
+      process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318';
+
+      await expect(loadOtel()).resolves.toBe(false);
+    });
+  });
+
+  describe('when the environment is declared among other resource attributes', () => {
+    it('starts the SDK', async () => {
+      process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318';
+      process.env['OTEL_RESOURCE_ATTRIBUTES'] =
+        'service.version=dev,deployment.environment.name=staging';
+
+      await expect(loadOtel()).resolves.toBe(true);
+    });
+  });
+});