AWS API Changes

2019/11/25 - Amazon CloudWatch - 6 new api methods

Changes This release adds a new feature called "Contributor Insights". "Contributor Insights" supports the following 6 new APIs (PutInsightRule, DeleteInsightRules, EnableInsightRules, DisableInsightRules, DescribeInsightRules and GetInsightRuleReport).

DescribeInsightRules (new)

Link ¶

Returns a list of all the Contributor Insights rules in your account. All rules in your account are returned with a single operation.

For more information about Contributor Insights, see Using Contributor Insights to Analyze High-Cardinality Data .

See also: AWS API Documentation

Request Syntax

client.describe_insight_rules(
    NextToken='string',
    MaxResults=123
)

type NextToken

string

param NextToken

Reserved for future use.

type MaxResults

integer

param MaxResults

This parameter is not currently used. Reserved for future use. If it is used in the future, the maximum value may be different.

rtype

dict

returns

Response Syntax

{
    'NextToken': 'string',
    'InsightRules': [
        {
            'Name': 'string',
            'State': 'string',
            'Schema': 'string',
            'Definition': 'string'
        },
    ]
}

Response Structure

(dict) --
- NextToken (string) --
  
  Reserved for future use.
- InsightRules (list) --
  
  The rules returned by the operation.
  - (dict) --
    
    This structure contains the definition for a Contributor Insights rule.
    - Name (string) --
      
      The name of the rule.
    - State (string) --
      
      Indicates whether the rule is enabled or disabled.
    - Schema (string) --
      
      For rules that you create, this is always {"Name": "CloudWatchLogRule", "Version": 1} . For built-in rules, this is {"Name": "ServiceLogRule", "Version": 1}
    - Definition (string) --
      
      The definition of the rule, as a JSON object. The definition contains the keywords used to define contributors, the value to aggregate on if this rule returns a sum instead of a count, and the filters. For details on the valid syntax, see Contributor Insights Rule Syntax .

DeleteInsightRules (new)

Link ¶

Permanently deletes the specified Contributor Insights rules.

If you create a rule, delete it, and then re-create it with the same name, historical data from the first time the rule was created may or may not be available.

See also: AWS API Documentation

Request Syntax

client.delete_insight_rules(
    RuleNames=[
        'string',
    ]
)

type RuleNames

list

param RuleNames

[REQUIRED]

An array of the rule names to delete. If you need to find out the names of your rules, use DescribeInsightRules .

(string) --

rtype

dict

returns

Response Syntax

{
    'Failures': [
        {
            'FailureResource': 'string',
            'ExceptionType': 'string',
            'FailureCode': 'string',
            'FailureDescription': 'string'
        },
    ]
}

Response Structure

(dict) --
- Failures (list) --
  
  An array listing the rules that could not be deleted. You cannot delete built-in rules.
  - (dict) --
    
    This array is empty if the API operation was successful for all the rules specified in the request. If the operation could not process one of the rules, the following data is returned for each of those rules.
    - FailureResource (string) --
      
      The specified rule that could not be deleted.
    - ExceptionType (string) --
      
      The type of error.
    - FailureCode (string) --
      
      The code of the error.
    - FailureDescription (string) --
      
      A description of the error.

PutInsightRule (new)

Link ¶

Creates a Contributor Insights rule. Rules evaluate log events in a CloudWatch Logs log group, enabling you to find contributor data for the log events in that log group. For more information, see Using Contributor Insights to Analyze High-Cardinality Data .

If you create a rule, delete it, and then re-create it with the same name, historical data from the first time the rule was created may or may not be available.

See also: AWS API Documentation

Request Syntax

client.put_insight_rule(
    RuleName='string',
    RuleState='string',
    RuleDefinition='string'
)

type RuleName

string

param RuleName

[REQUIRED]

A unique name for the rule.

type RuleState

string

param RuleState

The state of the rule. Valid values are ENABLED and DISABLED.

type RuleDefinition

string

param RuleDefinition

[REQUIRED]

The definition of the rule, as a JSON object. For details on the valid syntax, see Contributor Insights Rule Syntax .

rtype

dict

returns

Response Syntax

{}

Response Structure

(dict) --

DisableInsightRules (new)

Link ¶

Disables the specified Contributor Insights rules. When rules are disabled, they do not analyze log groups and do not incur costs.

See also: AWS API Documentation

Request Syntax

client.disable_insight_rules(
    RuleNames=[
        'string',
    ]
)

type RuleNames

list

param RuleNames

[REQUIRED]

An array of the rule names to disable. If you need to find out the names of your rules, use DescribeInsightRules .

