cloudwatch.Metric.put_data() docs inaccurate or incomplete?

[brettdh]

I was looking at how to use the Metric resource in the cloudwatch namespace, and I was surprised to see that its put_data method doesn't accept any arguments, according to the docs. I expect that this is a mistake, since the seemingly analogous put_metric_data client method does mention parameters in its docs. In fact, the two functions' docstrings are identical, except that put_metric_data has **kwargs in its signature, and the example request reflects the required parameters.

I'm about to test this out, so I guess I'll find out if I understand this right. :) Unfortunately, since boto3 is very meta-programmed, it's very difficult for me to figure out how to call this function simply by looking at the source code.

[joguSD]

Yep, the parameters definitely are missing from that documentation. I'll have to take a look and see what the cause is.

[boolafish]

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudwatch.html#CloudWatch.Metric.put_data

The parameters seems like to be still missing

[choughton85]

@brettdh, @boolafish, and @joguSD Here's a code snippet I used:

import boto3
import datetime

cloudwatch = boto3.resource('cloudwatch')
metric = cloudwatch.Metric('Namespace', 'MetricName')
metric.put_data(
    Namespace=metric.namespace,
    MetricData=[
        {
            'MetricName': metric.metric_name,
            'Timestamp': datetime.datetime.utcnow(),
            'Value': 1,
            'Unit': 'None',
            'Dimensions': [
                {'Name': 'Environment',
                 'Value': 'dev'
                 }
            ]
        }
    ]
)

I think it pulls most of the structure directly from the API docs: https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html

[swetashre]

@choughton85 - Yes you are right. It pulls most of the structure directly from API docs. Boto3 resource documentation is definitely lacking all these parameter. We should update our documentation.

I would mark this as documentation and see what can i do to update the documentation.

[pbaughman]

I was looking at the boto3 docs today and was surprised to find that put_data doesn't give any information about what the arguments are. This was surprising because I've always been pleased with the quality of the boto3 docs every other time I've used them.

[mdavis-xyz]

2.5 years and still no fix. I wish I could submit a PR to fix this, but as you say @brettdh , it's hard to understand how boto does things under the hood.

@choughton85 are you saying that you need to first instantiate the metric object by passing namespace and metric name, but then you need to pass those same values to the method call to put_data?

metric = cloudwatch.Metric('Namespace', 'MetricName')
metric.put_data(
    Namespace=metric.namespace,
    MetricData=[
        {
            'MetricName': metric.metric_name,

That seems redundant.

I just tried it without the Namespace argument, and it seems to work. (Didn't throw an exception. I need to wait before the data appears in the console.)

If I delete the MetricName key/value pair in the MetricData dict, it fails (throws an exception).

metric.metric_name seems redunantly verbose (what other kind of name could a metric have, other than a metric name?). Thankfully you can also do metric.name, which is the same value.

metric.put_data(
    MetricData=[
        {
            'MetricName': metric.name,
            'Timestamp': datetime.datetime.utcnow(),
            'Value': 3,
            'Unit': 'None',
            'Dimensions': [
                {
                 'Name': 'Environment',
                 'Value': 'dev'
                 }
            ]
        }
    ]
)

Hmm, I guess for this call there's no advantage in using the service resource over the client.

[milesgranger]

+1 Used a bit of time, trying to determine if I was just reading the docs wrong.

[ecnaidar]

Checking in 5 years since it was reported 😬 Had me scratching my head for some time on how Metric resource is supposed to be used until I've found this thread. +1'd initial issue but not holding out my hopes...

[aBurmeseDev]

The boto3 team has recently announced that the Resource interface has entered a feature freeze and won’t be accepting new changes at this time: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/resources.html. We’ll be closing existing feature requests, such as this issue, to avoid any confusion on current implementation status. We do appreciate your feedback and will ensure it’s considered in future feature decisions.

We’d like to highlight that all existing code using resources is supported and will continue to work in Boto3. No action is needed from users of the library.