NodeJS tracing
Available Platforms
For Log Correlation, scroll to the bottom of this page or click here
Instances
Node.JS Express
Install nodejs dependencies and save it in
package.json
usingnpm install --save elastic-apm-node@^3.20.0
npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"and run
npm install
to install dependencies
Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variable in.env
file and load it usingrequire('dotenv').config()
and access it in code usingprocess.env.<ENV_VAR>
Add initilization code at start of the file
Get Snappyflow trace config using
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variables in add container section of task definitions.https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html
Once your server is up and running you can check trace in Snappyflow Server.
For viewing trace in Snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to:
View dashboard -> Click on Tracing on left side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/refapp-express
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
Node.JS Script
Install nodejs dependencies and save it in
package.json
usingnpm install --save elastic-apm-node@^3.20.0
npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries:"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"And run
npm install
to install dependenciesAdd initilization code at start of the file
Get Snappyflow trace config using
const Snappyflow = require('sf-apm-lib');
let projectName = <SF_PROJECT_NAME>; //replace with appropriate project name
let appName = <SF_APP_NAME>; //replace with appropriate application name
let profileKey = <SF_PROFILE_KEY>; //replace with key copied from SF profile
var sfObj = new Snappyflow();
sfObj.init(profileKey, projectName, appName);
let sfTraceConfig = sfObj.getTraceConfig();Initialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}Create a custom transaction and span within transaction using following code
var trans = apm.startTransaction('json transaction', 'reference-app');
var span = apm.startSpan('parse json');
try {
JSON.parse('{"app": "test"}')
} catch (e) {
apm.captureError(e); // Capture the error using apm.captureError(e) method.
}
// when we've processed, stop the custom span
if (span) span.end()
trans.result = err ? 'error' : 'success';
// end the transaction
trans.end();For more info refer
https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-transactions.html
https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-spans.html
Run you script using node
file_name.js
you should see trace data in Snappyflow server.For viewing trace in Snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to: View dashboard -> Click on Tracing on left side bar -> Click on view transaction -> Go to real time tab
Refer sample script file at:
[https://github.com/snappyflow/tracing-reference-apps/blob/master/refapp- express/node_trace_script.js](https://github.com/snappyflow/tracing-reference-apps/blob/master/refapp- express/node_trace_script.js )
Node.JS Sails
Install nodejs dependencies and save it in
package.json
usingnpm install --save elastic-apm-node@^3.20.0
npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"And run
npm install
to install dependenciesProvide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variable in .env file and load it usingrequire('dotenv').config()
and access it in code usingprocess.env.<ENV_VAR>
Add initilization code at start of the file in
globals.js
present in config folder.Get Snappyflow trace config using:
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using:
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}Attach apm object to globals – This is required so we can use apm variable in other files as part of global sails object.
module.exports.globals = {
_: require('@sailshq/lodash'),
async: false,
models: true,
sails: true,
apm : apm,
logger: logger
};Also add middleware in
http.js
file present in config folder. Which allows to instrument our code.module.exports.http = {
middleware: {
order: [
'elasticAPM'
],
elasticAPM: (function () {
return function (err, req, res, next) {
apm.middleware.connect();
if (typeof err !== 'undefined')
apm.captureError(err);
return next();
};
})()
}
};
Once your server is up and running you can check trace in Snappyflow Server.
For viewing trace in snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to
View dashboard -> Click on Tracing on lef side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/RefappNodeSail
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
Kubernetes
Node.JS Express
Install nodejs dependencies and save it in
package.json
usingnpm install --save elastic-apm-node@^3.20.0
npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries:"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"and run
npm install
to install dependenciesAdd initilization code at start of the file in
app.js
Get Snappyflow trace config using
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variables in Kubernetes deployment file.https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/
Once your server is up and running you can check trace in Snappyflow Server.
For viewing trace in Snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to: View dashboard -> Click on Tracing on left side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/refapp-express
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
Node.JS Sails
Install nodejs dependencies and save it in
package.json
usingnpm install --save elastic-apm-node@^3.20.0
npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries:"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"And run
npm install
to install dependenciesAdd initilization code at start of the file in
globals.js
present in config folder.Get Snappyflow trace config using
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}Attach apm object to globals – This is required so we can use apm variable in other files as part of global sails object
module.exports.globals = {
_: require('@sailshq/lodash'),
async: false,
models: true,
sails: true,
apm : apm,
logger: logger
};Also add middleware in
http.js
file present in config folder. Which allows to instrument our codemodule.exports.http = {
middleware: {
order: [
'elasticAPM'
],
elasticAPM: (function () {
return function (err, req, res, next) {
apm.middleware.connect();
if (typeof err !== 'undefined')
apm.captureError(err);
return next();
};
})()
}
};
Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variables in Kubernetes deployment file.https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/
If deploying with helm provide above variables in values.yaml and use them in deployment file of charts.
Once your server is up and running you can check trace in Snappyflow Server.
For viewing trace in snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to
View dashboard -> Click on Tracing on lef side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/RefappNodeSail
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
Docker
Node.JS Express
Install nodejs dependencies and save it in
package.json
usingRUN npm install --save elastic-apm-node@^3.20.0
RUN npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries:"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"And run
npm install
to install dependenciesAdd initilization code at start of the file in
app.js
Get Snappyflow trace config using
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}
Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variables indocker-compose.yml
or docker stack deployment file or at command line when using docker run command for deployment.Eg:
Docker-compose and stack: https://docs.docker.com/compose/environment-variables/
Docker run cli command:
docker run -d -t -i -e SF_PROJECT_NAME='<Project name>' \
-e SF_APP_NAME='<SF_APP_NAME>' \
-e SF_PROFILE_KEY='<snappyflow profile key>' \
--name <container_name> <dockerhub_id/image_name>Once your server is up and running you can check trace in Snappyflow Server.
// Project related info
For viewing trace in Snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to
View dashboard -> Click on Tracing on lef side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/refapp-express
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
Node.JS Sails
Install nodejs dependencies and save it in
package.json
usingRUN npm install --save elastic-apm-node@^3.20.0
RUN npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries:"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"And run ‘npm install’ to install dependencies
Add initilization code at start of the file in
globals.js
present in config folder.Get Snappyflow trace config using
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}Attach apm object to globals – This is required so we can use apm variable in other files as part of global sails object.
module.exports.globals = {
_: require('@sailshq/lodash'),
async: false,
models: true,
sails: true,
apm : apm,
logger: logger
};Also add middleware in
http.js
file present in config folder. Which allows to instrument our code.module.exports.http = {
middleware: {
order: [
'elasticAPM'
],
elasticAPM: (function () {
return function (err, req, res, next) {
apm.middleware.connect();
if (typeof err !== 'undefined')
apm.captureError(err);
return next();
};
})()
}
};
Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variables indocker-compose.yml
or docker stack deployment file or at command line when using docker run command for deployment.Eg:
Docker-compose and stack: https://docs.docker.com/compose/environment-variables/
Docker run cli command:
docker run -d -t -i -e SF_PROJECT_NAME='<SF_PROJECT_NAME>' \
-e SF_APP_NAME='<SF_APP_NAME>' \
-e SF_PROFILE_KEY='<snappyflow profile key>' \
--name <container_name> <dockerhub_id/image_name>Once your server is up and running you can check trace in Snappyflow Server.
For viewing trace in snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to
View dashboard -> Click on Tracing on lef side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/RefappNodeSail
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
ECS
Node.JS Express
Install nodejs dependencies and save it in
package.json
usingnpm install --save elastic-apm-node@^3.20.0
npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"And run
npm install
to install dependenciesAdd initilization code at start of the file in
app.js
Get Snappyflow trace config using:
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}
Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variables in add container section of task definitions.https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html
Once your server is up and running you can check trace in Snappyflow Server.
For viewing trace in Snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to: View dashboard -> Click on Tracing on left side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/refapp-express
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
Node.JS Sails
Install nodejs dependencies and save it in
package.json
usingnpm install --save elastic-apm-node@^3.20.0
npm install --save sf-apm-lib@^1.0.2or update
package.json
file with following entries"elastic-apm-node": "^3.20.0"
"sf-apm-lib": "^1.0.2"And run
npm install
to install dependenciesAdd initialization code at start of the file in
globals.js
present in config folder.Get Snappyflow trace config using
const Snappyflow = require('sf-apm-lib');
var sfObj = new Snappyflow(); // Initialize Snappyflow. By default intialization will take profileKey, projectName and appName from sfagent config.yaml.
// Add below part to manually configure the initialization
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
sfObj.init(profileKey, projectName, appName); // Manual override
let sfTraceConfig = sfObj.getTraceConfig();
// Start Trace to log feature section
// Add below line of code to enable Trace to log feature:
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_redact_body=true'
// Option Configs for trace to log
// Add below line to provide custom documentType (Default:"user-input"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_documentType=<document-type>'
// Add below line to provide destination index (Default:"log"):
sfTraceConfig['SFTRACE_GLOBAL_LABELS'] += ',_tag_IndexType=<index-type>' // Applicable values(log, metric)
// End trace to log sectionInitialize apm object using
var apm;
try {
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME>', // Specify your service name for tracing
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e);
}Attach apm object to globals – This is required so we can use apm variable in other files as part of global sails object
module.exports.globals = {
_: require('@sailshq/lodash'),
async: false,
models: true,
sails: true,
apm : apm,
logger: logger
};Also add middleware in
http.js
file present in config folder. Which allows to instrument our codemodule.exports.http = {
middleware: {
order: [
'elasticAPM'
],
elasticAPM: (function () {
return function (err, req, res, next) {
apm.middleware.connect();
if (typeof err !== 'undefined')
apm.captureError(err);
return next();
};
})()
}
};
Provide
SF_PROJECT_NAME
,SF_APP_NAME
,SF_PROFILE_KEY
as an environment variables in add container section of task definitions.https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html
Once your server is up and running you can check trace in Snappyflow Server.
For viewing trace in snappyflow server make sure project and app name is created or discovered with project name and app name specified in point no.2
Once project and app name is created go to
View dashboard -> Click on Tracing on lef side bar -> Click on view transaction -> Go to real time tab
For complete code refer sample app refer at:
https://github.com/snappyflow/tracing-reference-apps/tree/master/RefappNodeSail
- Note: 'captureBody':'all' config should be present in apm agent code instrumentation for Trace to Log feature.
AWS Lambda
Install dependency libraries in the node_modules directory using the npm install command
npm install sf-apm-lib@^1.0.2
npm install elastic-apm-node@^3.20.0Ref: https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html
Instrument lambda function to enable tracing
Add code outside lambda handler method to get tracing config and create trace client
// SnappyFlow Tracing config
const Snappyflow = require('sf-apm-lib');
let projectName = process.env.SF_PROJECT_NAME;
let appName = process.env.SF_APP_NAME;
let profileKey = process.env.SF_PROFILE_KEY;
var sfObj = new Snappyflow();
sfObj.init(profileKey, projectName, appName);
var apm;
try {
var sfTraceConfig = sfObj.getTraceConfig();
apm = require('elastic-apm-node').start({
serviceName: '<SERVICE_NAME_CHANGEME>',
serverUrl: sfTraceConfig['SFTRACE_SERVER_URL'],
globalLabels: sfTraceConfig['SFTRACE_GLOBAL_LABELS'],
verifyServerCert: sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'] === undefined ? false : sfTraceConfig['SFTRACE_VERIFY_SERVER_CERT'],
active: sfTraceConfig['SFTRACE_SERVER_URL'] === undefined ? false : true,
stackTraceLimit: sfTraceConfig['SFTRACE_STACK_TRACE_LIMIT'],
captureSpanStackTraces: sfTraceConfig['SFTRACE_CAPTURE_SPAN_STACK_TRACES'],
captureBody: 'all' ,
metricsInterval: '0s',
usePathAsTransactionName: true
})
} catch (e) {
console.log(e)
}Add custom instrumentation inside lambda handler method
Ref: https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-transactions.html
https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-spans.html
// Create custom transaction
var trans = apm.startTransaction('lambda handler', 'lambda');
//Create custom span is needed
var span = apm.startSpan('parse json');
// your CODE here
// End of span
if (span) span.end()
//Some more code part of the transaction or add more spans here. Don’t RETURN/EXIT //end custom transaction
trans.result = 'success';
trans.end();
// RETURN codeDeploy the lambda app. Follow README to test sample app
Reference app:
https://github.com/upendrasahu/aws-lambda-nodejs-tracing-sample
Configure Lambda function before trigger/invoke.
Add the environment variable
SF_PROFILE_KEY
and set the value to your profile key copied from SnappyFlow.Add environment variables
SF_APP_NAME
andSF_PROJECT_NAME
with appropriate values. Create this Project and Application in SnappyFlow if not already present.
At this point you can trigger lambda function and get tracing data in SnappyFlow.
Log Correlation
If you are using existing logger in your application then embed transaction id, trace id and span id using elastic apm node client object which was created at the start of the application. For more info refer apm initialization code.
Eg.
var traceId = 'None';
var transactionId = 'None';
var spanId = 'None';
if (typeof(apm) !== 'undefined') {
var apmTraceObj = apm.currentTraceIds; // Apm object having current trace ids
transactionId = apmTraceObj['transaction.id'] || 'None';
traceId = apmTraceObj['trace.id'] || 'None';
spanId = apmTraceObj['span.id'] || 'None';
}
var msg = `[${moment().format('DD/MMM/YYYY hh:mm:ss')}] [${level}] [${msg}] | elasticapm transaction.id=${transactionId} trace.id=${traceId} span.id=${spanId}\n`
For using Log correlation in application log file refer: https://www.elastic.co/guide/en/apm/agent/nodejs/current/log-correlation.html
Adding custom Snappyflow logger for log correlation
//Copy logger file from snappyflow reference app to location where you want to put. Initialize logger in your app using following code:
const logger = require("./logger").Logger;
logger.attachAPM(apm);
logger.setLogFilePath('/var/log/trace/ntrace.log'); //Put log file in /var/log/trace folder
logger.init();
//Write log
logger.debug('Hello world get api called')
logger.info('Hello world get api called')
logger.error('Some error ocurred')
For code reference refer: https://github.com/snappyflow/tracing-reference-apps/blob/master/refapp-express/logger.js
Send log correlation data to snappyflow server
Below are the modes for sending log correlated data to snappyflow server
For Appliance
Install sfagent and create config file.
Refer: https://docs.snappyflow.io/docs/Integrations/os/linux/sfagent_linux
Add elasticApmLog plugin to sfagent config.yaml and restart sfagent service. Eg. Config.yaml
key: <SF_PROFILE_KEY>
tags:
Name: <any-name>
appName: <SF_APP_NAME>
projectName: <SF_PROJECT_NAME>
logging:
plugins:
- name: elasticApmTraceLog
enabled: true
config:
log_level:
- error
- warning
- info
log_path: /var/log/trace/ntrace.log # Your app log file path
For Kubernetes
Specify following values in metadata labels section of deployment file.
snappyflow/appname: <SF_APP_NAME>
snappyflow/projectname: <SF_PROJECT_NAME>
snappyflow/component: gen-elastic-apm-log # This is must for tracing log correlation
Sample deployment file
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
io.kompose.service: express-node
snappyflow/appname: '<sf_app_name>'
snappyflow/projectname: '<sf_project_name>'
snappyflow/component: gen-elastic-apm-log
name: express-node
spec:
replicas: 1
selector:
matchLabels:
io.kompose.service: express-node
strategy: {}
template:
metadata:
labels:
io.kompose.service: express-node
snappyflow/appname: '<sf_app_name>'
snappyflow/projectname: '<sf_project_name>'
snappyflow/component: gen-elastic-apm-log
spec:
containers:
- env:
- name: SF_APP_NAME
value: '<sf_app_name>'
- name: SF_PROFILE_KEY
value: '<sf_profile_key>'
- name: SF_PROJECT_NAME
value: '<sf_project_name>'
image: refapp-node:latest
imagePullPolicy: Always
name: express-node
ports:
- containerPort: 3000
resources:
requests:
cpu: 10m
memory: 10Mi
limits:
cpu: 50m
memory: 50Mi
restartPolicy: Always
For viewing trace and logs in Snappyflow server make sure project and app name is created or discovered. Once project and app name is created.
Go to: View App dashboard -> Click on Tracing on left side bar -> Click on view transaction -> Go to real time tab Then click on any trace and go to logs tab to see the correlated logs to trace.
// Note: To get trace in snappyflow server we need log entries to adhere following log format:
<date in following format>
[10/Aug/2021 10:51:16] [<log_level>] [<message>] | elasticapm transaction.id=<transaction_id> trace.id=<trace_id> span.id=<span_id>