Amazon X-Ray Xray Operations API

openapi: 3.2.0
info:
  title: AWS X-Ray Operations API
  version: '2016-04-12'
  description: Generated from AWS's published Smithy model for AWS X-Ray. 8 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://xray.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Operations
paths:
  /CancelTraceRetrieval:
    post:
      operationId: CancelTraceRetrieval
      summary: Cancel Trace Retrieval
      description: Cancels an ongoing trace retrieval job initiated by StartTraceRetrieval using the provided RetrievalToken. A successful cancellation will return an HTTP 200 response.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelTraceRetrievalResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelTraceRetrievalRequest'
      tags:
      - Operations
  /GetIndexingRules:
    post:
      operationId: GetIndexingRules
      summary: Get Indexing Rules
      description: Retrieves all indexing rules. Indexing rules are used to determine the server-side sampling rate for spans ingested through the CloudWatchLogs destination and indexed by X-Ray. For more information, see Transaction Search.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIndexingRulesResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetIndexingRulesRequest'
      tags:
      - Operations
  /GetRetrievedTracesGraph:
    post:
      operationId: GetRetrievedTracesGraph
      summary: Get Retrieved Traces Graph
      description: Retrieves a service graph for traces based on the specified RetrievalToken from the CloudWatch log group generated by Transaction Search. This API does not initiate a retrieval job. You must first execute StartTraceRetrieval to obtain the required RetrievalToken. The trace graph describes services that process incoming requests and any downstream services they call, which may include Amazon Web Services resources, external APIs, or databases. The response is empty until the RetrievalStatus is COMPLETE. Retry the request after the status changes from RUNNING or SCHEDULED to COMPLETE to access the full service graph. When CloudWatch log is the destination, this API can support cross-account observability and service graph retrieval across linked accounts. For retrieving graphs from X-Ray directly as opposed to the Transaction-Search Log group, see GetTraceGraph.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRetrievedTracesGraphResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRetrievedTracesGraphRequest'
      tags:
      - Operations
  /GetTraceSegmentDestination:
    post:
      operationId: GetTraceSegmentDestination
      summary: Get Trace Segment Destination
      description: Retrieves the current destination of data sent to PutTraceSegments and OpenTelemetry protocol (OTLP) endpoint. The Transaction Search feature requires a CloudWatchLogs destination. For more information, see Transaction Search and OpenTelemetry.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTraceSegmentDestinationResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTraceSegmentDestinationRequest'
      tags:
      - Operations
  /ListRetrievedTraces:
    post:
      operationId: ListRetrievedTraces
      summary: List Retrieved Traces
      description: Retrieves a list of traces for a given RetrievalToken from the CloudWatch log group generated by Transaction Search. For information on what each trace returns, see BatchGetTraces. This API does not initiate a retrieval process. To start a trace retrieval, use StartTraceRetrieval, which generates the required RetrievalToken. When the RetrievalStatus is not COMPLETE, the API will return an empty response. Retry the request once the retrieval has completed to access the full list of traces. For cross-account observability, this API can retrieve traces from linked accounts when CloudWatch log is set as the destination across relevant accounts. For more details, see CloudWatch cross-account observability. For retrieving data from X-Ray directly as opposed to the Transaction Search generated log group, see BatchGetTraces.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRetrievedTracesResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRetrievedTracesRequest'
      tags:
      - Operations
  /StartTraceRetrieval:
    post:
      operationId: StartTraceRetrieval
      summary: Start Trace Retrieval
      description: Initiates a trace retrieval process using the specified time range and for the given trace IDs in the Transaction Search generated CloudWatch log group. For more information, see Transaction Search. API returns a RetrievalToken, which can be used with ListRetrievedTraces or GetRetrievedTracesGraph to fetch results. Retrievals will time out after 60 minutes. To execute long time ranges, consider segmenting into multiple retrievals. If you are using CloudWatch cross-account observability, you can use this operation in a monitoring account to retrieve data from a linked source account, as long as both accounts have transaction search enabled. For retrieving data from X-Ray directly as opposed to the Transaction-Search Log group, see BatchGetTraces.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartTraceRetrievalResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartTraceRetrievalRequest'
      tags:
      - Operations
  /UpdateIndexingRule:
    post:
      operationId: UpdateIndexingRule
      summary: Update Indexing Rule
      description: Modifies an indexing rule’s configuration. Indexing rules are used for determining the sampling rate for spans indexed from CloudWatch Logs. For more information, see Transaction Search.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateIndexingRuleResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIndexingRuleRequest'
      tags:
      - Operations
  /UpdateTraceSegmentDestination:
    post:
      operationId: UpdateTraceSegmentDestination
      summary: Update Trace Segment Destination
      description: Modifies the destination of data sent to PutTraceSegments. The Transaction Search feature requires the CloudWatchLogs destination. For more information, see Transaction Search.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTraceSegmentDestinationResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTraceSegmentDestinationRequest'
      tags:
      - Operations
