Add CONTRIBUTING.md

Elastic APM Node.js Agent

This is the official Node.js application performance monitoring (APM) agent for the Elastic Observability solution. It is a Node.js package that runs with your Node.js application to automatically capture errors, tracing data, and performance metrics. APM data is sent to your Elastic Observability deployment -- hosted in Elastic's cloud or in your own on-premises deployment -- where you can monitor your application, create alerts, and quick identify root causes of service issues.

If you have any feedback or questions, please post them on the Discuss forum.

Installation

npm install --save elastic-apm-node

Getting started

First, you will need an Elastic Stack deployment. This is a deployment of APM Server (which receives APM data from the APM agent running in your application), Elasticsearch (the database that stores all APM data), and Kibana (the application that provides the interface to visualize and analyze the data). If you do not already have an Elastic deployment to use, follow this APM Quick Start guide to create a free trial on Elastic's cloud. From this deployment you will need the APM serverUrl and secretToken (or a configured apiKey) to use for configuring the APM agent.

Next, the best and easiest way to see how to install and start the APM agent is to follow one of the "Get started" guides for the web framework or technology that you are using:

Typically, the quick start steps are:

Install the APM agent package as a dependency:
```
npm install --save elastic-apm-node
```

Configure and start the APM agent. For the APM agent's automatic instrumentation of popular modules to work, it must be started before your application imports its other dependencies. For example, if you use CommonJS, then put this at the very top of your main application file:

require('elastic-apm-node').start({
    serverUrl: '<serverUrl from your Elastic Stack deployment>',
    secretToken: '<secretToken from your Elastic Stack deployment>'
    serviceName: '...', // https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#service-name
    environment: '...', // https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#environment
});

There are other ways to start the APM agent: for example, to support starting the APM agent without having to change application code; or to avoid certain surprises when using TypeScript or other transpilers like Babel or esbuild. See Starting the agent for a reference of all ways to start the agent and for details on gotchas with transpilers and bundlers (like Webpack and esbuild).

If your application is using ES modules, please see ECMAScript module support for the current experimental support.

Documentation

The full Node.js APM agent documentation is here. Some important links:

Release notes
Supported Technologies describes the supported Node.js versions, which modules (and version ranges) are automatically traced, and other technologies.
Configuring the agent describes the different ways to configure the APM agent (via options to apm.start(...), environment variables, or other mechanisms).
Configuration options is a full configuration reference.
Troubleshooting describes some common issues and a way to get debugging output from the APM agent for bug reports.
Upgrading includes a guide for upgrading from each past major version of the APM agent.
Metrics describes the metrics that the APM agent automatically collects.
The APM agent includes an OpenTelemetry Bridge that allows one to use the vendor-agnostic OpenTelemetry API for manual instrumentation in your application, should you require manual instrumentation.

Active release branches

The following git branches are active:

The "main" branch is being used for 4.x releases.
The "3.x" branch is being used for 3.x maintenance releases. The 3.x line will be supported until 2024-03-07 -- for 6 months after the release of v4.0.0.

Contributing

Contributions are very welcome. You can get in touch with us through our Discuss forum. If you have found an issue, you can open an issue at https://github.com/elastic/apm-agent-nodejs/issues.

If you are considering contributing code to the APM agent, please read our contribution guide.

Please see TESTING.md for instructions on how to run the test suite.

License

BSD-2-Clause

Made with ♥️ by Elastic and our community.

Release	Initial Release	LTS Start	Maintenance Start	End-of-Life
v0.10	2013-03-11			2016-10-31
v0.12	2015-02-06			2016-12-31
v4	2015-09-08	2015-10-12	2017-04-01	2018-04-30
v5	2015-10-29		2016-04-30	2016-06-30
v6	2016-04-26	2016-10-18	2018-04-30	2019-04-01
v7	2016-10-25		2017-04-30	2017-06-30
v8	2017-05-30	2017-10-31	Apr 2019	Dec 2019
v9	2017-10-01		Apr 2018	Jun 2018
v10	Apr 2018	Oct 2018	Apr 2020	Apr 2021

	exports.getContextFromRequest = function (req, logBody) {
	var raw = req.originalUrl \|\| req.url
	var url = parseUrl(raw \|\| '')
	var host = typeof req.headers.host === 'string' ? req.headers.host.split(':') : null
	var context = {
	http_version: req.httpVersion,
	method: req.method,
	url: {
	raw: raw
	},
	socket: {
	remote_address: req.socket.remoteAddress,
	encrypted: !!req.socket.encrypted
	},
	headers: objectAssign({}, req.headers)
	}

	if (url.protocol) context.url.protocol = url.protocol
	if (url.hostname) context.url.hostname = url.hostname
	else if (host) context.url.hostname = host[0]
	if (url.port) context.url.port = url.port
	else if (host && host.length === 2) context.url.port = host[1]
	if (url.pathname) context.url.pathname = url.pathname
	if (url.search) context.url.search = url.search

	var contentLength = parseInt(req.headers['content-length'], 10)
	var transferEncoding = req.headers['transfer-encoding']
	var chunked = typeof transferEncoding === 'string' && transferEncoding.toLowerCase() === 'chunked'
	var body = req.json \|\| req.body \|\| req.payload
	var haveBody = body && (chunked \|\| contentLength > 0)

	if (haveBody) {
	if (logBody) {
	var bodyStr = typeof body === 'string' ? body : stringify(body)
	if (bodyStr.length > exports._MAX_HTTP_BODY_CHARS) {
	body = bodyStr.slice(0, exports._MAX_HTTP_BODY_CHARS)
	}
	context.body = body
	} else {
	context.body = '[REDACTED]'
	}
	}

	return context
	}

	agent.captureError('Socket closed with active HTTP request (>' + (agent.timeout.errorThreshold / 1000) + ' sec)', {
	request: req,
	extra: { abortTime: duration }
	})

	// max 300 stack frames
	if (frames.length > 300) {
	frames = frames.slice(0, 300)
	}

elastic / apm-agent-nodejs Goto Github PK

apm-agent-nodejs's Introduction

Elastic APM Node.js Agent

Installation

Getting started

Documentation

Active release branches

Contributing

License

apm-agent-nodejs's People

Contributors

Stargazers

Watchers

Forkers

apm-agent-nodejs's Issues

Gotcha

Tasks

Problem

Background

Solution 1

Solution 2

Solution x

Recommend Projects

Recommend Topics

Recommend Org