Elastic APM Node.js Agent

This is the official Node.js agent for Elastic APM.

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

Installation

npm install elastic-apm-node --save

Quick start

1. To run Elastic APM for your own applications, make sure you have the prerequisites in place first. This agent is compatible with APM Server v6.5 and above. For support for previous releases of the APM Server, use version 1.x of the agent. For details see Getting Started with Elastic APM

2. Now follow the documentation links below relevant to your framework or stack to get set up

Documentation

• Table of contents
• Introduction
• Get started with Express
• Get started with hapi
• Get started with Koa
• Get started with Restify
• Get started with Fastify
• Get started with Lambda
• Get started with a custom Node.js stack
• Advanced Setup and Configuration
• API Reference
• Custom Transactions
• Custom Spans
• Metrics
• Performance Tuning
• Source Map Support
• OpenTracing Support
• Supported Technologies
• Upgrading
• Troubleshooting

Contributing

Contributions are welcome, but we recommend that you take a moment and read our contribution guide first.

To see what data is being sent to the APM Server, use the environment variable ELASTIC_APM_PAYLOAD_LOG_FILE (or the config option payloadLogFile) to speicfy a log file, e.g:

ELASTIC_APM_PAYLOAD_LOG_FILE=/tmp/payload.ndjson

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

License

BSD-2-Clause

Made with ♥️ and ☕️ by Elastic and our community.

2.11.6 - 2019/6/11

• fix(express): don't swallow error handling middleware (#1111)

2.11.5 - 2019/5/27

