Enable telemetry control from env vars (#605)

* Bump diagnostics-nodejs version

* Refactor telemetry client to support all signals

Enables this client to support logs, metrics, and tracing signals from the diagnostics-nodejs library, making them available already initialized. Additionally, this change enables registration of built-in and community instrumentation.

* Refactor getLogClient to simplify initialization

Remove unused parameters and use logClient already initialized

* Refactor logger client types

Refactor client types to use Types.LogClient for consistency

* Add resolution for @grpc/grpc-js dependency

* Update package version to 6.49.8-beta.0

* Refactor singleton to use dedicated initialization methods for telemetry clients

* Refactor telemetry client initialization logic

Improve telemetry client initialization using Promise.all to optimize asynchronous calls

* Update package.json and yarn.lock

Adds OpenTelemetry dependencies for host metrics and Koa instrumentation

* Update startApp function to proper init telemetry

Updates startApp function to initialize telemetry beforehand and uses dynamic imports for startMaster and startWorker. This ensures that telemetry clients and libraries are proper initialized so they can use hooks with application libraries that will be loaded later

* Add metrics client

Add getMetricClient function to make the client available and creates the asynchronous initialization function to retrieve it

* Add metrics instruments for monitoring HTTP requests

* Add middleware for request metrics

This commit creates a middleware for request metrics using OpenTelemetry instruments. This change is inspired by `requestMetricsMiddleware.ts` and follows the same logic, only changing the way it is instrumented to use OTel standard

* Add middleware usage on app

Add the use of OpenTelemetry metrics middleware for request monitoring

* Add Koa instrumentation to telemetry client

Add Koa instrumentation to the list of instruments that will be registered and used by the telemetry client. This enables automatic instrumentation for the Koa module, as well as automatic collection and export of telemetry data.

* Add Koa context propagation middleware to app worker

* Add host-metrics instrumentation

This commit creates a wrapper for the host-metrics module, which provides automatic collection for system metrics - such as CPU, memory, and network

* Add host-metrics instrumentation to telemetry client

* Release v7.0.1

* Release v7.1.0-beta.0

* Improves code formatting for setTimeout

* Refactor instrument init logic on middleware

Refactors the instrument initialization logic to improve readability and code structure

* Refactor metric client module

Refactor MetricClient to use Singleton pattern for improved client management

* Refactor metrics instruments module

Refactor OTel instruments initialization to use singleton pattern

* Add error handling when init instruments

* Bump @vtex/diagnostics-nodejs to 0.1.0-io-beta.20

* Add new constants for diagnostics configuration

This commit creates new constants based on environment variables that will be used to proper configure diagnostics-nodejs on node-vtex-api

* Enable log client initialization

* Add new constants to client.ts

Make the new constants available on clients.ts file, which is responsible for create telemetry client.

* Make clients use new constant for endpoint

This commit replaces and updates the telemetry clients to utilize the OTEL_EXPORTER_OTLP_ENDPOINT constant for exporting telemetry data

* Use DK_APP_ID on telemetry client creation

Small change on parameter to follow o11y team guidelines regarding this field

* Refactor telemetry client parameters

Updates parameters on telemetry client creation, making use of APPLICATION_ID and adding new additional attributes. Also, we remove unused constant CLIENT_NAME.

* Refactor telemetry client initialization with checks

This update adds console logging for diagnostics configuration and checks if telemetry is enabled before registering instrumentations. It ensures that the telemetry client operates correctly based on the DIAGNOSTICS_TELEMETRY_ENABLED constant. Also, whenever the app vendor is not enabled it will use a no-op client for diagnostics, meaning any telemetry signal will be ignored

* Update constant default value

This change modifies the DK_APP_ID constant to default to 'apps-team' instead of 'apps'

* improve logging approach for telemetry status

Replace negative warning message when telemetry is disabled with positive
confirmation message when enabled. This change aligns with the principle
of treating disabled telemetry as the default state.

* Add new attributes to telemetry client

* release v7.1.1

* update CHANGELOG

Author: daniyelnnr

CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [7.1.1] - 2025-09-08
+### Changed
+- Add conditional enabling for diagnostics telemetry signals
+
+## [7.1.0] - 2025-09-08
+### Changed
+- Add metrics instrumentation based on diagnostics lib
+
 ## [7.1.0] - 2025-09-02
 ### Changed
 - Add new scope argument into auth directive

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/api",
-  "version": "7.1.0",
+  "version": "7.1.1",
   "description": "VTEX I/O API client",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -53,7 +53,7 @@
     "@opentelemetry/instrumentation-koa": "0.47.1",
     "@types/koa": "^2.11.0",
     "@types/koa-compose": "^3.2.3",
-    "@vtex/diagnostics-nodejs": "0.1.0-io-beta.19",
+    "@vtex/diagnostics-nodejs": "0.1.0-io-beta.20",
     "@vtex/node-error-report": "^0.0.3",
     "@wry/equality": "^0.1.9",
     "agentkeepalive": "^4.0.2",

src/constants.ts

@@ -74,3 +74,9 @@ export const INSPECT_DEBUGGER_PORT = 5858
 export const cancellableMethods = new Set(['GET', 'OPTIONS', 'HEAD'])
 
 export const LOG_CLIENT_INIT_TIMEOUT_MS = 5000
+
+export const OTEL_EXPORTER_OTLP_ENDPOINT = process.env.OTEL_EXPORTER_OTLP_ENDPOINT as string;
+
+export const DK_APP_ID = process.env.NODE_VTEX_API_DK_APP_ID as string || "apps-team";
+
+export const DIAGNOSTICS_TELEMETRY_ENABLED = process.env.VTEX_DIAGNOSTICS_TELEMETRY_ENABLED === 'true';

src/service/logger/logger.ts

@@ -32,7 +32,7 @@ export class Logger {
       }
     }
 