(string) --

rtype

dict

returns

Response Syntax

{
    'Failures': [
        {
            'FailureResource': 'string',
            'ExceptionType': 'string',
            'FailureCode': 'string',
            'FailureDescription': 'string'
        },
    ]
}

Response Structure

(dict) --
- Failures (list) --
  
  An array listing the rules that could not be disabled. You cannot disable built-in rules.
  - (dict) --
    
    This array is empty if the API operation was successful for all the rules specified in the request. If the operation could not process one of the rules, the following data is returned for each of those rules.
    - FailureResource (string) --
      
      The specified rule that could not be deleted.
    - ExceptionType (string) --
      
      The type of error.
    - FailureCode (string) --
      
      The code of the error.
    - FailureDescription (string) --
      
      A description of the error.

GetInsightRuleReport (new)

Link ¶

This operation returns the time series data collected by a Contributor Insights rule. The data includes the identity and number of contributors to the log group.

You can also optionally return one or more statistics about each data point in the time series. These statistics can include the following:

UniqueContributors -- the number of unique contributors for each data point.
MaxContributorValue -- the value of the top contributor for each data point. The identity of the contributor may change for each data point in the graph. If this rule aggregates by COUNT, the top contributor for each data point is the contributor with the most occurrences in that period. If the rule aggregates by SUM, the top contributor is the contributor with the highest sum in the log field specified by the rule's Value , during that period.
SampleCount -- the number of data points matched by the rule.
Sum -- the sum of the values from all contributors during the time period represented by that data point.
Minimum -- the minimum value from a single observation during the time period represented by that data point.
Maximum -- the maximum value from a single observation during the time period represented by that data point.
Average -- the average value from all contributors during the time period represented by that data point.

See also: AWS API Documentation

Request Syntax

client.get_insight_rule_report(
    RuleName='string',
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    Period=123,
    MaxContributorCount=123,
    Metrics=[
        'string',
    ],
    OrderBy='string'
)

type RuleName

string

param RuleName

[REQUIRED]

The name of the rule that you want to see data from.

type StartTime

datetime

param StartTime

[REQUIRED]

The start time of the data to use in the report. When used in a raw HTTP Query API, it is formatted as yyyy-MM-dd'T'HH:mm:ss . For example, 2019-07-01T23:59:59 .

type EndTime

datetime

param EndTime

[REQUIRED]

The end time of the data to use in the report. When used in a raw HTTP Query API, it is formatted as yyyy-MM-dd'T'HH:mm:ss . For example, 2019-07-01T23:59:59 .

type Period

integer

param Period

[REQUIRED]

The period, in seconds, to use for the statistics in the InsightRuleMetricDatapoint results.

type MaxContributorCount

integer

param MaxContributorCount

The maximum number of contributors to include in the report. The range is 1 to 100. If you omit this, the default of 10 is used.

type Metrics

list

param Metrics

Specifies which metrics to use for aggregation of contributor values for the report. You can specify one or more of the following metrics:

UniqueContributors -- the number of unique contributors for each data point.
MaxContributorValue -- the value of the top contributor for each data point. The identity of the contributor may change for each data point in the graph. If this rule aggregates by COUNT, the top contributor for each data point is the contributor with the most occurrences in that period. If the rule aggregates by SUM, the top contributor is the contributor with the highest sum in the log field specified by the rule's Value , during that period.
SampleCount -- the number of data points matched by the rule.
Sum -- the sum of the values from all contributors during the time period represented by that data point.
Minimum -- the minimum value from a single observation during the time period represented by that data point.
Maximum -- the maximum value from a single observation during the time period represented by that data point.
Average -- the average value from all contributors during the time period represented by that data point.

(string) --

type OrderBy

string

param OrderBy

Determines what statistic to use to rank the contributors. Valid values are SUM and MAXIMUM.

rtype

dict

returns

Response Syntax

{
    'KeyLabels': [
        'string',
    ],
    'AggregationStatistic': 'string',
    'AggregateValue': 123.0,
    'ApproximateUniqueCount': 123,
    'Contributors': [
        {
            'Keys': [
                'string',
            ],
            'ApproximateAggregateValue': 123.0,
            'Datapoints': [
                {
                    'Timestamp': datetime(2015, 1, 1),
                    'ApproximateValue': 123.0
                },
            ]
        },
    ],
    'MetricDatapoints': [
        {
            'Timestamp': datetime(2015, 1, 1),
            'UniqueContributors': 123.0,
            'MaxContributorValue': 123.0,
            'SampleCount': 123.0,
            'Average': 123.0,
            'Sum': 123.0,
            'Minimum': 123.0,
            'Maximum': 123.0
        },
    ]
}

