:doc:`XRay <../../xray>` / Client / put_trace_segments

******************
put_trace_segments
******************



.. py:method:: XRay.Client.put_trace_segments(**kwargs)

  

  Uploads segment documents to Amazon Web Services X-Ray. A segment document can be a completed segment, an in-progress segment, or an array of subsegments.

   

  Segments must include the following fields. For the full segment document schema, see `Amazon Web Services X-Ray Segment Documents <https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments.html>`__ in the *Amazon Web Services X-Ray Developer Guide*.

   

  **Required segment document fields**

   

  
  * ``name`` - The name of the service that handled the request.
   
  * ``id`` - A 64-bit identifier for the segment, unique among segments in the same trace, in 16 hexadecimal digits.
   
  * ``trace_id`` - A unique identifier that connects all segments and subsegments originating from a single client request.
   
  * ``start_time`` - Time the segment or subsegment was created, in floating point seconds in epoch time, accurate to milliseconds. For example, ``1480615200.010`` or ``1.480615200010E9``.
   
  * ``end_time`` - Time the segment or subsegment was closed. For example, ``1480615200.090`` or ``1.480615200090E9``. Specify either an ``end_time`` or ``in_progress``.
   
  * ``in_progress`` - Set to ``true`` instead of specifying an ``end_time`` to record that a segment has been started, but is not complete. Send an in-progress segment when your application receives a request that will take a long time to serve, to trace that the request was received. When the response is sent, send the complete segment to overwrite the in-progress segment.
  

   

  A ``trace_id`` consists of three numbers separated by hyphens. For example, 1-58406520-a006649127e371903a2de979. For trace IDs created by an X-Ray SDK, or by Amazon Web Services services integrated with X-Ray, a trace ID includes:

   

  **Trace ID Format**

   

  
  * The version number, for instance, ``1``.
   
  * The time of the original request, in Unix epoch time, in 8 hexadecimal digits. For example, 10:00AM December 2nd, 2016 PST in epoch time is ``1480615200`` seconds, or ``58406520`` in hexadecimal.
   
  * A 96-bit identifier for the trace, globally unique, in 24 hexadecimal digits.
  

   

  .. note::

    

    Trace IDs created via OpenTelemetry have a different format based on the `W3C Trace Context specification <https://www.w3.org/TR/trace-context/>`__. A W3C trace ID must be formatted in the X-Ray trace ID format when sending to X-Ray. For example, a W3C trace ID ``4efaaf4d1e8720b39541901950019ee5`` should be formatted as ``1-4efaaf4d-1e8720b39541901950019ee5`` when sending to X-Ray. While X-Ray trace IDs include the original request timestamp in Unix epoch time, this is not required or validated.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/xray-2016-04-12/PutTraceSegments>`_  


  **Request Syntax**
  ::

    response = client.put_trace_segments(
        TraceSegmentDocuments=[
            'string',
        ]
    )
    
  :type TraceSegmentDocuments: list
  :param TraceSegmentDocuments: **[REQUIRED]** 

    A string containing a JSON document defining one or more segments or subsegments.

    

  
    - *(string) --* 

    

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

    
    ::

      {
          'UnprocessedTraceSegments': [
              {
                  'Id': 'string',
                  'ErrorCode': 'string',
                  'Message': 'string'
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **UnprocessedTraceSegments** *(list) --* 

        Segments that failed processing.

        
        

        - *(dict) --* 

          Information about a segment that failed processing.

          
          

          - **Id** *(string) --* 

            The segment's ID.

            
          

          - **ErrorCode** *(string) --* 

            The error that caused processing to fail.

            
          

          - **Message** *(string) --* 

            The error message.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`XRay.Client.exceptions.InvalidRequestException`

  
  *   :py:class:`XRay.Client.exceptions.ThrottledException`

  