-    // this.initLogClient();
+    this.initLogClient();
   }
 
   private initLogClient(): Promise<Types.LogClient | undefined> {

src/service/telemetry/client.ts

@@ -6,14 +6,12 @@ import {
   Metrics,
   Traces,
 } from '@vtex/diagnostics-nodejs';
-import { APP } from '../../constants';
+import { APP, OTEL_EXPORTER_OTLP_ENDPOINT, DK_APP_ID, DIAGNOSTICS_TELEMETRY_ENABLED, WORKSPACE, PRODUCTION } from '../../constants';
 import { TelemetryClient } from '@vtex/diagnostics-nodejs/dist/telemetry';
 import { KoaInstrumentation } from '@opentelemetry/instrumentation-koa';
 import { HostMetricsInstrumentation } from '../metrics/instruments/hostMetrics';
 
-const CLIENT_NAME = APP.NAME || 'node-vtex-api';
 const APPLICATION_ID = APP.ID || 'vtex-io-app';
-const EXPORTER_OTLP_ENDPOINT = process.env.EXPORTER_OTLP_ENDPOINT;
 
 interface TelemetryClients {
   logsClient: Logs.LogClient;
@@ -38,14 +36,14 @@ class TelemetryClientSingleton {
   private initializeTracesClient = async (telemetryClient: TelemetryClient) =>
     await telemetryClient.newTracesClient({
       exporter: Exporters.CreateExporter(Exporters.CreateTracesExporterConfig({
-        endpoint: EXPORTER_OTLP_ENDPOINT,
+        endpoint: OTEL_EXPORTER_OTLP_ENDPOINT,
       }), 'otlp'),
     });
 
   private initializeMetricsClient = async (telemetryClient: TelemetryClient) =>
     await telemetryClient.newMetricsClient({
       exporter: Exporters.CreateExporter(Exporters.CreateMetricsExporterConfig({
-        endpoint: EXPORTER_OTLP_ENDPOINT,
+        endpoint: OTEL_EXPORTER_OTLP_ENDPOINT,
         interval: 5,
         timeoutSeconds: 5,
       }), 'otlp'),
@@ -54,21 +52,27 @@ class TelemetryClientSingleton {
   private initializeLogsClient = async (telemetryClient: TelemetryClient) =>
     await telemetryClient.newLogsClient({
       exporter: Exporters.CreateExporter(Exporters.CreateLogsExporterConfig({
-        endpoint: EXPORTER_OTLP_ENDPOINT,
+        endpoint: OTEL_EXPORTER_OTLP_ENDPOINT,
       }), 'otlp'),
       loggerName: `node-vtex-api-${APPLICATION_ID}`,
     });
 
   private async initializeTelemetryClients(): Promise<TelemetryClients> {
+
     try {
       const telemetryClient = await NewTelemetryClient(
-        APPLICATION_ID,
-        CLIENT_NAME,
+        DK_APP_ID,
         'node-vtex-api',
+        APPLICATION_ID,
         {
+          // Use built-in no-op functionality when telemetry is disabled
+          noop: !DIAGNOSTICS_TELEMETRY_ENABLED,
           additionalAttrs: {
+            'app.id': APPLICATION_ID,
+            'vendor': APP.VENDOR,
             'version': APP.VERSION || '',
-            'environment': process.env.VTEX_WORKSPACE || 'development',
+            'workspace': WORKSPACE,
+            'production': PRODUCTION.toString(),
           },
         }
       );
@@ -79,16 +83,20 @@ class TelemetryClientSingleton {
         this.initializeLogsClient(telemetryClient),
       ]);
 
-      const instrumentations = [
-        ...Instrumentation.CommonInstrumentations.minimal(),
-        new KoaInstrumentation(),
-        new HostMetricsInstrumentation({
-          name: 'host-metrics-instrumentation',
-          meterProvider: metricsClient.provider(),
-        }),
-      ];
-
-      telemetryClient.registerInstrumentations(instrumentations);
+      if (DIAGNOSTICS_TELEMETRY_ENABLED) {
+        console.log(`Telemetry enabled for app: ${APP.ID} (vendor: ${APP.VENDOR})`);
+        
+        const instrumentations = [
+          ...Instrumentation.CommonInstrumentations.minimal(),
+          new KoaInstrumentation(),
+          new HostMetricsInstrumentation({
+            name: 'host-metrics-instrumentation',
+            meterProvider: metricsClient.provider(),
+          }),
+        ];
+
+        telemetryClient.registerInstrumentations(instrumentations);
+      }
 
       const clients: TelemetryClients = {
         logsClient,

yarn.lock

@@ -1251,10 +1251,10 @@
   dependencies:
     "@types/yargs-parser" "*"
 
-"@vtex/diagnostics-nodejs@0.1.0-io-beta.19":
-  version "0.1.0-io-beta.19"
-  resolved "https://registry.yarnpkg.com/@vtex/diagnostics-nodejs/-/diagnostics-nodejs-0.1.0-io-beta.19.tgz#e8ebc6a0b44014d0ffcda9df736291c52604ee9e"
-  integrity sha512-p3bcfpCI12k1DXqD2wJvO53dDdrULYsK7muJFHlwiZio4WvnSfPU1Ay5ni9Y8alD/MLX4fP4EEjRYXTGc7wFWQ==
+"@vtex/diagnostics-nodejs@0.1.0-io-beta.20":
+  version "0.1.0-io-beta.20"
+  resolved "https://registry.yarnpkg.com/@vtex/diagnostics-nodejs/-/diagnostics-nodejs-0.1.0-io-beta.20.tgz#79ee25a88827a501206d1a8ef0715674fa1521b5"
+  integrity sha512-8DbibPcPEd2yJCRKZOM2JAf4FYr9W90lD+DRV/mOwgMd1ZGdZuXupfoqqOzOdrkOidXhCeLBPhRXne8O2N3QEQ==
   dependencies:
     "@grpc/grpc-js" "^1.13.4"
     "@opentelemetry/api" "^1.9.0"