Node.js Agent version 3.xedit

3.21.1 2021/09/16edit

Bug fixesedit
  • Update types to avoid imports of @types/... modules (other than @types/node), so that TypeScript users of elastic-apm-node need not manually npm install @types/connect @types/pino @types/aws-lambda to compile. (#2331)

3.21.0 2021/09/15edit

  • Add the longFieldMaxLength integer configuration option (default 10000). Specific transaction/span/error fields (see the list below) will be truncated at this number of unicode characters. (#2193, #1921)

    The `errorMessageMaxLength` configuration option is now *deprecated*, but
    still supported. Users should switch to using `longFieldMaxLength. If
    `errorMessageMaxLength` is not specified, truncation of error messages will
    now use the `longFieldMaxLength` value.
    Note that ultimately the maximum length of any tracing field is limited by the
    configured for the receiving APM server.
    The fields affected by `longFieldMaxLength` are:
    • transaction.context.request.body, error.context.request.body - Before this change these fields were not truncated.
    • transaction.context.message.body, span.context.message.body, error.context.message.body - Before this change these fields were not truncated.
    • span.context.db.statement - Before this change this field was truncated at 10000 bytes. Truncation is now a number of unicode characters.
    • error.exception.message, error.log.message - Before this change, the default 2kB errorMessageMaxLength would apply.
  • Improve the TypeScript types by exporting more of interfaces: AgentConfigOptions, Transaction, Span, TransactionOptions, SpanOptions. (#2118)
Bug fixesedit
  • Fix a bug in apm.removePatch(module, aHandler) that would remove the last registered handler if aHandler did not match any currently registered handlers. (#2315)
  • Fix a crash in instrumentation of the old Elasticsearch client (elasticsearch) for some rarer cases of client options — for example passing multiple hosts. (#2312)
  • Ensure the internal HTTP(S) client requests made by the APM agent to APM server are not themselves traced. (#1168, #1136)
  • Fix crashing error with agent.registerMetric and active:false configuration. (#1799, #2290)

3.20.0 2021/08/12edit

Bug fixesedit
  • Fix failing tests and a possible runtime crash in @elastic/elasticsearch@7.14.0 instrumentation. (#2187)

3.19.0 2021/08/05edit

  • The agent now supports the 3.x branch of apollo-server-express. (#2155)
  • Add instrumentation support for mongodb@4.x. (#2171)
Bug fixesedit
  • The agent will no longer report counting metrics with a value of zero, and will remove these metrics from the registry. (#2163)

3.18.0 2021/07/20edit

  • Trace an incoming HTTP/1.1 request to an HTTP/2 server using the allowHTTP1 option. Before this change only incoming requests supporting HTTP/2 would be traced. (#2143)
  • Add instrumentation of the AWS SNS publish method when using the JavaScript AWS SDK v2 (aws-sdk). (#2157)
Bug fixesedit

3.17.0 2021/07/05edit

  • Add instrumentation of all AWS S3 methods when using the JavaScript AWS SDK v2 (aws-sdk).
  • Add disableSend configuration option. This supports some use cases using the APM agent without an APM server. (#2101)
  • Add instrumentation of all DynamoDB methods when using the JavaScript AWS SDK v2 (aws-sdk).
Bug fixesedit
  • Fix inconsistencies in HTTP spans from other APM agents. span.subtype will now be "http" for HTTP, HTTPS, and HTTP/2 outgoing spans — previously it was "http", "https", "http2", respectively. As well, span.action will now be the HTTP method (e.g. "GET", "PUT", "POST"), rather than "http". (#2075)
  • Fixed error where SQS messages sent without an active transactions could crash the agent. (#2113)
  • Fixed support for proxies in destination context (#1770)

3.16.0 - 2021/06/14edit

  • Added spanFramesMinDuration configuration field, allowing users to set a time threshold value that spans must reach before the agent will add a stack trace to the span. As a result, many short spans that previously included stack traces by default no longer will.
  • Prefer W3C "traceparent" header over "elastic-apm-traceparent" for incoming requests. #2079
Bug fixesedit
  • Fix a crash (TypeError: lastPrepareStackTrace) in the agent when used with React v17 and later (#1980).
  • Performance improvements have been made in error and stacktrace capture (#2094). This also included in two bug fixes:

    • Before this change, some captured errors (for example a next(new Error('boom') from an Express handler) would mark the error as "unhandled" incorrectly. "Unhandled" exceptions are those caught by an uncaughtException handler.
    • Before this change, source context lines for a stacktrace would not properly use the "sourcesContext" field of a file’s source map.

3.15.0 - 2021/05/19edit

  • Add support for Node.js v16. (This also drops testing of Node.js v13 releases.) #2055
Bug fixesedit
  • Update TypeScript typings for Agent.setLabel and Agent.addLabels to include the stringify argument that was added in v3.11.0.

3.14.0 - 2021/04/19edit

  • Add apm.addMetadataFilter(fn) for filtering the metadata object sent to APM server.
  • The handling of sending events (transactions, spans, errors) to APM server has improved in a few ways. During temporary spikes in load and/or an APM server that is unresponsive, the agent will buffer a number of events and drop them above a certain limit (configurable via maxQueueSize). This helps ensure the agent does not overly consume memory and CPU. As well, the agent will now backoff when the APM server errors. Finally, improved error handling means it will terminate failing requests to the APM server more quickly.

    Note: v1 of this agent (EOL’d 2 years ago), included a maxQueueSize config variable with a different meaning. If you have a lingering usage of that setting (also possibly as the ELASTIC_APM_MAX_QUEUE_SIZE environment variable), then it should be removed.

  • Adds support for Amazon SQS queues via aws-sdk instrumentation that partially implements the APM messaging spec, and adds,, and metrics for SQS queues.
Bug fixesedit
  • Fixed bug where the URL property for outgoing HTTP request spans was set with the server’s IP address rather than its hostname. The Agent now sets this property with the actual URL requested by Node.js. #2035
  • Fixed bug where external services were not listed under Dependencies on the APM Service Overview page due to the trace-context propagated sample_rate value not being set on either transactions or spans.

3.13.0 - 2021/04/06edit

  • The APM agent’s own internal logging now uses structured JSON logging using the pino API, and formatted in ecs-logging format. The log records on stdout are now single-line JSON objects. For example:

    # Before
    APM Server transport error (ECONNREFUSED): connect ECONNREFUSED
    # After
    "ecs":{"version":"1.6.0"},"message":"APM Server transport error (ECONNREFUSED): connect ECONNREFUSED"}

    Pretty formatting (and filtering) on the console may be done via the ecslog tool.

    A custom logger is still supported as before. However, a non-pino custom logger will only receive the "message" field, and not structured log fields as they are added over time.

  • Add support for setting the ELASTIC_APM_LOGGER=false environment variable to disable/ignore a given custom logger. This is to support easier Debug mode for troubleshooting.
Bug fixesedit
  • Lock package dependency "elastic-apm-http-client@9.6.0" to avoid using v9.7.0 for now, because it is breaking tests. A coming release will get back on the latest of this dependency. #2032
  • Remove the "ancestors" field from a log.trace message on startup. Its info is a duplicate of info in the "startTrace" field in the same log record. #2005
  • Remove the accidental nodejs.eventloop.delay.ns metric that was always reporting a zero value. The existing is the intended metric. #1993

3.12.1 - 2021/02/25edit

Bug fixesedit

3.12.0 - 2021/02/21edit

  • feat: Set span outcome to success or failure depending on whether an error was captured during when the span was active. #1814
  • feat: Adds public setOutcome method to span and transaction APIs, and adds a top level setTransactionOutcome and setSpanOutcome to set outcome values for the current active transaction or active span.
  • Limit the transactionSampleRate value to 4 decimal places of precision according to the shared APM spec. This ensures that propagated sampling rate in the tracestate header is short and consistent. #1979
Bug fixesedit
  • fix: It was possible for fetching central config to result in the cloudProvider config value being reset to its default. #1976
  • fix: fixes bug where tedious could crash the agent on bulk inserts #1935
    Reported via the forum. The error symptom was: Cannot read property 'statement' of undefined

3.11.0 - 2021/02/08edit

  • feat: add apm.getServiceName() #1949
    This will be used by ecs-logging packages to integrate with APM.
  • feat: support numeric and boolean labels #1909
    Add an optional stringify option to apm.setLabel(name, version, stringify = true) and apm.addLabels(labels, stringify = true), which can be set false to allow numeric and boolean labels. Stringify defaults to true for backwards compatibility — stringification will be removed in a future major version.
  • feat: added support for cloud metadata fetching #1937
    Agent now collects information about its cloud environment and includes this data in the APM Server’s metadata payload. See the spec for more information.

3.10.0 - 2021/01/11edit

  • feat: Improve handling of raw body parsing The agent will now report raw/Buffer encoded post bodies as <Buffer>.
  • feat: Add support for api keys #1818
    This allows the usage of API keys for authentication to the APM server
  • feat: Add automatic instrumentation of the @elastic/elasticsearch package #1870

    The instrumentation of the legacy "elasticsearch" package has also changed slightly to commonalize:

    • "span.context.destination" is set on all Elasticsearch spans, not just a subset of query-like API endpoints.
    • For query-like API endpoints (e.g. /_search), the capturing of query details on "span.context.db.statement" has changed (a) to include both the query params and the request body if both exist (separated by \n\n) and (b) to URL encode the query params, rather than JSON encoding.
  • feat: Add captureAttributes boolean option to apm.captureError() to allow disabling the automatic capture of Error object properties. This is useful for cases where those properties should not be sent to the APM Server, e.g. for performance (large string fields) or security (PII data). #1912
  • feat: Add log_level central config support. #1908
  • feat: Add sanitize_field_names configuration option.
    Allows users to configure a list of wildcard patterns to remove items from the agent’s HTTP header and application/x-www-form-urlencoded payloads. #1898

Bug fixesedit
  • fix: Fix parsing of comma-separated strings for relevant config vars to allow whitespace around the commas. E.g.:

    export ELASTIC_APM_TRANSACTION_IGNORE_URLS='/ping, /metrics*'

    Config vars affected are: disableInstrumentations, transactionIgnoreUrls addPatch, and globalLabels.

  • fix: Correct the environment variable for setting transactionIgnoreUrl (added in v3.9.0) from ELASTIC_TRANSACTION_IGNORE_URLS to ELASTIC_APM_TRANSACTION_IGNORE_URLS.

3.9.0 - 2020/11/30edit

  • feat: support fastify 3 #1891
    Adds .default and .fastify module.exports to instrumented fastify function for 3.x line, and prefers req.routerMethod and req.routerPath for transaction name
  • feat: Set "destination" context on spans for "mongodb". #1893
    This allows Kibana APM Service Maps to show a "mongodb" node for services using the mongodb package (which includes mongoose and mongojs).
  • feat: transactionIgnoreUrl wildcard matching #1870
    Allows users to ignore URLs using simple wildcard matching patterns that behave the same across language agents. See
Bug fixesedit
  • fix: treat set-cookie in response headers as sensitive data #1886
  • fix: Synchronous spans would never have span.sync == true. #1879

3.8.0 - 2020/11/09edit

  • feat: expand k8s pod ID discovery regex #1863
  • feat: implements tracestate #1828
    Expands support for the W3C Trace Context specification by adding a tracestate header implementation, and uses this new header to track the Elastic transaction sample rate across a trace’s service boundaries.
  • feat: add span and transaction outcome #1824
    This adds an "outcome" field to HTTP(S) transactions and spans.
Bug fixesedit
  • fix(pg): prevent unhandled promise rejection #1846
  • fix: redis@2.x instrumentation was broken #1852
  • A number of fixes to the test suite.

3.7.0 - 2020/8/10edit

  • feat(knex): add support for 0.21.x #1801
  • feat(redis): add support for v3.x #1641
  • feat(graphql): add support for 15.x #1795
  • feat(koa-router): add support for 9.x #1772
  • fix(elasticsearch): ensure requests can be aborted #1566
  • fix: end span if outgoing http request ends prematurely #1583
  • fix: don’t throw on invalid URL #1771
  • fix: patch apollo-server-core > 2.14 correctly #1796
  • fix: add currentTraceIds to typings #1733

3.6.1 - 2020/5/20edit

  • fix(package): bump elastic-apm-http-client to ^9.4.0 #1756

3.6.0 - 2020/5/18edit

  • feat: add destination metadata for db spans #1687
  • feat: add support for Node.js 14 #1742
  • feat(pg): add support for pg v8.x #1743
  • feat: add metrics for external memory #1724
  • feat: enrich spans with destination info #1685
  • fix(instrumentation): add .js to module path #1711

3.5.0 - 2020/3/9edit

  • feat(error): get stack trace from Error-like objects #1613
  • fix: add logUncaughtExceptions conf option to TypeScript typings #1668

3.4.0 - 2020/2/21edit

  • feat: support W3C TraceContext traceparent header #1587
  • feat: add custom metrics API (experimental) #1571
  • feat(koa-router): add support for v8.x #1642
  • fix(cassandra): improve support for cassandra-driver v4.4.0+ #1636
  • fix: support promisifying setTimeout and friends #1636

3.3.0 - 2019/12/13edit

  • feat(config): add serverCaCertFile config #1560
  • feat(config): add central config support for transactionMaxSpans and captureBody #1555

3.2.0 - 2019/11/19edit

  • fix(metrics): only register collectors if enabled #1520
  • fix(ioredis): prevent unhandled promise rejection #1523
  • chore: add Node 13 to supported engines #1524

3.1.0 - 2019/10/16edit

  • feat(mongodb): instrumentation #1423
  • fix(package): update elastic-apm-http-client to version 9.0.0 #1419
  • perf: cache ids value of transactions and spans #1434
Bug fixesedit
  • fix: always end transaction when socket is closed prematurely #1439
  • fix: change logUncaughtExceptions default to false #1432
  • fix: write stack trace of uncaught exceptions to STDERR #1429

3.0.0 - 2019/9/30edit

Breaking changesedit
  • feat: allow manual instrumentation with instrument: false #1114
  • feat: allow setting span/transaction type, subtype, and action separately (the behavior of the old type has changed) #1292
  • feat: use external as span type instead of ext #1291
  • refactor(graphql): use custom transaction type graphql for graphql requests instead of request #1245
  • feat(http): add instrumentIncomingHTTPRequests config (disableInstrumentations now behaves differently) #1298
  • chore: remove deprecated APIs #1413
  • chore: drop support for older Node.js versions #1383