<picture><source media="(prefers-color-scheme: dark)" srcset="https://github.com/newrelic/opensource-website/raw/main/src/images/categories/dark/Community_Plus.png"><source media="(prefers-color-scheme: light)" srcset="https://github.com/newrelic/opensource-website/raw/main/src/images/categories/Community_Plus.png"></picture>

New Relic AWS SDK Instrumentation

New Relic's official AWS SDK package instrumentation for use with the Node.js agent. Provides instrumentation for the AWS SDK (aws-sdk) npm package.

Installation

This package is a dependency of the the Node Agent, and the average user should not need to install it manually.

Getting Started

Our instrumentation automatically tracks all SDK calls as "external" activities. In addition, the following have more specific instrumentation to capture additional data store or queue information.

• Amazon DynamoDB
• Amazon Simple Notification Service (SNS)
• Amazon Simple Queue Service (SQS)

Testing

This module includes a list of unit and functional tests. To run these tests, use the following command

$ npm run test

You may also run individual test suites with the following commands

$ npm run unit
$ npm run versioned

Support

Should you need assistance with New Relic products, you are in good hands with several support channels.

If the issue has been confirmed as a bug or is a feature request, please file a GitHub issue.

Support Channels

• New Relic and AWS. AWS specific agent documentation
• New Relic Documentation: Comprehensive guidance for using our platform
• New Relic Community: The best place to engage in troubleshooting questions
• New Relic Developer: Resources for building a custom observability applications
• New Relic University: A range of online training for New Relic users of every level
• New Relic Technical Support 24/7/365 ticketed support. Read more about our Technical Support Offerings.

Privacy

At New Relic we take your privacy and the security of your information seriously, and are committed to protecting your information. We must emphasize the importance of not sharing personal data in public forums, and ask all users to scrub logs and diagnostic information for sensitive information, whether personal, proprietary, or otherwise.

We define "Personal Data" as any information relating to an identified or identifiable individual, including, for example, your name, phone number, post code or zip code, Device ID, IP address and email address.

Please review New Relic’s General Data Privacy Notice for more information.

Roadmap

See our roadmap, to learn more about our product vision, understand our plans, and provide us valuable feedback.

Contribute

We encourage your contributions to improve New Relic's AWS SDK Instrumentation! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.

If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at opensource@newrelic.com.

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.

If you would like to contribute to this project, please review these guidelines.

To all contributors, we thank you! Without your contribution, this project would not be what it is today. We also host a community project page dedicated to the New Relic AWS SDK Instrumentation package.

License

The New Relic AWS SDK Instrumentation package is licensed under the Apache 2.0 License.

v7.4.2 (2024-06-05)

Miscellaneous chores

