Telemetry Package

This package provides telemetry instrumentation and logging for Qrvey services.

Environment Variables

Set the following environment variables to configure telemetry:

ENABLE_OTLP_LOG=true             # Enable OpenTelemetry logging
ENABLE_OTLP_TRACE=true           # Enable OpenTelemetry tracing
ENABLE_OTLP_METRIC=true          # Enable OpenTelemetry metrics
SERVICE_NAME=Qrvey-Service # Name of the service for telemetry identification
SERVICE_VERSION=1.0.0      # Version of the service
OTLP_TRACE_URL=http://localhost:4320/v1/traces   # Endpoint for sending trace data
OTLP_LOG_URL=http://localhost:4320/v1/logs       # Endpoint for sending log data
OTLP_METRIC_URL=http://otel-collector:4318/v1/metrics # Endpoint for sending metric data
ENABLE_CONSOLE_LOGS=false        # Enable or disable console logging
NODE_ENV=development             # Node.js environment (development, production, etc.)
LOG_LEVEL=debug                  # Minimum log level (debug, info, warn, error)

Usage

At the beginning of each service, start the InstrumentationService and use the LoggerService for logging purposes:

const { InstrumentationService, LoggerService } = require("@qrvey/telemetry");

// Initialize instrumentation
new InstrumentationService();

// Initialize logger (optional name for context)
const logger = new LoggerService('your_context_name');

logger.info("this is info message");
logger.debug("this is a debug message");
logger.warn("this is a warning message");
logger.error("this is an error message");

Notes

• Ensure all environment variables are set before starting your service.
• Use the logger for consistent log formatting and output.
• InstrumentationService should be initialized once at service startup.

Fastify Integration

When using Fastify, use hooks (not Express middleware) to capture parsed request and real response payloads:

import Fastify from 'fastify';
import { MiddlewareService } from '@qrvey/telemetry';

const app = Fastify();
const middlewareService = new MiddlewareService({
  scopeName: "Middleware-Test-Service",
  excludePaths: ["/health", "/metrics"],
  logRequestBody: true,
  logResponseBody: true,
  maxBodySize: 10000,
  logRequestBodyFields: ["email"],
});

app.addHook("preHandler", await apiLogger.logFastifyPreHandler);
app.addHook("onSend", await apiLogger.logFastifyOnSend);

Notes:

• preHandler logs the parsed request body.
• onSend captures the actual payload sent to the client.
• If logRequestBodyFields is empty, all request body fields are logged.

Express Integration

When using Express, use the MiddlewareService as standard middleware:

import express from 'express';
import { MiddlewareService } from '@qrvey/telemetry';

const app = express();
const middlewareService = new MiddlewareService({
	scopeName: "Middleware-Test-Service",
	excludePaths: ["/health", "/metrics"],
	logRequestBody: true,
	logResponseBody: true,
	maxBodySize: 10000,
	logRequestBodyFields: ["email"],
});

app.use(middlewareService.logExpressApiCall);

Notes:

• Attach the middleware early in the middleware chain to capture all requests.
• If logRequestBodyFields is empty, all request body fields are logged.
• Ensure express.json() is registered before the telemetry middleware to allow request body parsing.