:doc:`CloudWatchLogs <../../logs>` / Client / put_destination

***************
put_destination
***************



.. py:method:: CloudWatchLogs.Client.put_destination(**kwargs)

  

  Creates or updates a destination. This operation is used only to create destinations for cross-account subscriptions.

   

  A destination encapsulates a physical resource (such as an Amazon Kinesis stream). With a destination, you can subscribe to a real-time stream of log events for a different account, ingested using `PutLogEvents <https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html>`__.

   

  Through an access policy, a destination controls what is written to it. By default, ``PutDestination`` does not set any access policy with the destination, which means a cross-account user cannot call `PutSubscriptionFilter <https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutSubscriptionFilter.html>`__ against this destination. To enable this, the destination owner must call `PutDestinationPolicy <https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDestinationPolicy.html>`__ after ``PutDestination``.

   

  To perform a ``PutDestination`` operation, you must also have the ``iam:PassRole`` permission.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/logs-2014-03-28/PutDestination>`_  


  **Request Syntax**
  ::

    response = client.put_destination(
        destinationName='string',
        targetArn='string',
        roleArn='string',
        tags={
            'string': 'string'
        }
    )
    
  :type destinationName: string
  :param destinationName: **[REQUIRED]** 

    A name for the destination.

    

  
  :type targetArn: string
  :param targetArn: **[REQUIRED]** 

    The ARN of an Amazon Kinesis stream to which to deliver matching log events.

    

  
  :type roleArn: string
  :param roleArn: **[REQUIRED]** 

    The ARN of an IAM role that grants CloudWatch Logs permissions to call the Amazon Kinesis ``PutRecord`` operation on the destination stream.

    

  
  :type tags: dict
  :param tags: 

    An optional list of key-value pairs to associate with the resource.

     

    For more information about tagging, see `Tagging Amazon Web Services resources <https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html>`__

    

  
    - *(string) --* 

    
      - *(string) --* 

      


  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'destination': {
              'destinationName': 'string',
              'targetArn': 'string',
              'roleArn': 'string',
              'accessPolicy': 'string',
              'arn': 'string',
              'creationTime': 123
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **destination** *(dict) --* 

        The destination.

        
        

        - **destinationName** *(string) --* 

          The name of the destination.

          
        

        - **targetArn** *(string) --* 

          The Amazon Resource Name (ARN) of the physical target where the log events are delivered (for example, a Kinesis stream).

          
        

        - **roleArn** *(string) --* 

          A role for impersonation, used when delivering log events to the target.

          
        

        - **accessPolicy** *(string) --* 

          An IAM policy document that governs which Amazon Web Services accounts can create subscription filters against this destination.

          
        

        - **arn** *(string) --* 

          The ARN of this destination.

          
        

        - **creationTime** *(integer) --* 

          The creation time of the destination, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.

          
    
  
  **Exceptions**
  
  *   :py:class:`CloudWatchLogs.Client.exceptions.InvalidParameterException`

  
  *   :py:class:`CloudWatchLogs.Client.exceptions.OperationAbortedException`

  
  *   :py:class:`CloudWatchLogs.Client.exceptions.ServiceUnavailableException`

  