Aws-sdk-js: Docs are incorrect for CloudWatch custom metrics

[miles-po]

https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CloudWatch.html#putMetricData-property

The Timestamp property to be passed to putMetricData(…) is listed as:

Timestamp — (Date)
The time the metric data was received, expressed as the number of milliseconds since Jan 1, 1970 00:00:00 UTC.

This implies that Date.now() could be used. This is not the case. Received error:

MalformedInput: timestamp must follow ISO8601

At no point in the docs linked above does it mandate or mention ISO8601 for that method.

[chrisradek]

@miles-po
Can you try passing in a Date object, instead of the number value from Date.now()? I'll also try to reproduce using Date.now(), but the SDK should convert a Date object to ISO8601 automatically in this case.

[miles-po]

I just changed my call to (new Date()).toISOString()

Passing in a Date object is missing the point. The docs specifically mention 'expressed as the number of milliseconds since Jan 1, 1970 00:00:00 UTC'. This describes Date.now(). Either the API needs to be fixed to follow the documentation or the docs need to reflect the actual usage.

[chrisradek]

@miles-po
I agree with you that either the docs or API have to change, I just wanted to make sure we could at least provide an immediate workaround.

It looks like what's happening is when a number value is passed as the date, the SDK assumes it is a unix timestamp and creates a new date object from that. Since the value from Date.now() has millisecond precision instead of second precision, the SDK converts it to a much larger value.

It will be difficult to change the SDK to accept timestamps with millisecond precision since existing code may be written based on how the SDK works today. That is however something we can fix in the next major version update. I'd much rather prefer being able to use the value from Date.now() without any modification

I'll update our documentation to call out that if a number value is provided, it needs to have second precision.

[miles-po]

Thank you. Much appreciated.

[dmarcoux]

I stumbled on this issue while trying to pass milliseconds since Epoch for the Timestamp property.

When will the docs be updated?

[SeanSnyders]

Also stumbled on this problem. Docs/API still seems to be incorrect.

[totomz]

Documentation is still broken after 6 months....

[jennliacl]

Ran into the same validation error, ended up using (new Date()).toISOString() as well.

[shadycuz]

same as others

[rabbitXIII]

Confirmed i'm still seeing the same issue. MetricDatum's type definition does not match the example

Timestamp: new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789

available for putMetricData Link to AWS Docs.

The documentation also remained

Timestamp — (Date)
The time the metric data was received, expressed as the number of milliseconds since Jan 1, 1970 00:00:00 UTC.

instead of being updated to "seconds" as referenced above by @chrisradek

[barneyparker]

Stumbled across this today - its been open for nearly 2 years and its simple documentation update - why the delay in getting this fixed?