components:
  schemas:
    ProbabilisticRuleValue:
      type: object
      properties:
        DesiredSamplingPercentage:
          type: number
          description: Configured sampling percentage of traceIds. Note that sampling can be subject to limits to ensure completeness of data.
        ActualSamplingPercentage:
          type: number
          description: Applied sampling percentage of traceIds.
      required:
      - DesiredSamplingPercentage
    IndexingRuleValue:
      type: object
      properties:
        Probabilistic:
          $ref: '#/components/schemas/ProbabilisticRuleValue'
      description: Exactly one member is set.
    Alias:
      type: object
      properties:
        Name:
          type: string
          description: The canonical name of the alias.
        Names:
          type: array
          items:
            type: string
          description: A list of names for the alias, including the canonical name.
        Type:
          type: string
          description: The type of the alias.
    StartTraceRetrievalRequest:
      type: object
      properties:
        TraceIds:
          type: array
          items:
            type: string
          description: Specify the trace IDs of the traces to be retrieved.
        StartTime:
          type: string
          format: date-time
          description: The start of the time range to retrieve traces. The range is inclusive, so the specified start time is included in the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
        EndTime:
          type: string
          format: date-time
          description: The end of the time range to retrieve traces. The range is inclusive, so the specified end time is included in the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
      required:
      - TraceIds
      - StartTime
      - EndTime
    ProbabilisticRuleValueUpdate:
      type: object
      properties:
        DesiredSamplingPercentage:
          type: number
          description: Configured sampling percentage of traceIds. Note that sampling can be subject to limits to ensure completeness of data.
      required:
      - DesiredSamplingPercentage
    GetTraceSegmentDestinationResult:
      type: object
      properties:
        Destination:
          type: string
          enum:
          - XRay
          - CloudWatchLogs
          description: Retrieves the current destination.
        Status:
          type: string
          enum:
          - PENDING
          - ACTIVE
          description: Status of the retrieval.
    EdgeStatistics:
      type: object
      properties:
        OkCount:
          type: integer
          description: The number of requests that completed with a 2xx Success status code.
        ErrorStatistics:
          $ref: '#/components/schemas/ErrorStatistics'
        FaultStatistics:
          $ref: '#/components/schemas/FaultStatistics'
        TotalCount:
          type: integer
          description: The total number of completed requests.
        TotalResponseTime:
          type: number
          description: The aggregate response time of completed requests.
    FaultStatistics:
      type: object
      properties:
        OtherCount:
          type: integer
          description: The number of requests that failed with untracked 5xx Server Error status codes.
        TotalCount:
          type: integer
          description: The total number of requests that failed with a 5xx Server Error status code.
    IndexingRuleValueUpdate:
      type: object
      properties:
        Probabilistic:
          $ref: '#/components/schemas/ProbabilisticRuleValueUpdate'
      description: Exactly one member is set.
    UpdateTraceSegmentDestinationResult:
      type: object
      properties:
        Destination:
          type: string
          enum:
          - XRay
          - CloudWatchLogs
          description: The destination of the trace segments.
        Status:
          type: string
          enum:
          - PENDING
          - ACTIVE
          description: The status of the update.
    GetRetrievedTracesGraphResult:
      type: object
      properties:
        RetrievalStatus:
          type: string
          enum:
          - SCHEDULED
          - RUNNING
          - COMPLETE
          - FAILED
          - CANCELLED
          - TIMEOUT
          description: Status of the retrieval.
        Services:
          type: array
          items:
            $ref: '#/components/schemas/RetrievedService'
          description: Retrieved services.
        NextToken:
          type: string
          description: Specify the pagination token returned by a previous request to retrieve the next page of indexes.
    GetIndexingRulesRequest:
      type: object
      properties:
        NextToken:
          type: string
          description: Specify the pagination token returned by a previous request to retrieve the next page of indexes.
    InvalidRequestException:
      type: object
      properties:
        Message:
          type: string
    CloudWatchLogsConfiguration:
      type: object
      properties:
        SpansLogGroupKmsKeyId:
          type: string
          description: The ARN of an AWS Key Management Service (AWS KMS) key that you create and manage, in the same account and Region, used to encrypt the aws/spans log group. Key IDs and alias ARNs are not supported. X-Ray applies the key only when it creates aws/spans. If the account already has an aws/spans log group, X-Ray fails the request with an InvalidRequestException and does not change the log group. To enable Transaction Search with the existing log group as it is, call UpdateTraceSegmentDestination again without SpansLogGroupKmsKeyId. To set or change the key of the existing log group, use the CloudWa
    CancelTraceRetrievalRequest:
      type: object
      properties:
        RetrievalToken:
          type: string
          description: Retrieval token.
      required:
      - RetrievalToken
    RetrievedTrace:
      type: object
      properties:
        Id:
          type: string
          description: The unique identifier for the span.
        Duration:
          type: number
          description: The length of time in seconds between the start time of the root span and the end time of the last span that completed.
        Spans:
          type: array
          items:
            $ref: '#/components/schemas/Span'
          description: Spans that comprise the trace.
    CancelTraceRetrievalResult:
      type: object
      properties: {}
    ServiceStatistics:
      type: object
      properties:
        OkCount:
          type: integer
          description: The number of requests that completed with a 2xx Success status code.
        ErrorStatistics:
          $ref: '#/components/schemas/ErrorStatistics'
        FaultStatistics:
          $ref: '#/components/schemas/FaultStatistics'
        TotalCount:
          type: integer
          description: The total number of completed requests.
        TotalResponseTime:
          type: number
          description: The aggregate response time of completed requests.
    IndexingRule:
      type: object
      properties:
        Name:
          type: string
          description: The name of the indexing rule.
        ModifiedAt:
          type: string
          format: date-time
          description: Displays when the rule was last modified, in Unix time seconds.
        Rule:
          $ref: '#/components/schemas/IndexingRuleValue'
    GetIndexingRulesResult:
      type: object
      properties:
        IndexingRules:
          type: array
          items:
            $ref: '#/components/schemas/IndexingRule'
          description: Retrieves all indexing rules.
        NextToken:
          type: string
          description: Specify the pagination token returned by a previous request to retrieve the next page of indexes.
    StartTraceRetrievalResult:
      type: object
      properties:
        RetrievalToken:
          type: string
          description: Retrieval token.
    RetrievedService:
      type: object
      properties:
        Service:
          $ref: '#/components/schemas/Service'
        Links:
          type: array
          items:
            $ref: '#/components/schemas/GraphLink'
          description: Relation between two 2 services.
    Edge:
      type: object
      properties:
        ReferenceId:
          type: integer
          description: Identifier of the edge. Unique within a service map.
        StartTime:
          type: string
          format: date-time
          description: The start time of the first segment on the edge.
        EndTime:
          type: string
          format: date-time
          description: The end time of the last segment on the edge.
        SummaryStatistics:
          $ref: '#/components/schemas/EdgeStatistics'
        ResponseTimeHistogram:
          type: array
          items:
            $ref: '#/components/schemas/HistogramEntry'
          description: A histogram that maps the spread of client response times on an edge. Only populated for synchronous edges.
        Aliases:
          type: array
          items:
            $ref: '#/components/schemas/Alias'
          description: Aliases for the edge.
        EdgeType:
          type: string
          description: Describes an asynchronous connection, with a value of link.
        ReceivedEventAgeHistogram:
          type: array
          items:
            $ref: '#/components/schemas/HistogramEntry'
          description: A histogram that maps the spread of event age when received by consumers. Age is calculated each time an event is received. Only populated when EdgeType is link.
    UpdateIndexingRuleResult:
      type: object
      properties:
        IndexingRule:
          $ref: '#/components/schemas/IndexingRule'
    ThrottledException:
      type: object
      properties:
        Message:
          type: string
    UpdateIndexingRuleRequest:
      type: object
      properties:
        Name:
          type: string
          description: Name of the indexing rule to be updated.
        Rule:
          $ref: '#/components/schemas/IndexingRuleValueUpdate'
      required:
      - Name
      - Rule
    GraphLink:
      type: object
      properties:
        ReferenceType:
          type: string
          description: Relationship of a trace to the corresponding service.
        SourceTraceId:
          type: string
          description: Source trace of a link relationship.
        DestinationTraceIds:
          type: array
          items:
            type: string
          description: Destination traces of a link relationship.
    ListRetrievedTracesRequest:
      type: object
      properties:
        RetrievalToken:
          type: string
          description: Retrieval token.
        TraceFormat:
          type: string
          enum:
          - XRAY
          - OTEL
          description: Format of the requested traces.
        NextToken:
          type: string
          description: Specify the pagination token returned by a previous request to retrieve the next page of indexes.
      required:
      - RetrievalToken
    Span:
      type: object
      properties:
        Id:
          type: string
          description: The span ID.
        Document:
          type: string
          description: The span document.
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
        ResourceName:
          type: string
    GetTraceSegmentDestinationRequest:
      type: object
      properties: {}
    UpdateTraceSegmentDestinationRequest:
      type: object
      properties:
        Destination:
          type: string
          enum:
          - XRay
          - CloudWatchLogs
          description: The configured destination of trace segments.
        CloudWatchLogsConfiguration:
          $ref: '#/components/schemas/CloudWatchLogsConfiguration'
    Service:
      type: object
      properties:
        ReferenceId:
          type: integer
          description: Identifier for the service. Unique within the service map.
        Name:
          type: string
          description: The canonical name of the service.
        Names:
          type: array
          items:
            type: string
          description: A list of names for the service, including the canonical name.
        Root:
          type: boolean
          description: Indicates that the service was the first service to process a request.
        AccountId:
          type: string
          description: Identifier of the Amazon Web Services account in which the service runs.
        Type:
          type: string
          description: The type of service. Amazon Web Services Resource - The type of an Amazon Web Services resource. For example, AWS::EC2::Instance for an application running on Amazon EC2 or AWS::DynamoDB::Table for an Amazon DynamoDB table that the application used. Amazon Web Services Service - The type of an Amazon Web Services service. For example, AWS::DynamoDB for downstream calls to Amazon DynamoDB that didn't target a specific table. client - Represents the clients that sent requests to a root service. remote - A downstream service of indeterminate type.
        State:
          type: string
          description: The service's state.
        StartTime:
          type: string
          format: date-time
          description: The start time of the first segment that the service generated.
        EndTime:
          type: string
          format: date-time
          description: The end time of the last segment that the service generated.
        Edges:
          type: array
          items:
            $ref: '#/components/schemas/Edge'
          description: Connections to downstream services.
        SummaryStatistics:
          $ref: '#/components/schemas/ServiceStatistics'
        DurationHistogram:
          type: array
          items:
            $ref: '#/components/schemas/HistogramEntry'
          description: A histogram that maps the spread of service durations.
        ResponseTimeHistogram:
          type: array
          items:
            $ref: '#/components/schemas/HistogramEntry'
          description: A histogram that maps the spread of service response times.
    ErrorStatistics:
      type: object
      properties:
        ThrottleCount:
          type: integer
          description: The number of requests that failed with a 429 throttling status code.
        OtherCount:
          type: integer
          description: The number of requests that failed with untracked 4xx Client Error status codes.
        TotalCount:
          type: integer
          description: The total number of requests that failed with a 4xx Client Error status code.
    GetRetrievedTracesGraphRequest:
      type: object
      properties:
        RetrievalToken:
          type: string
          description: Retrieval token.
        NextToken:
          type: string
          description: Specify the pagination token returned by a previous request to retrieve the next page of indexes.
      required:
      - RetrievalToken
    ListRetrievedTracesResult:
      type: object
      properties:
        RetrievalStatus:
          type: string
          enum:
          - SCHEDULED
          - RUNNING
          - COMPLETE
          - FAILED
          - CANCELLED
          - TIMEOUT
          description: Status of the retrieval.
        TraceFormat:
          type: string
          enum:
          - XRAY
          - OTEL
          description: Format of the requested traces.
        Traces:
          type: array
          items:
            $ref: '#/components/schemas/RetrievedTrace'
          description: Full traces for the specified requests.
        NextToken:
          type: string
          description: Specify the pagination token returned by a previous request to retrieve the next page of indexes.
    HistogramEntry:
      type: object
      properties:
        Value:
          type: number
          description: The value of the entry.
        Count:
          type: integer
          description: The prevalence of the entry.
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: xray
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/xray/service/2016-04-12/xray-2016-04-12.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)