Document How To Use newrelic API With This Plugin

[wrumsby]

Being new to layers I'm not 100% sure how they work.

Specifically, is this solution only usable if I do not want to use API features like newrelic.addCustomAttribute in my code?

Ideally I'd like to understand the best way to use this plugin and use the New Relic API with TypeScript in my Lambda code.

[mrickard]

The advantage of using layers is that you can make use of New Relic monitoring without changing your code. If you're going to make use of the newrelic.* API methods in your code, you don't need to use the layer, since you'll be referencing that in your package.json dependencies and importing it with require('newrelic').

Are you deploying/invoking with Serverless?

[wrumsby]

@mrickard yes, we're using Serverless.

[mrickard]

@wrumsby Great--this plugin is the right one to use if you want to use the New Relic lambda layer with serverless, assuming that you don't want to change your function code.

If, however, you want to use newrelic.* methods explicitly in your function code...then I'd suggest not bothering with the layers. Then you'd include newrelic and @newrelic/aws-sdk in your package json and require them in your function file, along with wrapping your handler function in newrelic.setLambdaHandler, and instrumenting throughout.

[kolanos]

@wrumsby You can still use the newrelic.* methods in your function with the layer. The layer just provides the newrelic agent for your runtime and automatically wraps your function without requiring you to have to make any code changes or add any additional dependencies. Does that answer your question?

We can definitely better document how layers work. If you're still unclear on layers, this blog post may be helpful: https://read.iopipe.com/cutting-through-the-layers-aws-lamba-layers-explained-28e8a8d7bda8

[doctau]

If you want to use the serverless plugin with it's automatic wrapping of every entry point, but also use the agent API to add custom attributes, you can do it. You need to add a dependency on the node agent but then exclude it from packaging via

package:
  patterns:
    - '!node_modules/newrelic/**'

[JordanPawlett]

If you want to use the serverless plugin with it's automatic wrapping of every entry point, but also use the agent API to add custom attributes, you can do it. You need to add a dependency on the node agent but then exclude it from packaging via

package:
  patterns:
    - '!node_modules/newrelic/**'

Thanks for this information!

Are you able to add custom attributes to the automatic span generated via the plugin, or do you have to create a new nested span to attach the attributes too?

Have you got any code examples you can share?

[JordanPawlett]

@doctau Can you see anything wrong with this use-case? Automatic spans are still appearing in new-relic, but they're lacking any custom attributes or custom spans.

serverless.yml

package:
  patterns:
    - '!node_modules/newrelic/**'

handler.ts

import newrelic from 'newrelic';
require('@newrelic/aws-sdk');

export const handler = (...) => {
        newrelic.addCustomAttributes({ foo: 'bar' });

        await newrelic.startSegment('customSpan', true, () => {
            newrelic.addCustomSpanAttributes({
                ...
            });
            return myAsyncFunc();
        });
}

package.json

"newrelic": "^8.8.0",
"@newrelic/aws-sdk": "^4.1.1",
"serverless-newrelic-lambda-layers": "^2.2.0",
"@types/newrelic": "^7.0.3",

[mrickard]

@JordanPawlett A couple things as I look at this:

1. Make sure the block you've excerpted from your package.json refers to devDependencies, rather than dependencies. (While I see that you're excluding them with the package...it's just easier to keep them in devDependencies and let the Serveless framework exclude them from the package.)
2. The Node agent's been updated to contain the aws-sdk, so there's no need to require @newrelic/aws-sdk for recent agents, like 8.8.0. (So you'll require just newrelic and not the SDK.)