Boto3: 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.