put_insight_selectors ¶

def put_insight_selectors(
    self,
    insight_selectors: "capo_cloudtrail.types.insight_selectors.InsightSelectors",
    *,
    config_overrides: Optional[CloudTrailClientConfig] = None,
    trail_name: Optional["capo_cloudtrail.types.string.String"] = None,
    event_data_store: Optional[
        "capo_cloudtrail.types.event_data_store_arn.EventDataStoreArn"
    ] = None,
    insights_destination: Optional[
        "capo_cloudtrail.types.event_data_store_arn.EventDataStoreArn"
    ] = None,
) -> "capo_cloudtrail.types.put_insight_selectors_response.PutInsightSelectorsResponse":
    """<p>Lets you enable Insights event logging on specific event categories by specifying the Insights selectors that you want to enable on an existing trail or event data store. You also use <code>PutInsightSelectors</code> to turn off Insights event logging, by passing an empty list of Insights types. The valid Insights event types are <code>ApiErrorRateInsight</code> and <code>ApiCallRateInsight</code>, and valid EventCategories are <code>Management</code> and <code>Data</code>.</p> <note> <p> Insights on data events are not supported on event data stores. For event data stores, you can only enable Insights on management events. </p> </note> <p>To enable Insights on an event data store, you must specify the ARNs (or ID suffix of the ARNs) for the source event data store (<code>EventDataStore</code>) and the destination event data store (<code>InsightsDestination</code>). The source event data store logs management events and enables Insights. The destination event data store logs Insights events based upon the management event activity of the source event data store. The source and destination event data stores must belong to the same Amazon Web Services account.</p> <p>To log Insights events for a trail, you must specify the name (<code>TrailName</code>) of the CloudTrail trail for which you want to change or add Insights selectors.</p> <ul> <li> <p> For Management events Insights: To log CloudTrail Insights on the API call rate, the trail or event data store must log <code>write</code> management events. To log CloudTrail Insights on the API error rate, the trail or event data store must log <code>read</code> or <code>write</code> management events. </p> </li> <li> <p> For Data events Insights: To log CloudTrail Insights on the API call rate or API error rate, the trail must log <code>read</code> or <code>write</code> data events. Data events Insights are not supported on event data store. </p> </li> </ul> <p>To log CloudTrail Insights events on API call volume, the trail or event data store must log <code>write</code> management events. To log CloudTrail Insights events on API error rate, the trail or event data store must log <code>read</code> or <code>write</code> management events. You can call <code>GetEventSelectors</code> on a trail to check whether the trail logs management events. You can call <code>GetEventDataStore</code> on an event data store to check whether the event data store logs management events.</p> <p>For more information, see <a href="https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-insights-events-with-cloudtrail.html">Working with CloudTrail Insights</a> in the <i>CloudTrail User Guide</i>.</p>

    Args:
        trail_name: <p>The name of the CloudTrail trail for which you want to change or add Insights selectors.</p> <p>You cannot use this parameter with the <code>EventDataStore</code> and <code>InsightsDestination</code> parameters.</p>
        insight_selectors: <p>Contains the Insights types you want to log on a specific category of events on a trail or event data store. <code>ApiCallRateInsight</code> and <code>ApiErrorRateInsight</code> are valid Insight types.The EventCategory field can specify <code>Management</code> or <code>Data</code> events or both. For event data store, you can log Insights for management events only.</p> <p>The <code>ApiCallRateInsight</code> Insights type analyzes write-only management API calls or read and write data API calls that are aggregated per minute against a baseline API call volume.</p> <p>The <code>ApiErrorRateInsight</code> Insights type analyzes management and data API calls that result in error codes. The error is shown if the API call is unsuccessful.</p>
        event_data_store: <p>The ARN (or ID suffix of the ARN) of the source event data store for which you want to change or add Insights selectors. To enable Insights on an event data store, you must provide both the <code>EventDataStore</code> and <code>InsightsDestination</code> parameters.</p> <p>You cannot use this parameter with the <code>TrailName</code> parameter.</p>
        insights_destination: <p> The ARN (or ID suffix of the ARN) of the destination event data store that logs Insights events. To enable Insights on an event data store, you must provide both the <code>EventDataStore</code> and <code>InsightsDestination</code> parameters. </p> <p>You cannot use this parameter with the <code>TrailName</code> parameter.</p>

    Raises:
        capo_cloudtrail.errors.cloud_trail_arn_invalid_exception.CloudTrailARNInvalidException: <p>This exception is thrown when an operation is called with an ARN that is not valid.</p> <p>The following is the format of a trail ARN: <code>arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail</code> </p> <p>The following is the format of an event data store ARN: <code>arn:aws:cloudtrail:us-east-2:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE</code> </p> <p>The following is the format of a dashboard ARN: <code>arn:aws:cloudtrail:us-east-1:123456789012:dashboard/exampleDash</code> </p> <p>The following is the format of a channel ARN: <code>arn:aws:cloudtrail:us-east-2:123456789012:channel/01234567890</code> </p>
        capo_cloudtrail.errors.conflict_exception.ConflictException: <p>This exception is thrown when the specified resource is not ready for an operation. This can occur when you try to run an operation on a resource before CloudTrail has time to fully load the resource, or because another operation is modifying the resource. If this exception occurs, wait a few minutes, and then try the operation again.</p>
        capo_cloudtrail.errors.insufficient_encryption_policy_exception.InsufficientEncryptionPolicyException: <p>For the <code>CreateTrail</code> <code>PutInsightSelectors</code>, <code>UpdateTrail</code>, <code>StartQuery</code>, and <code>StartImport</code> operations, this exception is thrown when the policy on the S3 bucket or KMS key does not have sufficient permissions for the operation.</p> <p>For all other operations, this exception is thrown when the policy for the KMS key does not have sufficient permissions for the operation.</p>
        capo_cloudtrail.errors.insufficient_s3_bucket_policy_exception.InsufficientS3BucketPolicyException: <p>This exception is thrown when the policy on the S3 bucket is not sufficient.</p>
        capo_cloudtrail.errors.invalid_home_region_exception.InvalidHomeRegionException: <p>This exception is thrown when an operation is called on a trail from a Region other than the Region in which the trail was created.</p>
        capo_cloudtrail.errors.invalid_insight_selectors_exception.InvalidInsightSelectorsException: <p>For <code>PutInsightSelectors</code>, this exception is thrown when the formatting or syntax of the <code>InsightSelectors</code> JSON statement is not valid, or the specified <code>InsightType</code> in the <code>InsightSelectors</code> statement is not valid. Valid values for <code>InsightType</code> are <code>ApiCallRateInsight</code> and <code>ApiErrorRateInsight</code>. To enable Insights on an event data store, the destination event data store specified by the <code>InsightsDestination</code> parameter must log Insights events and the source event data store specified by the <code>EventDataStore</code> parameter must log management events.</p> <p>For <code>UpdateEventDataStore</code>, this exception is thrown if Insights are enabled on the event data store and the updated advanced event selectors are not compatible with the configured <code>InsightSelectors</code>. If the <code>InsightSelectors</code> includes an <code>InsightType</code> of <code>ApiCallRateInsight</code>, the source event data store must log <code>write</code> management events. If the <code>InsightSelectors</code> includes an <code>InsightType</code> of <code>ApiErrorRateInsight</code>, the source event data store must log management events.</p>
        capo_cloudtrail.errors.invalid_parameter_combination_exception.InvalidParameterCombinationException: <p>This exception is thrown when the combination of parameters provided is not valid.</p>
        capo_cloudtrail.errors.invalid_parameter_exception.InvalidParameterException: <p>The request includes a parameter that is not valid.</p>
        capo_cloudtrail.errors.invalid_trail_name_exception.InvalidTrailNameException: <p>This exception is thrown when the provided trail name is not valid. Trail names must meet the following requirements:</p> <ul> <li> <p>Contain only ASCII letters (a-z, A-Z), numbers (0-9), periods (.), underscores (_), or dashes (-)</p> </li> <li> <p>Start with a letter or number, and end with a letter or number</p> </li> <li> <p>Be between 3 and 128 characters</p> </li> <li> <p>Have no adjacent periods, underscores or dashes. Names like <code>my-_namespace</code> and <code>my--namespace</code> are not valid.</p> </li> <li> <p>Not be in IP address format (for example, 192.168.5.4)</p> </li> </ul>
        capo_cloudtrail.errors.kms_exception.KmsException: <p>This exception is thrown when there is an issue with the specified KMS key and the trail or event data store can't be updated.</p>
        capo_cloudtrail.errors.no_management_account_slr_exists_exception.NoManagementAccountSLRExistsException: <p> This exception is thrown when the management account does not have a service-linked role. </p>
        capo_cloudtrail.errors.not_organization_master_account_exception.NotOrganizationMasterAccountException: <p>This exception is thrown when the Amazon Web Services account making the request to create or update an organization trail or event data store is not the management account for an organization in Organizations. For more information, see <a href="https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-an-organizational-trail-prepare.html">Prepare For Creating a Trail For Your Organization</a> or <a href="https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-organizations.html">Organization event data stores</a>.</p>
        capo_cloudtrail.errors.operation_not_permitted_exception.OperationNotPermittedException: <p>This exception is thrown when the requested operation is not permitted.</p>
        capo_cloudtrail.errors.s3_bucket_does_not_exist_exception.S3BucketDoesNotExistException: <p>This exception is thrown when the specified S3 bucket does not exist.</p>
        capo_cloudtrail.errors.throttling_exception.ThrottlingException: <p> This exception is thrown when the request rate exceeds the limit. </p>
        capo_cloudtrail.errors.trail_not_found_exception.TrailNotFoundException: <p>This exception is thrown when the trail with the given name is not found.</p>
        capo_cloudtrail.errors.unsupported_operation_exception.UnsupportedOperationException: <p>This exception is thrown when the requested operation is not supported.</p>
        capo_cloudtrail.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    def _handler(
        req: "OperationRequest[capo_cloudtrail.types.put_insight_selectors_request.PutInsightSelectorsRequest]",
    ) -> OperationResponse[
        "capo_cloudtrail.types.put_insight_selectors_response.PutInsightSelectorsResponse"
    ]:
        import capo_cloudtrail._operations.cloud_trail_20131101.put_insight_selectors

        output, http_response = (
            capo_cloudtrail._operations.cloud_trail_20131101.put_insight_selectors.put_insight_selectors(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("PutInsightSelectors")
    )
    input_: capo_cloudtrail.types.put_insight_selectors_request.PutInsightSelectorsRequest = {
        "insight_selectors": insight_selectors
    }
    if trail_name is not None:
        input_["trail_name"] = trail_name
    if event_data_store is not None:
        input_["event_data_store"] = event_data_store
    if insights_destination is not None:
        input_["insights_destination"] = insights_destination

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output