Node.js agent

Use SixthSense Node monitoring to track the exact error in the code. You will get the whole picture of your application environment which will help you in resolving issues.

Prerequisites

  • For prerequisite checks for agent installation, see Prerequisite checks for agent installation.
  • SixthSense Agent - Node Package See, Downloading the agent.
  • URL/IP of the SixthSense collector (the tenant URL which will be provided by the SixthSense Customer Support.)
  • Access token - For accessing the token, see Accessing your Access Token under Getting started with the Observability Portal.
  • PACKAGE_TOKEN - token from SixthSense Customer Support to download the SixthSense package.

Downloading the agent

  • Download the SixthSense agent into your project dependencies."@SixthSense/SixthSense-node-js": "^2.2.5"
  • Agent configurations will be added to the entry point of your application. For example, in any Node.js application entry point will be defined in the package.json file and in the following example server.js file is the entry point. Following is the package.json file.
{
"name": "SixthSense-node-demo",
"version": "2.2.5",
"description": "RESTful API with Node Demo",
"main": "server.js",
"scripts":{
"test": "echo \"Error: no tests specified\"&& exit 1"
}
}
  • Add the agent with your dependencies.
"dependencies": {
"@sixthsense/sixthsense-node-js": "^2.2.5"
}

Initialise and name the agent

  • Entry point to the application is "server.js". For your application the entry point can be different. Hence, add our agent configurations in the entry point file as mentioned below.
  • Name the service using the serviceName variable.
// Sixthsense Agent
var agent = require('@sixthsense/sixthsense-node-js').default
agent.start({
serviceName: 'NAME_OF_THE_SERVICE',
// The identifier of the instance
// Collector agent_gRPC/grpc service addresses.
directServers: 'grpc-collector-observability.sixthsense.rakuten.com:443',
collectorAddress: 'grpc-collector-observability.sixthsense.rakuten.com:443',
enableLogs: true,
caPath: true,
authorization: process.env.TOKEN
});

For OneCloud Platform use the following command:

// Sixthsense Agent
var agent = require('@sixthsense/sixthsense-node-js').default
agent.start({
serviceName: 'NAME_OF_THE_SERVICE',
// The identifier of the instance
// Collector agent_gRPC/grpc service addresses.
// For connectivity to backend using onecloud private network: 100.99.116.221:80
// For connectivity to backend using intra public network: 133.237.176.44:80
directServers: '133.237.176.44:80',
collectorAddress: '133.237.176.44:80',
enableLogs: true,
agent.force_tls=${SW_AGENT_FORCE_TLS:false},
caPath: true,
authorization: process.env.TOKEN
});
  • Get Access Token from the SixthSense portal. For accessing the token, see Accessing your Access Token under Getting started with the Observability Portal.
  • Add the access token to the entry point file authorization:'Access token'.

For example, see the above snippet.

Run your application

  • Run the following commands before the npm install command

To download the agent, download Packages from Gitlab Package Registry.

npm config set @sixthsense:registry https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/
npm config set -- '//artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/:_authToken' "PACKAGE_TOKEN"
  • PACKAGE_TOKen - provided by SixthSense Customer Support.
  • Run npm install command to download all the dependencies.
npm install @sixthsense/sixthsense-node-js
  • Run the start command to run your Node application.

Incase of network restriction to sixthsense backend, you can either use proxy or ask your network team to whitelist the SixthSense backend address to allow connectivity to send data.

  1. Set proxy at system/container level.

Example: a. Windows Servers: Add environment variable in system level variables for http_proxy, https_proxy b. Linux Servers: Add proxy in the ~/.bashrc file as follows. export http_proxy= 10.0.0.1:3128

  1. Pass Proxy at node level.

npm config set proxy http://username:password@host:port npm config set https-proxy https://username:password@host:port

  1. For setting proxy and other configurations for npm, type the following command in the console

npm config edit

This command will open the .npmrc file. Set the proxy, https-proxy related to npm in the file.

note

