Add option to disable agent communication during unit tests

[davidtheclark]

I'd like to block the SDK from trying to communicate with a CloudWatch Agent during certain unit tests. I don't see a documented way to do this right now.

Ideally, I'd also be able to run assertions against the information that the SDK would have logged. (Did the dimensions, properties, and metrics logged during this test match my expectations?) So one possible approach to this problem could be to "report" logs to some in-memory object that can be inspected, instead of the CloudWatch Agent. At a minimum, though, I'd like to be able turn off Agent communication, instead of having to mock the module's API whenever I want to run my code without an Agent.

[jaredcnance]

You can do this a couple ways. Generally, I would recommend mocking out the logging modules. You can see how we do this in our tests:

https://github.com/awslabs/aws-embedded-metrics-node/blob/master/src/logger/__tests__/MetricScope.test.ts

Alternatively, you can set the lambda function name environment variable to force the logger to use the stdout sink:

aws-embedded-metrics-node/src/environment/__tests__/LambdaEnvironment.test.ts

Line 7 in 843c7c4

process.env.AWS_LAMBDA_FUNCTION_NAME = faker.random.word();

This is a great question though and I will work on putting together some better documentation that provides various techniques for testing code that uses our logger.

Additionally, I think there is value in providing an easier sink configuration mechanism. Today, most are using the auto-environment detection, but if we allow you to configure your environment, we can skip the auto-detection and allow you to configure a no-op or in-memory sink.

[davidtheclark]

Thanks, @jaredcnance. Yeah, I'm also mocking the module for unit tests — which has added benefit that you can make assertions about what you log. So maybe the more important challenge is about running an application locally for debugging. As you suggest, an easier sink configuration mechanism sounds fantastic (especially for piping logs to stdout).

Right now I'm using Docker Compose to run my application alongside a very simple TCP server that logs whatever messages it gets, and I'm pointing the EMF SDK at that server with AWS_EMF_AGENT_ENDPOINT. This is working pretty nicely, but does involve some setup (like writing a little TCP server).

[jaredcnance]

If the goal is just to support running it locally without an agent, one way we could do this is allow you to specify the environment directly. Example:

export AWS_EMF_ENVIRONMENT="Local"

We would support the following environment values:

• Local: no decoration and sends over stdout
• Lambda: decorates logs with Lambda metadata and sends over stdout
• Agent: no decoration and sends over TCP
• EC2: decorates logs with EC2 metadata and sends over TCP

This override would bypass environment detection.

[davidtheclark]

That sounds like a good idea 👍

In addition to manual configuration, would the environment detection be able to determine that I'm not on a Lambda or EC2, and default to Local?

Also worth noting that to accomplish the Docker Compose setup I mentioned above, I needed to use the undocumented AWS_EMF_AGENT_ENDPOINT environment variable. Unless there's any reason not to, it seems useful to surface that option in the documentation.

[jaredcnance]

be able to determine that I'm not on a Lambda or EC2

There are other agent scenarios where we don't currently have a good way of detecting the environment (K8s and EKS for example). This is why we default to using an agent.

I 100% agree on updating the documentation. I will likely convert the configuration section to a table of all available parameters. I'll plan on working on both of these later this week.