apm-js

@rpp-eva/apm-js es la interfaz para poder elegir con que APM trabajar, New Relic o SignalFx.

Instalación

Instalación

npm install --save @rpp-eva/apm-js

Implementación

Se remplazan todas las ocurrencias donde se importe newrelic:

import 'newrelic'

por:

import 'apm-js'

Remplazar:

const newrelic = require('newrelic')

por

const apm = require('apm-js')

Variables de entorno

Del deploy único se reciben las variables:

• RAPPI_APM: que trae como valores signalfx o newrelic (el default)

Y dependiendo del caso:

• NEW_RELIC_LICENSE_KEY: token de autenticación contra NR.
• NEW_RELIC_APP_NAME: nombre con el cual reporta la aplicación.

o

• SIGNALFX_SERVICE_NAME: nombre con el cual reporta la aplicación.
• SIGNALFX_ENDPOINT_URL: URL a la que enviar los spans.

Variables exclusivas de SFX

La librería cuenta con la opción de hacer ingesta de eventos a SFX para esto requiere las siguiente variables de entorno.

• SIGNALFX_ACCESS_TOKEN_PRIVATE: Token de acceso contra SFX, este se debe solicitar en #secops_on_scheduled
• POSTFIX: Variable de ansible que contienen todos los proyectos, tan solo debe ser definida en el env.yml.

Despliegue

Es necesario utilizar una llave SSH privada que pertenezca a una cuenta con acceso al repositorio, y codificarla en base 64:

# Mac OS
base64 -i ~/.ssh/id_rsa -o ~/id_rsa_base64

# ... o solo copiando a portapapeles sin crear un archivo
cat ~/.ssh/id_rsa | base64 -b 0 | pbcopy

# Linux
base64 -i ~/.ssh/id_rsa > ~/id_rsa_base64

# Windows
base64 -w 0 <path-to-private-key>

Después es necesario usarla para clonar el repositorio. Es preferible usar un entrypoint de Docker y agregarla como variable de entorno al microservicio de ms-api (en este caso SSH_PRIVATE_KEY):

# docker-entrypoint.sh
mkdir ~/.ssh/
echo "${SSH_PRIVATE_KEY}" | base64 -d > ~/.ssh/id_rsa && chmod 400 ~/.ssh/id_rsa
eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_rsa
touch ~/.ssh/known_hosts
ssh-keyscan bitbucket.org >> ~/.ssh/known_hosts
npm ci

Funciones

noticeError

const APM = require('apm-js');

APM.noticeError('Error description');

APM.noticeError(new Error());

sendEvents

const APM = require('apm-js');

/**
 * @param first -> Nombre del evento
 * @param second -> Tipo de categoria, estas se pueden ver en https://github.com/signalfx/signalfx-nodejs/blob/master/proto/signal_fx_protocol_buffers.proto#L55
 * @param third -> Opcional, Son las dimensiones del evento,Aquí se puede enviar un objeto del formato clave-valor (string -> string)
 * 
 * Se añaden cuatro dimensiones por defecto: "service", "instance", "country" y "env"; service e instance contienen el valor de SIGNALFX_SERVICE_NAME
 */
APM.sendEvent('eventName', 'AUDIT', { any: 'any', other: 'other' })

APM.sendEvent('eventName', 'AUDIT')

startBackgroundTransactionWithScope

const APM = require('apm-js');

const handler = () => {
  // En la función callback se debe ejecutar todo aquello que se desee añadir al mismo span.
  // funciones sync o promesas.
  someFunction()

  promiseFunction().then().catch();

  // sino no hay un retorno explicito se retorna undefined.
  return 'any' || undefined
}

const tags = {
  some: 'test',
};

/**
 * @param first -> Nombre del span.
 * @param second -> Grupo del span => name + group, generan el nombre identificador del span.
 * @param third -> Callback el cual contiene las instrucciones o procesos que se desean agrupar en el mismo span.
 * @param fourth -> Opcional, Objeto que contiene propiedades clave-valor que se añadir como tags al span.
 */
const response = APM.startBackgroundTransactionWithScope('name', 'gropu', handler, tags);

sendMetrics

const APM = require('apm-js');

/**
 * @param first -> Nombre de la metrica
 * @param second -> Valor del evento
 * @param third -> Opcional, Son las dimensiones del evento,Aquí se puede enviar un objeto del formato clave-valor (string -> string)
 * 
 * Se añaden cuatro dimensiones por defecto: "service", "instance", "country" y "env"; service e instance contienen el valor de SIGNALFX_SERVICE_NAME
 */
APM.sendMetric('metricName', 'some-value', { any: 'any', other: 'other' })

APM.sendMetric('metricName', 'some-value')