• Revert "refactor: Updated aws sdk instrumentation to construct specs at instrumentation (#259)" (#286) (87678d4)
  • This will allow customers using newrelic < 11.11.0 to no longer crash when using aws-sdk v2 or v3.

v7.4.1 (2024-04-09)

Miscellaneous chores

• Fixed typo on sqs v3 name (#282) (6836a48)

Continuous integration

• Removed use_new_release input from prepare release workflow (#283) (d63bdd2)
• Removed changelog.json file (#281) (e4ac38f)

v7.4.0 (2024-04-02)

Miscellaneous chores

• deps-dev: bump follow-redirects from 1.15.5 to 1.15.6 (#277) (ce0d324)
• Removed unused attributes on LlmChatCompletionSummary and LlmEmbedding (#278) (c1a9978)
• Updated test-utils dependency (#279) (5b037c6)

Continuous integration

• Updated CI workflows to run npm ci instead of npm install to catch package-lock.json being out of sync (#276) (87b1f07)

v7.3.0 (2024-03-12)

Features

• Added ability to disable capturing of content in LLM events ai_monitoring.record_content.enabled (#268) (a36050e)
• Added llm.tokenCountCallback support to Bedrock (#270) (d2af144)

Bug fixes

• Added override setting to middleware configuration (#273) (1a291f0)

Miscellaneous chores

• Changed token_count to only use tokenCountCallback (#272) (a9dbf26)
• Updated Bedrock entities with token_count (#269) (f6a86cb)

v7.2.0 (2024-02-29)

Features

• Added ability to disable instrumenting streaming via ai_monitoring.streaming.enabled = false (#257) (9b5abd6)

Code refactoring

• moved mock server to v3 so deps can be installed during versioned test run (#250) (33bf934)
• Removed storing message, request and completion id to be used to post LlmFeedbackEvents (#261) (0ab4890)
• Updated aws sdk instrumentation to construct specs at instrumentation (#259) (94de420)

Miscellaneous chores

• Apply LLM updates based on specification changes (#253) (a32f0bd)
• Refactor LLM user added metadata (#256) (c2a0314)
• Replace inlined bedrock server with test-utils version (#251) (94a2562)

v7.1.0 (2024-01-18)

Features

• Added Bedrock LLM streamed response handling (#245) (fb1911a)
• Added initial objects for LLM events (#236) (0543609)
• Added instrumentation for InvokeModelCommand (#239) (42d04ff)
• Added LLama2 support to LLM events and mock server (#238) (31dad9c)
• Added llm attribute to all transactions that contain llm spans for bedrock (#246) (3032545)
• Added ability to store feedback ids by request id (#240) (0bb4ffc)
• Added handling errors by adding additional attributes to the transaction errors. (#244) (e9584b4)
• Record metric on every InvokeModelCommand (#242) (0766bc6)

Code refactoring

• Added a serialize method to LlmEvent to remove the complex objects before enqueuing to the custom event aggregator (#241) (993673e)
• Removed aws_bedrock_instrumentation feature flag as feature is ready (#248) (e2dc0ad)

Miscellaneous chores

• Used latest of test deps for bedrock versioned tests (#235) (bc0fa24)

Tests

• Added missing test files to config (#233) (e4b504c)
• Added mock server for Bedrock API (#230) (c1e4c4c)
• Pinned peer deps of @aws-sdk/util-dynamodb and @aws-sdk/client-dynamodb so the older versions of @aws-sdk/lib-dynamodb pass (#231) (0a5773b)
• Resolved issue with testing in main repo (#234) (e5294ed)

Continuous integration

• Fixed misspelling in prepare-release.yml (#247) (783e474)
• Updated prepare-release to use conventional commit based releases. (#232) (5cbb649)

v7.0.3 (2023-12-07)

• Updated aws-sdk v3 instrumentation to only call shim.setLibrary and shim.setDatastore once instead of on every call to SQS, SNS, and DynamoDB.
• Updated axios from 0.21.4 to 1.6.0
• Updated ancestor dependency newrelic from 11.0.0 to 11.5.0

v7.0.2 (2023-10-25)

• Removed newrelic as peer dependency since this package only gets bundled with agent.
• Bumped @babel/traverse from 7.17.3 and 7.20.5 to 7.23.2

v7.0.1 (2023-09-19)

• Updated v3 smithy-client instrumentation to properly handle all types of clients for DynamoDB, SQS, and SNS.

v7.0.0 (2023-08-28)

• BREAKING: Removed support for Node 14.

• Added support for Node 20.

• Simplified instrumentation to only register relevant v3 middleware once in the send method of the SmithyClient.

• Updated vulnerable dependencies:

  • word-wrap from 1.2.3 to 1.2.4.
  • protobufjs from 7.2.3 to 7.2.4.

v6.0.0 (2023-06-30)

• BREAKING: Removed ability to run @newrelic/aws-sdk as a standalone module. This package gets bundled with agent and no longer can run as a standalone in v10 of the newrelic agent.

• Fixed instrumentation in AWS 3.363.0.

• Updated README links to point to new forum link due to repolinter ruleset change.

v5.0.5 (2023-05-01)

• Assigned shimName to v3 instrumentation hooks to avoid duplicate middleware crashes.

v5.0.4 (2023-04-04)

• Fixed issue where agent instrumentation caused unusable presigned urls to be generated by @aws-sdk/s3-request-presigner

v5.0.3 (2023-03-15)

• Updated name of header in NewRelicHeader middleware to avoid crashing in versions >= 3.290.0

• Updated README header image to latest OSS office required images.

• Added lockfile checks to CI workflow to prevent malicious changes.

v5.0.2 (2022-11-07)

• Fixed a crash when using versions >3.192.0 of AWS sdk v3 where a customer would see an error of error: TypeError: config.endpoint is not a function.

• Updated versioned tests to exclude 3.194.0-3.196.0 from tests because they contain breaking changes.

v5.0.1 (2022-10-10)

• Updated DynamoDB instrumentation to default port to 443 when not specified from the endpoint.

v5.0.0 (2022-07-28)

• BREAKING Removed support for Node 12.

The minimum supported version is now Node v14. For further information on our support policy, see: https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent.

• Added support for Node 18.x

• Updated the minimum version of the newrelic agent peer dependency to be >=8.7.0.

• Removed usage of async module.

• Bumped tap to ^16.0.1.

• Resolved several dev-dependency audit warnings.

v4.1.2 (2022-03-07)

• Removed versioned tests from npm artifact.

• Fixed link to discuss.newrelic.com in README

• Updated newrelic from 8.7.0 to 8.7.1.

• Resolved several dev-dependency audit warnings.

• Updated add-to-board to use org level NODE_AGENT_GH_TOKEN

v4.1.1 (2022-01-13)

• Fixed issue where v3 instrumentation checks against agent version would result in a logged error and fail to apply instrumentation.

v4.1.0 (2022-01-06)

• Added support for AWS SDK v3 🎉

  • Instrumented the following packages: @aws-sdk/client-sns, @aws-sdk/client-sqs, @aws-sdk/client-dynamodb, @aws-sdk/lib-dynamodb.

  • Captured generic AWS requests by instrumenting the @aws-sdk/smithy-client.

• Required agent version to be >=8.7.0 to register the instrumentation to support AWS SDK v3

• Added workflow to automate preparing release notes by reusing the newrelic/node-newrelic/.github/workflows/prep-release.yml@main workflow from agent repository.

• Added job to automatically add issues/pr to Node.js Engineering board

• Upgraded @newrelic/test-utilities to enable running 1 file through versioned runner

• Added a pre-commit hook to check if package.json changes and run oss third-party manifest and oss third-party notices. This will ensure the third_party_manifest.json and THIRD_PARTY_NOTICES.md are up to date.

• Added a pre-commit hook to run linting via husky

• Added @newrelic/eslint-config to rely on a centralized eslint ruleset.

• Upgraded setup-node CI job to v2 and changed the linting node version to lts/* for future proofing

4.0.1 (2021-07-20):

• Added versioned tests to the files list within package.json

4.0.0 (2021-07-20):

• BREAKING Removed support for Node 10.

  The minimum supported version is now Node v12. For further information on our support policy, see: https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent.

• Added support for Node 16.

• Added files list to package.json instead of using .npmignore for module publishing.
• Bumped @newrelic/test-utilities to ^5.1.0.
• Bumped tap to ^15.0.9.

3.1.0 (2021-01-05):

• Properly instrument dynamodb batchGet, batchWrite, transactGet, and transactWrite calls as database operations instead of External service calls.

3.0.0 (2020-11-02):

• Removed Node v8.x from CI.
• Added Node v14.x to CI.
• Update README for consistency with New Relic OSS repositories
• Remove Code of Conduct doc and link to New Relic org Code of Conduct in Contributing doc.

2.0.0 (2020-08-03):

• Updated to Apache 2.0 license.
• Bumped minimum peer dependency (and dev dependency) of newrelic (agent) to 6.11 for license matching.
• Added third party notices file and metadata for dependencies.
• Updated README with more detail.
• Added issue templates for bugs and enhancements.
• Added code of conduct file.
• Added contributing guide.
• Added pull request template.
• Migrated CI to GitHub Actions.
• Added copyright headers to all source files.
• Bumped @newrelic/test-utils to 4.0.0
• Added additional items to .npmignore.
• Removed AWS servers as dependency for versioned tests. Enables versioned test to run successfully for forked repo PRs.

1.1.3 (2020-06-12):

• Fixed issue where instrumentation would produce a TypeError: Cannot read property 'lastIndexOf' of undefined error if a program called sqs.receiveMessage without a QueueUrl parameter.

1.1.2 (2020-02-20):

• Fixed issue where instrumentation would crash pulling host and port values when AmazonDaxClient was used as the service for DocumentClient.

  AmazonDaxClient requests will report 'unknown' for host and port attributes. Other oddities may still exist until DAX officially supported.

1.1.1 (2020-01-27):

• Bumps DynamoDB tap.test timeout to avoid versioned test terminations when table creates are slow.

1.1.0 (2020-01-23):

• Adds official support for API promise calls. For example: await ddb.createTable(params).promise().

  • Fixed issue where external spans/segments would be incorrectly created in addition to more specific types such as datastore spans/segments. This also resulted in missing attributes from the more specific spans/segments.
  • Fixed issue where spans/segments would not have timing update appropriately upon promise resolution. These would show sub-millisecond execution time as the time captured was the execution of the initial function not accounting for async execution.

• Adds check before applying instrumentation to avoid breaking for very old versions of aws-sdk.

1.0.0 (2019-10-25):

• BREAKING Removed support for Node 6, 7, and 9.

  The minimum supported version is now Node v8. For further information on our support policy, see: https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent.

0.3.0 (2019-07-18):

• Adds support for DocumentClient API calls to be captured as Datastore segments/metrics.

  Supported calls are: get, put, update, delete, query and scan. These will be named according to the underlying DynamoDB operation that is executed. For example: get will be named getItem. DocumentClient calls not listed above will still be captured as Externals.

• Fixed issue that would prevent multiple DynamoDB instances from being instrumented.

• Replaced database_name with collection in DynamoDB attributes.

• Moved name property to the root of DynamoDB segment description object.

  Previously, segments were being incorrectly named "Datastore/operation/DynamoDB/undefined", due to the operation name being misplaced.

0.2.0 (2019-02-19):

• Added instrumentation for SNS publish API.

• Added instrumentation for SQS sendMessage, sendMessageBatch and receiveMessageBatch APIs.

0.1.0 (2019-02-13):

• Added instrumentation for services to be recorded as HTTP externals.

  • APIGateway
  • ELB
  • ElastiCache
  • Lambda
  • RDS
  • Redshift
  • Rekognition
  • S3
  • SES

• Added instrumentation for DynamoDB.