MTN APM Node.js Agent

This is the MTN-official Node.js application performance monitoring (APM) agent. It builds on the battle-tested OpenTelemetry SDK and auto-instrumentation libraries, packaging them as a simple drop-in SDK for MTN Node.js projects. After installing the package and configuring the observability endpoint, Node.js applications are automatically instrumented with no manual instrumentation required.

The agent captures errors, traces, and performance metrics and forwards them to your Observability backend so you can monitor services, create alerts, and quickly identify root causes. MTN engineers can reach the internal SRE team for questions or feedback.

Getting started

You will need an Observability endpoint that accepts APM traffic. Obtain the APM endpoint from the SRE team before starting.

Getting started typically looks like this:

1. Install the APM agent package as a dependency:

   npm install @mukhy/mtn-apm-agent

2. Initialize the APM agent before any other imports Create a file called init.ts:

   // init.ts
   const mtn = require('@mukhy/mtn-apm-agent');
      
   mtn.start({
     serviceName: 'your-service-name',
     environment: 'your-deployment-environment',
     serverUrl: 'http://localhost:8200',
     captureBody: 'all',
     captureConsoleLogs: true,
     captureStdStreams: true,
     opentelemetryBridgeEnabled: true,
   });
      
   module.exports = mtn;

3: Import it FIRST in your application entry point

// main.ts
import './init';
//import { NestFactory } from '@nestjs/core';

Loading the agent early (important)

The MTN APM agent must be started before any other application code so that automatic instrumentation works correctly.

CommonJS applications

Start the agent at the very top of your main entry file:

require('@mukhy/mtn-apm-agent').start({...});

TypeScript / ESM applications (recommended)

To avoid issues caused by transpilation or bundling, preload the agent using

node -r @mukhy/mtn-apm-agent/start dist/main.js

Consistent Logs in APM

If logs appear intermittently in the APM service Logs tab, enable console log capture so every console.log/info/warn/error/debug line is emitted as structured JSON with:

• service.name
• service.environment
• trace correlation fields (trace.id, transaction.id, span.id) when available

Enable via startup config:

mtn.start({
  serviceName: 'your-service-name',
  environment: 'workforce-stage',
  captureConsoleLogs: true,
  captureStdStreams: true,
});

or via environment variable:

MTN_APM_CAPTURE_CONSOLE_LOGS=true
MTN_APM_CAPTURE_STD_STREAMS=true

captureStdStreams captures process.stdout.write and process.stderr.write output as structured JSON as well, which helps include framework logger output that does not go through console.*.

Made with ♥️ by MTN SRE Team.