Docs: clarify addMetadata() call order in single metrics docs

[bml1g12]

Expected Behavior

const metrics = new Metrics({
  namespace: 'cci',
})

const lambdaHandler = async (
  _event: unknown,
  _context: unknown
): Promise<void> => {
    const taskTotal = metrics.singleMetric()
    taskTotal.addMetadata("caseId", caseId)
    taskTotal.addMetric("deleteme-taskTotal", MetricUnit.Count, 1)
}

Works as expected however, doing instead the other way around:

    taskTotal.addMetric("deleteme-taskTotal", MetricUnit.Count, 1)
    taskTotal.addMetadata("caseId", caseId)

Seems to result in no metadata being appended to the EMF cloudwatch log.

This is confusing because the documentation example shows addMetadata() being called after addMetadata https://docs.powertools.aws.dev/lambda/typescript/latest/core/metrics/#adding-metadata

Current Behavior

    taskTotal.addMetric("deleteme-taskTotal", MetricUnit.Count, 1)
    taskTotal.addMetadata("caseId", caseId)

Does not add metadata to the cloudwatch log

Code snippet

    taskTotal.addMetric("deleteme-taskTotal", MetricUnit.Count, 1)
    taskTotal.addMetadata("caseId", caseId)

Steps to Reproduce

    "@aws-lambda-powertools/logger": "^2.8.0",
    "@aws-lambda-powertools/metrics": "^2.8.0",

Possible Solution

I'd suggest either updating docs to specify explicitly the order required, or making it work in either order

Powertools for AWS Lambda (TypeScript) version

2.8.0

AWS Lambda function runtime

20.x

Packaging format used

npm

Execution logs

No response

[dreamorosi]

Hi @bml1g12, thanks for opening the issue.

As far as I can tell (haven't tested yet), this happens only for single metrics, but not for regular metrics.

The reason why, is that single metrics are published as soon as you add them, so by the time you add the metadata, that metric has already been emitted.

You can see the implementation for addMetric() here. As I mentioned, we immediately flush the metric out of the buffer by calling publishStoredMetrics() (implementation here), which in turn calls the internal method serializeMetrics() which is where we append the metadata (here).

With this in mind, if you want to append metadata and use single metric, you'll have to do it before adding the metric.

The example you linked is for regular metrics and not single metrics

[dreamorosi]

Ok, I have just tested what I shared above and I can confirm that this is the case.

import { expect, it, describe, vi } from 'vitest';
import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

vi.hoisted(() => {
  process.env.POWERTOOLS_DEV = 'true';
});

describe('metrics', () => {
  it('has metadata when using regular metrics', () => {
    // Prepare
    const metrics = new Metrics();
    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});

    // Act
    metrics.addMetric('myMetric', MetricUnit.Count, 1);
    metrics.addMetadata('foo', 'bar');

    metrics.publishStoredMetrics();

    // Assess
    expect(JSON.parse(logSpy.mock.calls[0][0])).toStrictEqual(
      expect.objectContaining({
        _aws: {
          CloudWatchMetrics: [
            {
              Namespace: 'default_namespace',
              Dimensions: [['service']],
              Metrics: [{ Name: 'myMetric', Unit: 'Count' }],
            },
          ],
          Timestamp: expect.any(Number),
        },
        foo: 'bar',
        myMetric: 1,
        service: 'service_undefined',
      })
    );
  });

  it('does not have metadata when using single metrics', () => {
    // Prepare
    const metrics = new Metrics({ singleMetric: true });
    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});

    // Act
    metrics.addMetric('myMetric', MetricUnit.Count, 1);
    metrics.addMetadata('foo', 'bar');

    // Assess
    expect(JSON.parse(logSpy.mock.calls[0][0])).toStrictEqual({
      _aws: {
        CloudWatchMetrics: [
          {
            Namespace: 'default_namespace',
            Dimensions: [['service']],
            Metrics: [{ Name: 'myMetric', Unit: 'Count' }],
          },
        ],
        Timestamp: expect.any(Number),
      },
      myMetric: 1,
      service: 'service_undefined',
    });
  });
});

With this in mind, I don't think there's a way for us to make it work with single metrics since, as explained, by the time you call addMetadata() the metric has already been emitted.

I am going however to improve the code sample for the single metric section to include an addMetadata() call shown before the addMetric() one.

[bml1g12]

That makes perfect sense, thanks for clarifying in the docs

I wasn't aware single metrics emit immediately (I thought they also would flush at end of runtime), that might be nice to clarify in docs too (apologies if it's there and I missed it)

[dreamorosi]

I have opened a PR to fix the issue and also spell out the fact that these metrics are emitted as soon as they are added, which was not explicitly stated in the previous version of that section (it was elsewhere).

[github-actions]

⚠️ COMMENT VISIBILITY WARNING ⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions]

This is now released under v2.10.0 version!