The various ignore options like SW_IGNORE_SUFFIX, SW_TRACE_IGNORE_PATH and SW_HTTP_IGNORE_METHOD as well as endpoints which are not recorded due to exceeding SW_AGENT_MAX_BUFFER_SIZE all propagate their ignored status downstream to any other endpoints they may call. If that endpoint is running the Node Sixthsense agent then regardless of its ignore settings, it will not be recorded since its upstream parent was not recorded. This allows elimination of entire trees of endpoints you are not interested in as well as eliminating partial traces if a span in the chain is ignored but calls out to other endpoints which are recorded as children of ROOT instead of the actual parent.

Enabling Node.js Agent log

Node.js agent uses debug framework for output log, and you can activate the log before you deploy the application currently.

You can set the logging level as follows:

  • info
  • debug
  • warn
  • error

Enabling log rotation

By default log rotation is enabled with max size 5MB and max files 7 days. You can change this by setting env SS_AGENT_LOGGING_MAXFILES & SS_AGENT_LOGGING_MAXSIZE.

  • SS_AGENT_LOGGING_MAXSIZE

Maximum size of the file after which it will rotate. This can be a number of bytes, or units of kb, mb, and gb. If using the units, add 'k', 'm', or 'g' as the suffix. The units need to directly follow the number.

  • SS_AGENT_LOGGING_MAXFILES

The maximum number of logs to keep. This can be a number of files or a number of days. If using days, add 'd' as the suffix.

Installing on a Docker

Agent Integrations in a Docker

For agent integrations in a docker, see Downloading the agent.

Adding the dependency download configuration in the Docker file

The Node SixthSense agent is hosted in Rakuten self-hosted private package manager. To download the package, do the following for authentication.

  • Add the below code snippet in your docker file before the NPM Install command.
RUN npm config set @sixthsense:registry https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/
npm config set -- '//artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/:_authToken' "PACKAGE_TOKEN"
RUN npm install @sixthsense/sixthsense-node-js
  • This code will set the configuration to identify the SixthSense package registry. It also tells the dependency to download from this URL that you defined with the same name in the package.json file.
  • https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/ -- the SixthSense package manager URL.
  • _authToken' "PACKAGE_TOKEN"– Since the package is hosted in a private package manager it requires some authentication to identify the user. This auth token will be defined during the onboarding.
  • For simplicity, the auth token is placed in the docker file. However, if you don’t wish to add in the docker file and push it to your version control repository, you can pass this auth token based on your credential management by setting the environment variable, passing the secrets from Jenkins CI/CD, and so on.
  • Build your application with docker build and run the docker image/container. The agent is integrated with your application and you will start seeing the metrics in the SixthSense dashboard.

Pass the PACKAGE_TOKEN as build arguments.

docker build --build-arg PACKAGE_TOKEN=${PACKAGE_TOKEN_VALUE} -t service:tag .

Example for yarn

FROM yarnpkg/node-yarn
# Prepare app directory
WORKDIR /usr/src/app
COPY package.json /usr/src/app/
COPY yarn.lock /usr/src/app/
ARG PACKAGE_TOKEN
RUN npm config set @sixthsense:registry https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/ && \
npm config set -- '//artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/:_authToken' "${PACKAGE_TOKEN}"
# RUN yarn add @sixthsense/sixthsense-node-js
RUN yarn install
COPY . /usr/src/app
# Start the app
CMD ["yarn", "start"]

Example for NPM

FROM node:10-alpine
# Prepare app directory
WORKDIR /usr/src/app
COPY package.json /usr/src/app/
COPY package-lock.json /usr/src/app/
ARG PACKAGE_TOKEN
RUN npm config set @sixthsense:registry https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/ && \
npm config set -- '//artifacts-observability.sixthsense.rakuten.com/api/v4/projects/3/packages/npm/:_authToken' "${PACKAGE_TOKEN}"
RUN npm i @sixthsense/sixthsense-node-js
RUN npm install
COPY . /usr/src/app
# Start the app
CMD ["/usr/local/bin/npm", "start"]

Node.js supported libraries

There are some built-in plugins that support automatic instrumentation of NodeJS libraries. Following is a complete list:

LibraryPlugin Name
1Expressexpress
2Axiosaxios
3MySQLmysql
4MySQLmysql2
5PostgreSQLpg
6pg-cursorpg-cursor
7MongoDBmongodb
8Mongoosemongoose
9RabbitMQamqplib
10redisioredis