Telemetry Package

This package provides telemetry instrumentation and logging for Qrvey services.

Environment Variables

Set the following environment variables to configure telemetry:

LOG_LEVEL=debug                                # Minimum log level (debug, info, warn, error). Default: debug
ENABLE_CONSOLE_LOGS=false                      # Enable or disable console logging. Default: false

ENABLE_OTLP_TRACE=false                        # Enable OpenTelemetry tracing. Default: false
ENABLE_OTLP_METRIC=false                       # Enable OpenTelemetry metrics. Default: false
ENABLE_OTLP_LOG=false                          # Enable OpenTelemetry logs. Default: false

OTLP_TRACE_URL=http://localhost:4320/v1/traces   # Trace exporter endpoint
OTLP_METRIC_URL=http://localhost:4318/v1/metrics # Metric exporter endpoint
OTLP_LOG_URL=http://localhost:4320/v1/logs       # Log exporter endpoint

SERVICE_NAME=Qrvey-Service                     # OpenTelemetry service name. Default: Default-Service-name
QRVEY_VERSION=1.0.0                            # Service version used in telemetry resource attributes. Default: 0.0.0

SENSITIVE_FIELDS=password,token,authorization  # Comma-separated fields to sanitize from logs. Default: empty
EXPORT_METRICS_INTERVAL_MILLIS=10000           # Metric export interval in milliseconds. Default: 10000

ENABLE_BATCH_LOG_RECORD_PROCESSOR=false        # Use BatchLogRecordProcessor instead of SimpleLogRecordProcessor. Default: false
LOG_BATCH_MAX_QUEUE_SIZE=2048                  # Max queued log records for batch processor. Default: 2048
LOG_BATCH_MAX_EXPORT_BATCH_SIZE=512            # Max records per export batch. Default: 512
LOG_BATCH_SCHEDULED_DELAY_MILLIS=5000          # Delay between batch exports in milliseconds. Default: 5000

Notes:

• If ENABLE_BATCH_LOG_RECORD_PROCESSOR=false, the package uses SimpleLogRecordProcessor.
• If ENABLE_BATCH_LOG_RECORD_PROCESSOR=true, the package uses BatchLogRecordProcessor with the batch settings above.
• File system and DNS auto-instrumentations are disabled by default in code to reduce noisy traces.

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", { requestId: "abc-123", userId: 42 });
logger.debug("this is a debug message", { feature: "telemetry" });
logger.warn("this is a warning message", { retry: true });
logger.error("this is an error message", new Error("Something failed"));

Logger methods accept a second parameter for metadata:

• logger.info(message, meta) expects meta to be an object.
• logger.debug(message, meta) expects meta to be an object.
• logger.warn(message, meta) expects meta to be an object.
• logger.error(message, meta) accepts either an object or an Error instance.

When an Error instance is passed to logger.error(), the logger extracts structured fields such as the error name, message, cause, code and stack trace before sending them to OpenTelemetry.

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.