• fix(metrics): report correct CPU usage on Linux (#1092)
• fix(express): improve names for routes added via app.use() (#1013)

2.11.4 - 2019/5/27

• fix: don't add traceparent header to signed AWS requests (#1089)

2.11.3 - 2019/5/22

• fix(span): use correct logger location (#1081)

2.11.2 - 2019/5/21

• fix: url.parse expects req.url not req (#1074)
• fix(express-slash): expose express handle properties (#1070)

2.11.1 - 2019/5/10

• fix(instrumentation): explicitly use require (#1059)
• chore: add Node.js 12 to package.json engines field (#1057)

2.11.0 - 2019/5/3

• chore: rename tags to labels (#1019)
• feat(config): support global labels (#1020)
• fix(config): do not use ELASTIC_APM_ prefix for k8s (#1041)
• fix(instrumentation): prevent handler leak in bindEmitter (#1044)

2.10.0 - 2019/4/15

• feat(express-graphql): add support for version ^0.8.0 (#1010)
• fix(package): bump elastic-apm-http-client to ^7.2.2 so Kubernetes metadata gets corrected recorded (#1011)
• fix(ts): add TypeScript typings for new traceparent API (#1001)

2.9.0 - 2019/4/10

• feat: add traceparent getter to agent, span and transaction (#969)
• feat(template): add support for jade and pug (#914)
• feat(elasticsearch): capture more types of queries (#967)
• feat: sync flag on spans and transactions (#980)
• fix(agent): init config/logger before usage (#956)
• fix: don't add response listener to outgoing requests (#974)
• fix(agent): fix basedir in debug mode when starting agent with -r (#981)
• fix: ensure Kubernetes/Docker container info is captured (#995)

2.8.0 - 2019/4/2

• feat: add agent.setFramework() method (#966)
• feat(config): add usePathAsTransactionName config option (#907)
• feat(debug): output configuration if logLevel is trace (#972)
• fix(express): transaction default name is incorrect (#938)

2.7.1 - 2019/3/28

• fix: instrument http/https.get requests (#954)
• fix: don't add traceparent header to S3 requests (#952)

2.7.0 - 2019/3/26

• feat: add patch registry (#803)
• feat: allow sub-modules to be patched (#920)
• feat: add TypeScript typings (#926)
• fix: update measured-reporting to fix Windows installation issue (#933)
• fix(lambda): do not wrap context (#931)
• fix(lambda): fix cloning issues of context (#947)
• fix(metrics): use noop logger in metrics reporter (#912)
• fix(transaction): don't set transaction result if it's null (#936)
• fix(agent): allow flush callback to be undefined (#934)
• fix: handle promise rejection in case Elasticsearch client throws (#870)
• chore: change 'npm run' command namespaces (#944)

2.6.0 - 2019/3/5

• feat: add support for Fastify framework (#594)
• feat(lambda): accept parent span in lambda wrapper (#881)
• feat(lambda): support promise form (#871)
• fix: ensure http headers are always recorded as strings (#895)
• fix(metrics): prevent 0ms timers from being created (#872)
• fix(config): apiRequestSize should be 768kb (#848)
• fix(express): ensure correct transaction names (#842)

2.5.1 - 2019/2/4

• fix(metrics): ensure NaN becomes 0, not null (#837)

2.5.0 - 2019/1/29

• feat(metrics): added basic metrics gathering (#731)

2.4.0 - 2019/1/24

• feat: add ability to set custom log message for errors (#824)
• feat: add ability to set custom timestamp for errors (#823)
• feat: add support for custom start/end times (#818)

2.3.0 - 2019/1/22

• fix(parsers): move port fix into parser (#820)
• fix(mongo): support 3.1.10+ (#793)
• feat(config): add captureHeaders config (#788)
• feat(config): add container info options (#766)

2.2.1 - 2019/1/21

• fix: ensure request.url.port is a string on transactions (#814)

2.2.0 - 2019/1/21

• feat(koa): record framework name and version (#810)
• feat(cassandra): support 4.x (#784)
• feat(config): validate serverUrl port (#795)
• feat: add transaction.type to errors (#805)
• fix: filter outgoing http headers with any case (#799)
• fix: we don't support mongodb-core v3.1.10+ (#792)

2.1.0 - 2019/1/15

• feat(error): include sampled flag on errors (#767)
• feat(span): add tags to spans (#757)
• fix(tedious): don't fail on newest tedious v4.1.3 (#775)
• fix(graphql): fix span name for unknown queries (#756)

2.0.6 - 2018/12/18

• fix(graphql): don't throw on invalid query (#747)
• fix(koa-router): support more complex routes (#749)

2.0.5 - 2018/12/12

• fix: don't create spans for APM Server requests (#735)

2.0.4 - 2018/12/7

• chore: update engines field in package.json (#727)
• chore(package): bump random-poly-fill to ^1.0.1 (#726)

2.0.3 - 2018/12/7

• fix(restify): support an array of handlers (#709)
• fix: don't throw on older versions of Node.js 6 (#711)

2.0.2 - 2018/12/4

• fix: use randomFillSync polyfill on Node.js <6.13.0 (#702)
• fix(hapi): ignore internal events channel (#700)

2.0.1 - 2018/11/26

• fix: log APM Server API errors correctly (#692)

2.0.0 - 2018/11/14

• Breaking changes:
  • chore: remove support for Node.js 4 and 9
  • chore: remove deprecated buildSpan function (#642)
  • feat: support APM Server intake API version 2 (#465)
  • feat: improved filtering function API (#579)
  • feat: replace double-quotes with underscores in tag names (#666)
  • feat(config): change config order (#604)
  • feat(config): support time suffixes (#602)
  • feat(config): stricter boolean parsing (#613)
• feat: add support for Distributed Tracing (#538)
• feat(transaction): add transaction.ensureParentId function (#661)
• feat(config): support byte suffixes (#601)
• feat(transaction): restructure span_count and include total (#553)
• perf: improve Async Hooks implementation (#679)

1.14.3 - 2018/11/13

• fix(async_hooks): more reliable cleanup (#674)

1.14.2 - 2018/11/10

• fix: prevent memory leak due to potential reference cycle (#667)

1.14.1 - 2018/11/8

• fix: promise.then() resolve point (#663)

1.14.0 - 2018/11/6

• feat(agent): return uuid in captureError callback (#636)
• feat(apollo-server-express): set custom GraphQL transaction names (#648)
• feat(finalhandler): improve capturing of errors in Express (#629)
• fix(http): bind writeHead to transaction (#637)
• fix(shimmer): safely handle property descriptors (#634)

1.13.0 - 2018/10/19

• feat(ioredis): add support for ioredis version 4.x (#516)
• fix(ws): allow disabling WebSocket instrumentation (#599)
• fix: allow flushInterval to be set from env (#568)
• fix: default transactionMaxSpans to 500 (#567)

1.12.0 - 2018/8/31

• feat(restify): add Restify instrumentation (#517)
• feat(config): default serviceName to package name (#508)
• fix: always call agent.flush() callback (#537)

1.11.0 - 2018/8/15

• feat(filters): filter set-cookie headers (#485)
• fix(express): cannot create property symbol (#510)

1.10.2 - 2018/8/8

• fix: ensure logger config can update (#503)
• perf: improve request body parsing speed (#492)

1.10.1 - 2018/7/31

• fix(graphql): handle execute args object (#484)

1.10.0 - 2018/7/30

• feat(cassandra): instrument Cassandra queries (#437)
• feat(mssql): instrument SQL Server queries (#444)

1.9.0 - 2018/7/25

• fix(parsers): use basic-auth rather than req.auth (#475)
• feat(agent): add currentTransaction getter (#462)
• feat: add support for ws 6.x (#464)

1.8.3 - 2018/7/11

• perf: don't patch newer versions of mimic-response (#442)

1.8.2 - 2018/7/4

• fix: ensure correct streaming when using mimic-response (#429)

1.8.1 - 2018/6/27

• fix: improve ability to run in an environment with muliple APM vendors (#417) (via require-in-the-middle#11)

1.8.0 - 2018/6/23

• feat: truncate very long error messages (#413)
• fix: be unicode aware when truncating body (#412)

1.7.1 - 2018/6/20

• fix(express-queue): retain continuity through express-queue (#396)

1.7.0 - 2018/6/18

• feat(mysql): support mysql2 module (#298)
• feat(graphql): add support for the upcoming GraphQL v14.x (#399)
• feat(config): add option to disable certain instrumentations (#353)
• feat(http2): instrument client requests (#326)
• fix: get remoteAddress before HTTP request close event (#384)
• fix: improve capture of spans when EventEmitter is in use (#371)

1.6.0 - 2018/5/28

• feat(http2): instrument incoming http2 requests (#205)
• fix(agent): allow agent.endTransaction() to set result (#350)

1.5.4 - 2018/5/15

• chore: allow Node.js 10 in package.json engines field (#345)

1.5.3 - 2018/5/14

• fix: guard against non string err.message

1.5.2 - 2018/5/11

• fix(express): string errors should not be reported

1.5.1 - 2018/5/10

• fix: don't throw if span callsites can't be collected

1.5.0 - 2018/5/9

• feat: add agent.addTags() method (#313)
• feat: add agent.isStarted() method (#311)
• feat: allow calling transaction.end() with transaction result (#328)
• fix: encode spans even if their stack trace can't be captured (#321)
• fix(config): restore custom logger feature (#299)
• fix(doc): lambda getting started had old argument (#296)

1.4.0 - 2018/4/9

• feat(lambda): implement manual lambda instrumentation (#234)

1.3.0 - 2018/3/22

• feat(request): include ppid (#286)

1.2.1 - 2018/3/15

• fix(span): Do not pass stack frames into promises (memory leak fix) (#269)

1.2.0 - 2018/3/13

• feat(config): add serverTimeout (#238)
• fix(config): set default maxQueueSize to 100 (#270)
• feat(ws): add support for ws v5 (#267)

1.1.1 - 2018/3/4

• fix(mongodb): don't throw if span cannot be built (#265)

1.1.0 - 2018/2/28

• feat: add agent.startSpan() function (#262)
• feat(debug): output more debug info on start (#254)

1.0.3 - 2018/2/14

• fix: ensure context.url.full property is truncated if too long (#242)

1.0.2 - 2018/2/13

• fix(express): prevent invalid errors from crashing (#240)

1.0.1 - 2018/2/9

• fix: don't add req/res to unsampled transactions (#236)

1.0.0 - 2018/2/6

• feat(instrumentation): support sampling (#154)
• feat(transaction): add transactionMaxSpans config option (#170)
• feat(errors): add captureError call location stack trace (#181)
• feat: allow setting of framework name and version (#228)
• feat(protcol): add url.full to intake API payload (#166)
• refactor(config): replace logBody with captureBody (#214)
• refactor(config): unify config options with python (#213)
• fix: don't collect source code for in-app span frames by default (#229)
• fix(protocol): report dropped span counts in intake API payload (#172)
• refactor(protocol): always include handled flag in intake API payload (#191)
• refactor(protocol): move process fields to own namespace in intake API payload (#155)
• refactor(protocol): rename uncaught to handled in intake API payload (#140)
• refactor(protocol): rename in_app to library_frame in intake API payload (#96)
• refactor: rename app to service (#93)
• refactor: rename trace to span (#92)

0.12.0 - 2018/1/24

• feat(*): control amount of source context lines collected using new config options (#196)
• feat(agent): add public flush function to force flush of transaction queue: agent.flush([callback]) (#187)
• feat(mongodb): add support for mongodb-core 3.x (#190)
• refactor(config): update default flushInterval to 10 seconds (lower memory usage) (#186)
• chore(*): drop support for Node.js 5 and 7 (#169)
• refactor(instrumentation): encode transactions as they are added to the queue (lower memory usage) (#184)

0.11.0 - 2018/1/11

• feat(*): Set default stack trace limit to 50 frames (#171)
• feat(ws): add support for ws@4.x (#164)
• feat(errors): associate errors with active transaction

0.10.0 - 2018/1/3

• feat(express): auto-track errors (BREAKING CHANGE: removed express middleware) (#127)
• feat(hapi): add hapi 17 support (#146)
• fix(*): fix Node.js 8 support using async_hooks (#77)
• fix(graphql): support sync execute (#139)
• refactor(agent): make all config properties private (BREAKING CHANGE) (#107)

0.9.0 - 2017/12/15

• feat(conf): allow serverUrl to contain a sub-path (#116)
• refactor(*): better format of error messages from the APM Server (#108)

0.8.1 - 2017/12/13

• docs(*): we're now in beta! (#103)

0.8.0 - 2017/12/13

• feat(handlebars): instrument handlebars (#98)

0.7.0 - 2017/12/6

• feat(parser): add sourceContext config option to control if code snippets are sent to the APM Server (#87)
• fix(*): move https-pem to list of devDependencies

0.6.0 - 2017/11/17

• feat(queue): add maxQueueSize config option (#56)

0.5.0 - 2017/11/17

• refactor(*): drop support for Node.js <4 (#65)
• refactor(*): rename module to elastic-apm-node (#71)
• feat(queue): add fuzziness to flushInterval (#63)

0.4.0 - 2017/11/15

• fix(https): instrument https.request in Node.js v9
• refactor(http): log HTTP results in groups of 100 (#68)
• fix(api): add language to APM Server requests (#64)
• refactor(trans): set default transaction.result to success (#67)
• refactor(config): rename timeout config options (#59)

0.3.1 - 2017/10/3

• fix(parsers): don't log context.request.url.search as null (#48)
• fix(parsers): separate hostname and port when parsing Host header (#47)

0.3.0 - 2017/9/20

• fix(instrumentation): don't sample transactions (#40)
• feat(graphql): include GraphQL operation name in trace and transaction names (#27)
• feat(tls): add validateServerCert config option (#32)
• feat(parser): support http requests with full URI's (#26)
• refactor(*): remove appGitRef config option
• fix(instrumentation): fix setting of custom flushInterval
• feat(elasticsearch): add simple Elasticsearch instrumentation
• fix(*): don't start agent if appName is invalid

0.2.0 - 2017/8/28

• refactor(*): support new default port 8200 in APM Server
• refactor(*): support new context.response status code format

0.1.1 - 2017/8/17

• fix(instrumentation): don't fail when sending transactions to APM Server

0.1.0 - 2017/8/17

• Initial release