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.