Response Structure

(dict) --
- KeyLabels (list) --
  
  An array of the strings used as the keys for this rule. The keys are the dimensions used to classify contributors. If the rule contains more than one key, then each unique combination of values for the keys is counted as a unique contributor.
  - (string) --
- AggregationStatistic (string) --
  
  Specifies whether this rule aggregates contributor data by COUNT or SUM.
- AggregateValue (float) --
  
  The sum of the values from all individual contributors that match the rule.
- ApproximateUniqueCount (integer) --
  
  An approximate count of the unique contributors found by this rule in this time period.
- Contributors (list) --
  
  An array of the unique contributors found by this rule in this time period. If the rule contains multiple keys, each combination of values for the keys counts as a unique contributor.
  - (dict) --
    
    One of the unique contributors found by a Contributor Insights rule. If the rule contains multiple keys, then a unique contributor is a unique combination of values from all the keys in the rule.
    
    If the rule contains a single key, then each unique contributor is each unique value for this key.
    
    For more information, see GetInsightRuleReport .
    - Keys (list) --
      
      One of the log entry field keywords that is used to define contributors for this rule.
      - (string) --
    - ApproximateAggregateValue (float) --
      
      An approximation of the aggregate value that comes from this contributor.
    - Datapoints (list) --
      
      An array of the data points where this contributor is present. Only the data points when this contributor appeared are included in the array.
      - (dict) --
        
        One data point related to one contributor.
        
        For more information, see GetInsightRuleReport and InsightRuleContributor .
        
        Timestamp (datetime) --
        
        The timestamp of the data point.
        
        ApproximateValue (float) --
        
        The approximate value that this contributor added during this timestamp.
- MetricDatapoints (list) --
  
  A time series of metric data points that matches the time period in the rule request.
  - (dict) --
    
    One data point from the metric time series returned in a Contributor Insights rule report.
    
    For more information, see GetInsightRuleReport .
    - Timestamp (datetime) --
      
      The timestamp of the data point.
    - UniqueContributors (float) --
      
      The number of unique contributors who published data during this timestamp.
      
      This statistic is returned only if you included it in the Metrics array in your request.
    - MaxContributorValue (float) --
      
      The maximum value provided by one contributor during this timestamp. Each timestamp is evaluated separately, so the identity of the max contributor could be different for each timestamp.
      
      This statistic is returned only if you included it in the Metrics array in your request.
    - SampleCount (float) --
      
      The number of occurrences that matched the rule during this data point.
      
      This statistic is returned only if you included it in the Metrics array in your request.
    - Average (float) --
      
      The average value from all contributors during the time period represented by that data point.
      
      This statistic is returned only if you included it in the Metrics array in your request.
    - Sum (float) --
      
      The sum of the values from all contributors during the time period represented by that data point.
      
      This statistic is returned only if you included it in the Metrics array in your request.
    - Minimum (float) --
      
      The minimum value from a single contributor during the time period represented by that data point.
      
      This statistic is returned only if you included it in the Metrics array in your request.
    - Maximum (float) --
      
      The maximum value from a single occurence from a single contributor during the time period represented by that data point.
      
      This statistic is returned only if you included it in the Metrics array in your request.

EnableInsightRules (new)

Link ¶

Enables the specified Contributor Insights rules. When rules are enabled, they immediately begin analyzing log data.

See also: AWS API Documentation

Request Syntax

client.enable_insight_rules(
    RuleNames=[
        'string',
    ]
)

type RuleNames

list

param RuleNames

[REQUIRED]

An array of the rule names to enable. If you need to find out the names of your rules, use DescribeInsightRules .

(string) --

rtype

dict

returns

Response Syntax

{
    'Failures': [
        {
            'FailureResource': 'string',
            'ExceptionType': 'string',
            'FailureCode': 'string',
            'FailureDescription': 'string'
        },
    ]
}

Response Structure

(dict) --
- Failures (list) --
  
  An array listing the rules that could not be enabled. You cannot disable or enable built-in rules.
  - (dict) --
    
    This array is empty if the API operation was successful for all the rules specified in the request. If the operation could not process one of the rules, the following data is returned for each of those rules.
    - FailureResource (string) --
      
      The specified rule that could not be deleted.
    - ExceptionType (string) --
      
      The type of error.
    - FailureCode (string) --
      
      The code of the error.
    - FailureDescription (string) --
      
      A description of the error.