AWS SDK for PHP 3.x

Service ID: xray

Version: 2016-04-12

This page describes the parameters and results for the operations of the AWS X-Ray (2016-04-12), and shows how to use the Aws\XRay\XRayClient object to call the described operations. This documentation is specific to the 2016-04-12 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

BatchGetTraces ( array $params = [] )
Retrieves a list of traces specified by ID.
CreateGroup ( array $params = [] )
Creates a group resource with a name and a filter expression.
CreateSamplingRule ( array $params = [] )
Creates a rule to control sampling behavior for instrumented applications.
DeleteGroup ( array $params = [] )
Deletes a group resource.
DeleteResourcePolicy ( array $params = [] )
Deletes a resource policy from the target Amazon Web Services account.
DeleteSamplingRule ( array $params = [] )
Deletes a sampling rule.
GetEncryptionConfig ( array $params = [] )
Retrieves the current encryption configuration for X-Ray data.
GetGroup ( array $params = [] )
Retrieves group resource details.
GetGroups ( array $params = [] )
Retrieves all active group details.
GetInsight ( array $params = [] )
Retrieves the summary information of an insight.
GetInsightEvents ( array $params = [] )
X-Ray reevaluates insights periodically until they're resolved, and records each intermediate state as an event.
GetInsightImpactGraph ( array $params = [] )
Retrieves a service graph structure filtered by the specified insight.
GetInsightSummaries ( array $params = [] )
Retrieves the summaries of all insights in the specified group matching the provided filter values.
GetSamplingRules ( array $params = [] )
Retrieves all sampling rules.
GetSamplingStatisticSummaries ( array $params = [] )
Retrieves information about recent sampling results for all sampling rules.
GetSamplingTargets ( array $params = [] )
Requests a sampling quota for rules that the service is using to sample requests.
GetServiceGraph ( array $params = [] )
Retrieves a document that describes services that process incoming requests, and downstream services that they call as a result.
GetTimeSeriesServiceStatistics ( array $params = [] )
Get an aggregation of service statistics defined by a specific time range.
GetTraceGraph ( array $params = [] )
Retrieves a service graph for one or more specific trace IDs.
GetTraceSummaries ( array $params = [] )
Retrieves IDs and annotations for traces available for a specified time frame using an optional filter.
ListResourcePolicies ( array $params = [] )
Returns the list of resource policies in the target Amazon Web Services account.
ListTagsForResource ( array $params = [] )
Returns a list of tags that are applied to the specified Amazon Web Services X-Ray group or sampling rule.
PutEncryptionConfig ( array $params = [] )
Updates the encryption configuration for X-Ray data.
PutResourcePolicy ( array $params = [] )
Sets the resource policy to grant one or more Amazon Web Services services and accounts permissions to access X-Ray.
PutTelemetryRecords ( array $params = [] )
Used by the Amazon Web Services X-Ray daemon to upload telemetry.
PutTraceSegments ( array $params = [] )
Uploads segment documents to Amazon Web Services X-Ray.
TagResource ( array $params = [] )
Applies tags to an existing Amazon Web Services X-Ray group or sampling rule.
UntagResource ( array $params = [] )
Removes tags from an Amazon Web Services X-Ray group or sampling rule.
UpdateGroup ( array $params = [] )
Updates a group resource.
UpdateSamplingRule ( array $params = [] )
Modifies a sampling rule's configuration.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

BatchGetTraces
GetGroups
GetInsightEvents
GetInsightSummaries
GetSamplingRules
GetSamplingStatisticSummaries
GetServiceGraph
GetTimeSeriesServiceStatistics
GetTraceGraph
GetTraceSummaries
ListResourcePolicies
ListTagsForResource

Operations

BatchGetTraces

$result = $client->batchGetTraces([/* ... */]);
$promise = $client->batchGetTracesAsync([/* ... */]);

Retrieves a list of traces specified by ID. Each trace is a collection of segment documents that originates from a single request. Use GetTraceSummaries to get a list of trace IDs.

Parameter Syntax

$result = $client->batchGetTraces([
    'NextToken' => '<string>',
    'TraceIds' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

NextToken

Type: string

Pagination token.

TraceIds

Required: Yes
Type: Array of strings

Specify the trace IDs of requests for which to retrieve segments.

Result Syntax

[
    'NextToken' => '<string>',
    'Traces' => [
        [
            'Duration' => <float>,
            'Id' => '<string>',
            'LimitExceeded' => true || false,
            'Segments' => [
                [
                    'Document' => '<string>',
                    'Id' => '<string>',
                ],
                // ...
            ],
        ],
        // ...
    ],
    'UnprocessedTraceIds' => ['<string>', ...],
]

Result Details

Members

NextToken

Type: string

Pagination token.

Traces

Type: Array of Trace structures

Full traces for the specified requests.

UnprocessedTraceIds

Type: Array of strings

Trace IDs of requests that haven't been processed.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

CreateGroup

$result = $client->createGroup([/* ... */]);
$promise = $client->createGroupAsync([/* ... */]);

Creates a group resource with a name and a filter expression.

Parameter Syntax

$result = $client->createGroup([
    'FilterExpression' => '<string>',
    'GroupName' => '<string>', // REQUIRED
    'InsightsConfiguration' => [
        'InsightsEnabled' => true || false,
        'NotificationsEnabled' => true || false,
    ],
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

FilterExpression

Type: string

The filter expression defining criteria by which to group traces.

GroupName

Required: Yes
Type: string

The case-sensitive name of the new group. Default is a reserved name and names must be unique.

InsightsConfiguration

Type: InsightsConfiguration structure

The structure containing configurations related to insights.

The InsightsEnabled boolean can be set to true to enable insights for the new group or false to disable insights for the new group.
The NotificationsEnabled boolean can be set to true to enable insights notifications for the new group. Notifications may only be enabled on a group with InsightsEnabled set to true.

Tags

Type: Array of Tag structures

A map that contains one or more tag keys and tag values to attach to an X-Ray group. For more information about ways to use tags, see Tagging Amazon Web Services resources in the Amazon Web Services General Reference.

The following restrictions apply to tags:

Maximum number of user-applied tags per resource: 50
Maximum tag key length: 128 Unicode characters
Maximum tag value length: 256 Unicode characters
Valid values for key and value: a-z, A-Z, 0-9, space, and the following characters: _ . : / = + - and @
Tag keys and values are case sensitive.
Don't use aws: as a prefix for keys; it's reserved for Amazon Web Services use.

Result Syntax

[
    'Group' => [
        'FilterExpression' => '<string>',
        'GroupARN' => '<string>',
        'GroupName' => '<string>',
        'InsightsConfiguration' => [
            'InsightsEnabled' => true || false,
            'NotificationsEnabled' => true || false,
        ],
    ],
]

Result Details

Members

Group

Type: Group structure

The group that was created. Contains the name of the group that was created, the Amazon Resource Name (ARN) of the group that was generated based on the group name, the filter expression, and the insight configuration that was assigned to the group.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

CreateSamplingRule

$result = $client->createSamplingRule([/* ... */]);
$promise = $client->createSamplingRuleAsync([/* ... */]);

Creates a rule to control sampling behavior for instrumented applications. Services retrieve rules with GetSamplingRules, and evaluate each rule in ascending order of priority for each request. If a rule matches, the service records a trace, borrowing it from the reservoir size. After 10 seconds, the service reports back to X-Ray with GetSamplingTargets to get updated versions of each in-use rule. The updated rule contains a trace quota that the service can use instead of borrowing from the reservoir.

Parameter Syntax

$result = $client->createSamplingRule([
    'SamplingRule' => [ // REQUIRED
        'Attributes' => ['<string>', ...],
        'FixedRate' => <float>, // REQUIRED
        'HTTPMethod' => '<string>', // REQUIRED
        'Host' => '<string>', // REQUIRED
        'Priority' => <integer>, // REQUIRED
        'ReservoirSize' => <integer>, // REQUIRED
        'ResourceARN' => '<string>', // REQUIRED
        'RuleARN' => '<string>',
        'RuleName' => '<string>',
        'ServiceName' => '<string>', // REQUIRED
        'ServiceType' => '<string>', // REQUIRED
        'URLPath' => '<string>', // REQUIRED
        'Version' => <integer>, // REQUIRED
    ],
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

SamplingRule

Required: Yes
Type: SamplingRule structure

The rule definition.

Tags

Type: Array of Tag structures

A map that contains one or more tag keys and tag values to attach to an X-Ray sampling rule. For more information about ways to use tags, see Tagging Amazon Web Services resources in the Amazon Web Services General Reference.

The following restrictions apply to tags:

Maximum number of user-applied tags per resource: 50
Maximum tag key length: 128 Unicode characters
Maximum tag value length: 256 Unicode characters
Valid values for key and value: a-z, A-Z, 0-9, space, and the following characters: _ . : / = + - and @
Tag keys and values are case sensitive.
Don't use aws: as a prefix for keys; it's reserved for Amazon Web Services use.

Result Syntax

[
    'SamplingRuleRecord' => [
        'CreatedAt' => <DateTime>,
        'ModifiedAt' => <DateTime>,
        'SamplingRule' => [
            'Attributes' => ['<string>', ...],
            'FixedRate' => <float>,
            'HTTPMethod' => '<string>',
            'Host' => '<string>',
            'Priority' => <integer>,
            'ReservoirSize' => <integer>,
            'ResourceARN' => '<string>',
            'RuleARN' => '<string>',
            'RuleName' => '<string>',
            'ServiceName' => '<string>',
            'ServiceType' => '<string>',
            'URLPath' => '<string>',
            'Version' => <integer>,
        ],
    ],
]

Result Details

Members

SamplingRuleRecord

Type: SamplingRuleRecord structure

The saved rule definition and metadata.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.
RuleLimitExceededException:
You have reached the maximum number of sampling rules.

DeleteGroup

$result = $client->deleteGroup([/* ... */]);
$promise = $client->deleteGroupAsync([/* ... */]);

Deletes a group resource.

Parameter Syntax

$result = $client->deleteGroup([
    'GroupARN' => '<string>',
    'GroupName' => '<string>',
]);

Parameter Details

Members

GroupARN

Type: string

The ARN of the group that was generated on creation.

GroupName

Type: string

The case-sensitive name of the group.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

DeleteResourcePolicy

$result = $client->deleteResourcePolicy([/* ... */]);
$promise = $client->deleteResourcePolicyAsync([/* ... */]);

Deletes a resource policy from the target Amazon Web Services account.

Parameter Syntax

$result = $client->deleteResourcePolicy([
    'PolicyName' => '<string>', // REQUIRED
    'PolicyRevisionId' => '<string>',
]);

Parameter Details

Members

PolicyName

Required: Yes
Type: string

The name of the resource policy to delete.

PolicyRevisionId

Type: string

Specifies a specific policy revision to delete. Provide a PolicyRevisionId to ensure an atomic delete operation. If the provided revision id does not match the latest policy revision id, an InvalidPolicyRevisionIdException exception is returned.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
InvalidPolicyRevisionIdException:
A policy revision id was provided which does not match the latest policy revision. This exception is also if a policy revision id of 0 is provided via PutResourcePolicy and a policy with the same name already exists.
ThrottledException:
The request exceeds the maximum number of requests per second.

DeleteSamplingRule

$result = $client->deleteSamplingRule([/* ... */]);
$promise = $client->deleteSamplingRuleAsync([/* ... */]);

Deletes a sampling rule.

Parameter Syntax

$result = $client->deleteSamplingRule([
    'RuleARN' => '<string>',
    'RuleName' => '<string>',
]);

Parameter Details

Members

RuleARN

Type: string

The ARN of the sampling rule. Specify a rule by either name or ARN, but not both.

RuleName

Type: string

The name of the sampling rule. Specify a rule by either name or ARN, but not both.

Result Syntax

[
    'SamplingRuleRecord' => [
        'CreatedAt' => <DateTime>,
        'ModifiedAt' => <DateTime>,
        'SamplingRule' => [
            'Attributes' => ['<string>', ...],
            'FixedRate' => <float>,
            'HTTPMethod' => '<string>',
            'Host' => '<string>',
            'Priority' => <integer>,
            'ReservoirSize' => <integer>,
            'ResourceARN' => '<string>',
            'RuleARN' => '<string>',
            'RuleName' => '<string>',
            'ServiceName' => '<string>',
            'ServiceType' => '<string>',
            'URLPath' => '<string>',
            'Version' => <integer>,
        ],
    ],
]

Result Details

Members

SamplingRuleRecord

Type: SamplingRuleRecord structure

The deleted rule definition and metadata.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetEncryptionConfig

$result = $client->getEncryptionConfig([/* ... */]);
$promise = $client->getEncryptionConfigAsync([/* ... */]);

Retrieves the current encryption configuration for X-Ray data.

Parameter Syntax

$result = $client->getEncryptionConfig([
]);

Parameter Details

Members

Result Syntax

[
    'EncryptionConfig' => [
        'KeyId' => '<string>',
        'Status' => 'UPDATING|ACTIVE',
        'Type' => 'NONE|KMS',
    ],
]

Result Details

Members

EncryptionConfig

Type: EncryptionConfig structure

The encryption configuration document.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetGroup

$result = $client->getGroup([/* ... */]);
$promise = $client->getGroupAsync([/* ... */]);

Retrieves group resource details.

Parameter Syntax

$result = $client->getGroup([
    'GroupARN' => '<string>',
    'GroupName' => '<string>',
]);

Parameter Details

Members

GroupARN

Type: string

The ARN of the group that was generated on creation.

GroupName

Type: string

The case-sensitive name of the group.

Result Syntax

[
    'Group' => [
        'FilterExpression' => '<string>',
        'GroupARN' => '<string>',
        'GroupName' => '<string>',
        'InsightsConfiguration' => [
            'InsightsEnabled' => true || false,
            'NotificationsEnabled' => true || false,
        ],
    ],
]

Result Details

Members

Group

Type: Group structure

The group that was requested. Contains the name of the group, the ARN of the group, the filter expression, and the insight configuration assigned to the group.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetGroups

$result = $client->getGroups([/* ... */]);
$promise = $client->getGroupsAsync([/* ... */]);

Retrieves all active group details.

Parameter Syntax

$result = $client->getGroups([
    'NextToken' => '<string>',
]);

Parameter Details

Members

NextToken

Type: string

Pagination token.

Result Syntax

[
    'Groups' => [
        [
            'FilterExpression' => '<string>',
            'GroupARN' => '<string>',
            'GroupName' => '<string>',
            'InsightsConfiguration' => [
                'InsightsEnabled' => true || false,
                'NotificationsEnabled' => true || false,
            ],
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members

Groups

Type: Array of GroupSummary structures

The collection of all active groups.

NextToken

Type: string

Pagination token.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetInsight

$result = $client->getInsight([/* ... */]);
$promise = $client->getInsightAsync([/* ... */]);

Retrieves the summary information of an insight. This includes impact to clients and root cause services, the top anomalous services, the category, the state of the insight, and the start and end time of the insight.

Parameter Syntax

$result = $client->getInsight([
    'InsightId' => '<string>', // REQUIRED
]);

Parameter Details

Members

InsightId

Required: Yes
Type: string

The insight's unique identifier. Use the GetInsightSummaries action to retrieve an InsightId.

Result Syntax

[
    'Insight' => [
        'Categories' => ['<string>', ...],
        'ClientRequestImpactStatistics' => [
            'FaultCount' => <integer>,
            'OkCount' => <integer>,
            'TotalCount' => <integer>,
        ],
        'EndTime' => <DateTime>,
        'GroupARN' => '<string>',
        'GroupName' => '<string>',
        'InsightId' => '<string>',
        'RootCauseServiceId' => [
            'AccountId' => '<string>',
            'Name' => '<string>',
            'Names' => ['<string>', ...],
            'Type' => '<string>',
        ],
        'RootCauseServiceRequestImpactStatistics' => [
            'FaultCount' => <integer>,
            'OkCount' => <integer>,
            'TotalCount' => <integer>,
        ],
        'StartTime' => <DateTime>,
        'State' => 'ACTIVE|CLOSED',
        'Summary' => '<string>',
        'TopAnomalousServices' => [
            [
                'ServiceId' => [
                    'AccountId' => '<string>',
                    'Name' => '<string>',
                    'Names' => ['<string>', ...],
                    'Type' => '<string>',
                ],
            ],
            // ...
        ],
    ],
]

Result Details

Members

Insight

Type: Insight structure

The summary information of an insight.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetInsightEvents

$result = $client->getInsightEvents([/* ... */]);
$promise = $client->getInsightEventsAsync([/* ... */]);

X-Ray reevaluates insights periodically until they're resolved, and records each intermediate state as an event. You can review an insight's events in the Impact Timeline on the Inspect page in the X-Ray console.

Parameter Syntax

$result = $client->getInsightEvents([
    'InsightId' => '<string>', // REQUIRED
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members

InsightId

Required: Yes
Type: string

The insight's unique identifier. Use the GetInsightSummaries action to retrieve an InsightId.

MaxResults

Type: int

Used to retrieve at most the specified value of events.

NextToken

Type: string

Specify the pagination token returned by a previous request to retrieve the next page of events.

Result Syntax

[
    'InsightEvents' => [
        [
            'ClientRequestImpactStatistics' => [
                'FaultCount' => <integer>,
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
            ],
            'EventTime' => <DateTime>,
            'RootCauseServiceRequestImpactStatistics' => [
                'FaultCount' => <integer>,
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
            ],
            'Summary' => '<string>',
            'TopAnomalousServices' => [
                [
                    'ServiceId' => [
                        'AccountId' => '<string>',
                        'Name' => '<string>',
                        'Names' => ['<string>', ...],
                        'Type' => '<string>',
                    ],
                ],
                // ...
            ],
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members

InsightEvents

Type: Array of InsightEvent structures

A detailed description of the event. This includes the time of the event, client and root cause impact statistics, and the top anomalous service at the time of the event.

NextToken

Type: string

Use this token to retrieve the next page of insight events.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetInsightImpactGraph

$result = $client->getInsightImpactGraph([/* ... */]);
$promise = $client->getInsightImpactGraphAsync([/* ... */]);

Retrieves a service graph structure filtered by the specified insight. The service graph is limited to only structural information. For a complete service graph, use this API with the GetServiceGraph API.

Parameter Syntax

$result = $client->getInsightImpactGraph([
    'EndTime' => <integer || string || DateTime>, // REQUIRED
    'InsightId' => '<string>', // REQUIRED
    'NextToken' => '<string>',
    'StartTime' => <integer || string || DateTime>, // REQUIRED
]);

Parameter Details

Members

EndTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The estimated end time of the insight, in Unix time seconds. The EndTime is exclusive of the value provided. The time range between the start time and end time can't be more than six hours.

InsightId

Required: Yes
Type: string

The insight's unique identifier. Use the GetInsightSummaries action to retrieve an InsightId.

NextToken

Type: string

Specify the pagination token returned by a previous request to retrieve the next page of results.

StartTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The estimated start time of the insight, in Unix time seconds. The StartTime is inclusive of the value provided and can't be more than 30 days old.

Result Syntax

[
    'EndTime' => <DateTime>,
    'InsightId' => '<string>',
    'NextToken' => '<string>',
    'ServiceGraphEndTime' => <DateTime>,
    'ServiceGraphStartTime' => <DateTime>,
    'Services' => [
        [
            'AccountId' => '<string>',
            'Edges' => [
                [
                    'ReferenceId' => <integer>,
                ],
                // ...
            ],
            'Name' => '<string>',
            'Names' => ['<string>', ...],
            'ReferenceId' => <integer>,
            'Type' => '<string>',
        ],
        // ...
    ],
    'StartTime' => <DateTime>,
]

Result Details

Members

EndTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The provided end time.

InsightId

Type: string

The insight's unique identifier.

NextToken

Type: string

Pagination token.

ServiceGraphEndTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, at which the service graph ended.

ServiceGraphStartTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, at which the service graph started.

Services

Type: Array of InsightImpactGraphService structures

The Amazon Web Services instrumented services related to the insight.

StartTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The provided start time.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetInsightSummaries

$result = $client->getInsightSummaries([/* ... */]);
$promise = $client->getInsightSummariesAsync([/* ... */]);

Retrieves the summaries of all insights in the specified group matching the provided filter values.

Parameter Syntax

$result = $client->getInsightSummaries([
    'EndTime' => <integer || string || DateTime>, // REQUIRED
    'GroupARN' => '<string>',
    'GroupName' => '<string>',
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'StartTime' => <integer || string || DateTime>, // REQUIRED
    'States' => ['<string>', ...],
]);

Parameter Details

Members

EndTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The end of the time frame in which the insights ended. The end time can't be more than 30 days old.

GroupARN

Type: string

The Amazon Resource Name (ARN) of the group. Required if the GroupName isn't provided.

GroupName

Type: string

The name of the group. Required if the GroupARN isn't provided.

MaxResults

Type: int

The maximum number of results to display.

NextToken

Type: string

Pagination token.

StartTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The beginning of the time frame in which the insights started. The start time can't be more than 30 days old.

States

Type: Array of strings

The list of insight states.

Result Syntax

[
    'InsightSummaries' => [
        [
            'Categories' => ['<string>', ...],
            'ClientRequestImpactStatistics' => [
                'FaultCount' => <integer>,
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
            ],
            'EndTime' => <DateTime>,
            'GroupARN' => '<string>',
            'GroupName' => '<string>',
            'InsightId' => '<string>',
            'LastUpdateTime' => <DateTime>,
            'RootCauseServiceId' => [
                'AccountId' => '<string>',
                'Name' => '<string>',
                'Names' => ['<string>', ...],
                'Type' => '<string>',
            ],
            'RootCauseServiceRequestImpactStatistics' => [
                'FaultCount' => <integer>,
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
            ],
            'StartTime' => <DateTime>,
            'State' => 'ACTIVE|CLOSED',
            'Summary' => '<string>',
            'TopAnomalousServices' => [
                [
                    'ServiceId' => [
                        'AccountId' => '<string>',
                        'Name' => '<string>',
                        'Names' => ['<string>', ...],
                        'Type' => '<string>',
                    ],
                ],
                // ...
            ],
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Members

InsightSummaries

Type: Array of InsightSummary structures

The summary of each insight within the group matching the provided filters. The summary contains the InsightID, start and end time, the root cause service, the root cause and client impact statistics, the top anomalous services, and the status of the insight.

NextToken

Type: string

Pagination token.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetSamplingRules

$result = $client->getSamplingRules([/* ... */]);
$promise = $client->getSamplingRulesAsync([/* ... */]);

Retrieves all sampling rules.

Parameter Syntax

$result = $client->getSamplingRules([
    'NextToken' => '<string>',
]);

Parameter Details

Members

NextToken

Type: string

Pagination token.

Result Syntax

[
    'NextToken' => '<string>',
    'SamplingRuleRecords' => [
        [
            'CreatedAt' => <DateTime>,
            'ModifiedAt' => <DateTime>,
            'SamplingRule' => [
                'Attributes' => ['<string>', ...],
                'FixedRate' => <float>,
                'HTTPMethod' => '<string>',
                'Host' => '<string>',
                'Priority' => <integer>,
                'ReservoirSize' => <integer>,
                'ResourceARN' => '<string>',
                'RuleARN' => '<string>',
                'RuleName' => '<string>',
                'ServiceName' => '<string>',
                'ServiceType' => '<string>',
                'URLPath' => '<string>',
                'Version' => <integer>,
            ],
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

Pagination token.

SamplingRuleRecords

Type: Array of SamplingRuleRecord structures

Rule definitions and metadata.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetSamplingStatisticSummaries

$result = $client->getSamplingStatisticSummaries([/* ... */]);
$promise = $client->getSamplingStatisticSummariesAsync([/* ... */]);

Retrieves information about recent sampling results for all sampling rules.

Parameter Syntax

$result = $client->getSamplingStatisticSummaries([
    'NextToken' => '<string>',
]);

Parameter Details

Members

NextToken

Type: string

Pagination token.

Result Syntax

[
    'NextToken' => '<string>',
    'SamplingStatisticSummaries' => [
        [
            'BorrowCount' => <integer>,
            'RequestCount' => <integer>,
            'RuleName' => '<string>',
            'SampledCount' => <integer>,
            'Timestamp' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

Pagination token.

SamplingStatisticSummaries

Type: Array of SamplingStatisticSummary structures

Information about the number of requests instrumented for each sampling rule.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetSamplingTargets

$result = $client->getSamplingTargets([/* ... */]);
$promise = $client->getSamplingTargetsAsync([/* ... */]);

Requests a sampling quota for rules that the service is using to sample requests.

Parameter Syntax

$result = $client->getSamplingTargets([
    'SamplingStatisticsDocuments' => [ // REQUIRED
        [
            'BorrowCount' => <integer>,
            'ClientID' => '<string>', // REQUIRED
            'RequestCount' => <integer>, // REQUIRED
            'RuleName' => '<string>', // REQUIRED
            'SampledCount' => <integer>, // REQUIRED
            'Timestamp' => <integer || string || DateTime>, // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

SamplingStatisticsDocuments

Required: Yes
Type: Array of SamplingStatisticsDocument structures

Information about rules that the service is using to sample requests.

Result Syntax

[
    'LastRuleModification' => <DateTime>,
    'SamplingTargetDocuments' => [
        [
            'FixedRate' => <float>,
            'Interval' => <integer>,
            'ReservoirQuota' => <integer>,
            'ReservoirQuotaTTL' => <DateTime>,
            'RuleName' => '<string>',
        ],
        // ...
    ],
    'UnprocessedStatistics' => [
        [
            'ErrorCode' => '<string>',
            'Message' => '<string>',
            'RuleName' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

LastRuleModification

Type: timestamp (string|DateTime or anything parsable by strtotime)

The last time a user changed the sampling rule configuration. If the sampling rule configuration changed since the service last retrieved it, the service should call GetSamplingRules to get the latest version.

SamplingTargetDocuments

Type: Array of SamplingTargetDocument structures

Updated rules that the service should use to sample requests.

UnprocessedStatistics

Type: Array of UnprocessedStatistics structures

Information about SamplingStatisticsDocument that X-Ray could not process.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetServiceGraph

$result = $client->getServiceGraph([/* ... */]);
$promise = $client->getServiceGraphAsync([/* ... */]);

Retrieves a document that describes services that process incoming requests, and downstream services that they call as a result. Root services process incoming requests and make calls to downstream services. Root services are applications that use the Amazon Web Services X-Ray SDK. Downstream services can be other applications, Amazon Web Services resources, HTTP web APIs, or SQL databases.

Parameter Syntax

$result = $client->getServiceGraph([
    'EndTime' => <integer || string || DateTime>, // REQUIRED
    'GroupARN' => '<string>',
    'GroupName' => '<string>',
    'NextToken' => '<string>',
    'StartTime' => <integer || string || DateTime>, // REQUIRED
]);

Parameter Details

Members

EndTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The end of the timeframe for which to generate a graph.

GroupARN

Type: string

The Amazon Resource Name (ARN) of a group based on which you want to generate a graph.

GroupName

Type: string

The name of a group based on which you want to generate a graph.

NextToken

Type: string

Pagination token.

StartTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The start of the time frame for which to generate a graph.

Result Syntax

[
    'ContainsOldGroupVersions' => true || false,
    'EndTime' => <DateTime>,
    'NextToken' => '<string>',
    'Services' => [
        [
            'AccountId' => '<string>',
            'DurationHistogram' => [
                [
                    'Count' => <integer>,
                    'Value' => <float>,
                ],
                // ...
            ],
            'Edges' => [
                [
                    'Aliases' => [
                        [
                            'Name' => '<string>',
                            'Names' => ['<string>', ...],
                            'Type' => '<string>',
                        ],
                        // ...
                    ],
                    'EdgeType' => '<string>',
                    'EndTime' => <DateTime>,
                    'ReceivedEventAgeHistogram' => [
                        [
                            'Count' => <integer>,
                            'Value' => <float>,
                        ],
                        // ...
                    ],
                    'ReferenceId' => <integer>,
                    'ResponseTimeHistogram' => [
                        [
                            'Count' => <integer>,
                            'Value' => <float>,
                        ],
                        // ...
                    ],
                    'StartTime' => <DateTime>,
                    'SummaryStatistics' => [
                        'ErrorStatistics' => [
                            'OtherCount' => <integer>,
                            'ThrottleCount' => <integer>,
                            'TotalCount' => <integer>,
                        ],
                        'FaultStatistics' => [
                            'OtherCount' => <integer>,
                            'TotalCount' => <integer>,
                        ],
                        'OkCount' => <integer>,
                        'TotalCount' => <integer>,
                        'TotalResponseTime' => <float>,
                    ],
                ],
                // ...
            ],
            'EndTime' => <DateTime>,
            'Name' => '<string>',
            'Names' => ['<string>', ...],
            'ReferenceId' => <integer>,
            'ResponseTimeHistogram' => [
                [
                    'Count' => <integer>,
                    'Value' => <float>,
                ],
                // ...
            ],
            'Root' => true || false,
            'StartTime' => <DateTime>,
            'State' => '<string>',
            'SummaryStatistics' => [
                'ErrorStatistics' => [
                    'OtherCount' => <integer>,
                    'ThrottleCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'FaultStatistics' => [
                    'OtherCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
                'TotalResponseTime' => <float>,
            ],
            'Type' => '<string>',
        ],
        // ...
    ],
    'StartTime' => <DateTime>,
]

Result Details

Members

ContainsOldGroupVersions

Type: boolean

A flag indicating whether the group's filter expression has been consistent, or if the returned service graph may show traces from an older version of the group's filter expression.

EndTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The end of the time frame for which the graph was generated.

NextToken

Type: string

Pagination token.

Services

Type: Array of Service structures

The services that have processed a traced request during the specified time frame.

StartTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The start of the time frame for which the graph was generated.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetTimeSeriesServiceStatistics

$result = $client->getTimeSeriesServiceStatistics([/* ... */]);
$promise = $client->getTimeSeriesServiceStatisticsAsync([/* ... */]);

Get an aggregation of service statistics defined by a specific time range.

Parameter Syntax

$result = $client->getTimeSeriesServiceStatistics([
    'EndTime' => <integer || string || DateTime>, // REQUIRED
    'EntitySelectorExpression' => '<string>',
    'ForecastStatistics' => true || false,
    'GroupARN' => '<string>',
    'GroupName' => '<string>',
    'NextToken' => '<string>',
    'Period' => <integer>,
    'StartTime' => <integer || string || DateTime>, // REQUIRED
]);

Parameter Details

Members

EndTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The end of the time frame for which to aggregate statistics.

EntitySelectorExpression

Type: string

A filter expression defining entities that will be aggregated for statistics. Supports ID, service, and edge functions. If no selector expression is specified, edge statistics are returned.

ForecastStatistics

Type: boolean

The forecasted high and low fault count values. Forecast enabled requests require the EntitySelectorExpression ID be provided.

GroupARN

Type: string

The Amazon Resource Name (ARN) of the group for which to pull statistics from.

GroupName

Type: string

The case-sensitive name of the group for which to pull statistics from.

NextToken

Type: string

Pagination token.

Period

Type: int

Aggregation period in seconds.

StartTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The start of the time frame for which to aggregate statistics.

Result Syntax

[
    'ContainsOldGroupVersions' => true || false,
    'NextToken' => '<string>',
    'TimeSeriesServiceStatistics' => [
        [
            'EdgeSummaryStatistics' => [
                'ErrorStatistics' => [
                    'OtherCount' => <integer>,
                    'ThrottleCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'FaultStatistics' => [
                    'OtherCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
                'TotalResponseTime' => <float>,
            ],
            'ResponseTimeHistogram' => [
                [
                    'Count' => <integer>,
                    'Value' => <float>,
                ],
                // ...
            ],
            'ServiceForecastStatistics' => [
                'FaultCountHigh' => <integer>,
                'FaultCountLow' => <integer>,
            ],
            'ServiceSummaryStatistics' => [
                'ErrorStatistics' => [
                    'OtherCount' => <integer>,
                    'ThrottleCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'FaultStatistics' => [
                    'OtherCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
                'TotalResponseTime' => <float>,
            ],
            'Timestamp' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members

ContainsOldGroupVersions

Type: boolean

A flag indicating whether or not a group's filter expression has been consistent, or if a returned aggregation might show statistics from an older version of the group's filter expression.

NextToken

Type: string

Pagination token.

TimeSeriesServiceStatistics

Type: Array of TimeSeriesServiceStatistics structures

The collection of statistics.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetTraceGraph

$result = $client->getTraceGraph([/* ... */]);
$promise = $client->getTraceGraphAsync([/* ... */]);

Retrieves a service graph for one or more specific trace IDs.

Parameter Syntax

$result = $client->getTraceGraph([
    'NextToken' => '<string>',
    'TraceIds' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

NextToken

Type: string

Pagination token.

TraceIds

Required: Yes
Type: Array of strings

Trace IDs of requests for which to generate a service graph.

Result Syntax

[
    'NextToken' => '<string>',
    'Services' => [
        [
            'AccountId' => '<string>',
            'DurationHistogram' => [
                [
                    'Count' => <integer>,
                    'Value' => <float>,
                ],
                // ...
            ],
            'Edges' => [
                [
                    'Aliases' => [
                        [
                            'Name' => '<string>',
                            'Names' => ['<string>', ...],
                            'Type' => '<string>',
                        ],
                        // ...
                    ],
                    'EdgeType' => '<string>',
                    'EndTime' => <DateTime>,
                    'ReceivedEventAgeHistogram' => [
                        [
                            'Count' => <integer>,
                            'Value' => <float>,
                        ],
                        // ...
                    ],
                    'ReferenceId' => <integer>,
                    'ResponseTimeHistogram' => [
                        [
                            'Count' => <integer>,
                            'Value' => <float>,
                        ],
                        // ...
                    ],
                    'StartTime' => <DateTime>,
                    'SummaryStatistics' => [
                        'ErrorStatistics' => [
                            'OtherCount' => <integer>,
                            'ThrottleCount' => <integer>,
                            'TotalCount' => <integer>,
                        ],
                        'FaultStatistics' => [
                            'OtherCount' => <integer>,
                            'TotalCount' => <integer>,
                        ],
                        'OkCount' => <integer>,
                        'TotalCount' => <integer>,
                        'TotalResponseTime' => <float>,
                    ],
                ],
                // ...
            ],
            'EndTime' => <DateTime>,
            'Name' => '<string>',
            'Names' => ['<string>', ...],
            'ReferenceId' => <integer>,
            'ResponseTimeHistogram' => [
                [
                    'Count' => <integer>,
                    'Value' => <float>,
                ],
                // ...
            ],
            'Root' => true || false,
            'StartTime' => <DateTime>,
            'State' => '<string>',
            'SummaryStatistics' => [
                'ErrorStatistics' => [
                    'OtherCount' => <integer>,
                    'ThrottleCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'FaultStatistics' => [
                    'OtherCount' => <integer>,
                    'TotalCount' => <integer>,
                ],
                'OkCount' => <integer>,
                'TotalCount' => <integer>,
                'TotalResponseTime' => <float>,
            ],
            'Type' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

Pagination token.

Services

Type: Array of Service structures

The services that have processed one of the specified requests.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

GetTraceSummaries

$result = $client->getTraceSummaries([/* ... */]);
$promise = $client->getTraceSummariesAsync([/* ... */]);

Retrieves IDs and annotations for traces available for a specified time frame using an optional filter. To get the full traces, pass the trace IDs to BatchGetTraces.

A filter expression can target traced requests that hit specific service nodes or edges, have errors, or come from a known user. For example, the following filter expression targets traces that pass through api.example.com:

service("api.example.com")

This filter expression finds traces that have an annotation named account with the value 12345:

annotation.account = "12345"

For a full list of indexed fields and keywords that you can use in filter expressions, see Using Filter Expressions in the Amazon Web Services X-Ray Developer Guide.

Parameter Syntax

$result = $client->getTraceSummaries([
    'EndTime' => <integer || string || DateTime>, // REQUIRED
    'FilterExpression' => '<string>',
    'NextToken' => '<string>',
    'Sampling' => true || false,
    'SamplingStrategy' => [
        'Name' => 'PartialScan|FixedRate',
        'Value' => <float>,
    ],
    'StartTime' => <integer || string || DateTime>, // REQUIRED
    'TimeRangeType' => 'TraceId|Event',
]);

Parameter Details

Members

EndTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The end of the time frame for which to retrieve traces.

FilterExpression

Type: string

Specify a filter expression to retrieve trace summaries for services or requests that meet certain requirements.

NextToken

Type: string

Specify the pagination token returned by a previous request to retrieve the next page of results.

Sampling

Type: boolean

Set to true to get summaries for only a subset of available traces.

SamplingStrategy

Type: SamplingStrategy structure

A parameter to indicate whether to enable sampling on trace summaries. Input parameters are Name and Value.

StartTime

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The start of the time frame for which to retrieve traces.

TimeRangeType

Type: string

A parameter to indicate whether to query trace summaries by TraceId or Event time.

Result Syntax

[
    'ApproximateTime' => <DateTime>,
    'NextToken' => '<string>',
    'TraceSummaries' => [
        [
            'Annotations' => [
                '<AnnotationKey>' => [
                    [
                        'AnnotationValue' => [
                            'BooleanValue' => true || false,
                            'NumberValue' => <float>,
                            'StringValue' => '<string>',
                        ],
                        'ServiceIds' => [
                            [
                                'AccountId' => '<string>',
                                'Name' => '<string>',
                                'Names' => ['<string>', ...],
                                'Type' => '<string>',
                            ],
                            // ...
                        ],
                    ],
                    // ...
                ],
                // ...
            ],
            'AvailabilityZones' => [
                [
                    'Name' => '<string>',
                ],
                // ...
            ],
            'Duration' => <float>,
            'EntryPoint' => [
                'AccountId' => '<string>',
                'Name' => '<string>',
                'Names' => ['<string>', ...],
                'Type' => '<string>',
            ],
            'ErrorRootCauses' => [
                [
                    'ClientImpacting' => true || false,
                    'Services' => [
                        [
                            'AccountId' => '<string>',
                            'EntityPath' => [
                                [
                                    'Exceptions' => [
                                        [
                                            'Message' => '<string>',
                                            'Name' => '<string>',
                                        ],
                                        // ...
                                    ],
                                    'Name' => '<string>',
                                    'Remote' => true || false,
                                ],
                                // ...
                            ],
                            'Inferred' => true || false,
                            'Name' => '<string>',
                            'Names' => ['<string>', ...],
                            'Type' => '<string>',
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'FaultRootCauses' => [
                [
                    'ClientImpacting' => true || false,
                    'Services' => [
                        [
                            'AccountId' => '<string>',
                            'EntityPath' => [
                                [
                                    'Exceptions' => [
                                        [
                                            'Message' => '<string>',
                                            'Name' => '<string>',
                                        ],
                                        // ...
                                    ],
                                    'Name' => '<string>',
                                    'Remote' => true || false,
                                ],
                                // ...
                            ],
                            'Inferred' => true || false,
                            'Name' => '<string>',
                            'Names' => ['<string>', ...],
                            'Type' => '<string>',
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'HasError' => true || false,
            'HasFault' => true || false,
            'HasThrottle' => true || false,
            'Http' => [
                'ClientIp' => '<string>',
                'HttpMethod' => '<string>',
                'HttpStatus' => <integer>,
                'HttpURL' => '<string>',
                'UserAgent' => '<string>',
            ],
            'Id' => '<string>',
            'InstanceIds' => [
                [
                    'Id' => '<string>',
                ],
                // ...
            ],
            'IsPartial' => true || false,
            'MatchedEventTime' => <DateTime>,
            'ResourceARNs' => [
                [
                    'ARN' => '<string>',
                ],
                // ...
            ],
            'ResponseTime' => <float>,
            'ResponseTimeRootCauses' => [
                [
                    'ClientImpacting' => true || false,
                    'Services' => [
                        [
                            'AccountId' => '<string>',
                            'EntityPath' => [
                                [
                                    'Coverage' => <float>,
                                    'Name' => '<string>',
                                    'Remote' => true || false,
                                ],
                                // ...
                            ],
                            'Inferred' => true || false,
                            'Name' => '<string>',
                            'Names' => ['<string>', ...],
                            'Type' => '<string>',
                        ],
                        // ...
                    ],
                ],
                // ...
            ],
            'Revision' => <integer>,
            'ServiceIds' => [
                [
                    'AccountId' => '<string>',
                    'Name' => '<string>',
                    'Names' => ['<string>', ...],
                    'Type' => '<string>',
                ],
                // ...
            ],
            'Users' => [
                [
                    'ServiceIds' => [
                        [
                            'AccountId' => '<string>',
                            'Name' => '<string>',
                            'Names' => ['<string>', ...],
                            'Type' => '<string>',
                        ],
                        // ...
                    ],
                    'UserName' => '<string>',
                ],
                // ...
            ],
        ],
        // ...
    ],
    'TracesProcessedCount' => <integer>,
]

Result Details

Members

ApproximateTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The start time of this page of results.

NextToken

Type: string

If the requested time frame contained more than one page of results, you can use this token to retrieve the next page. The first page contains the most recent results, closest to the end of the time frame.

TraceSummaries

Type: Array of TraceSummary structures

Trace IDs and annotations for traces that were found in the specified time frame.

TracesProcessedCount

Type: long (int|float)

The total number of traces processed, including traces that did not match the specified filter expression.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

ListResourcePolicies

$result = $client->listResourcePolicies([/* ... */]);
$promise = $client->listResourcePoliciesAsync([/* ... */]);

Returns the list of resource policies in the target Amazon Web Services account.

Parameter Syntax

$result = $client->listResourcePolicies([
    'NextToken' => '<string>',
]);

Parameter Details

Members

NextToken

Type: string

Not currently supported.

Result Syntax

[
    'NextToken' => '<string>',
    'ResourcePolicies' => [
        [
            'LastUpdatedTime' => <DateTime>,
            'PolicyDocument' => '<string>',
            'PolicyName' => '<string>',
            'PolicyRevisionId' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

Pagination token. Not currently supported.

ResourcePolicies

Type: Array of ResourcePolicy structures

The list of resource policies in the target Amazon Web Services account.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Returns a list of tags that are applied to the specified Amazon Web Services X-Ray group or sampling rule.

Parameter Syntax

$result = $client->listTagsForResource([
    'NextToken' => '<string>',
    'ResourceARN' => '<string>', // REQUIRED
]);

Parameter Details

Members

NextToken

Type: string

A pagination token. If multiple pages of results are returned, use the NextToken value returned with the current page of results as the value of this parameter to get the next page of results.

ResourceARN

Required: Yes
Type: string

The Amazon Resource Number (ARN) of an X-Ray group or sampling rule.

Result Syntax

[
    'NextToken' => '<string>',
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

A pagination token. If multiple pages of results are returned, use the NextToken value returned with the current page of results to get the next page of results.

Tags

Type: Array of Tag structures

A list of tags, as key and value pairs, that is associated with the specified X-Ray group or sampling rule.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.
ResourceNotFoundException:
The resource was not found. Verify that the name or Amazon Resource Name (ARN) of the resource is correct.

PutEncryptionConfig

$result = $client->putEncryptionConfig([/* ... */]);
$promise = $client->putEncryptionConfigAsync([/* ... */]);

Updates the encryption configuration for X-Ray data.

Parameter Syntax

$result = $client->putEncryptionConfig([
    'KeyId' => '<string>',
    'Type' => 'NONE|KMS', // REQUIRED
]);

Parameter Details

Members

KeyId

Type: string

An Amazon Web Services KMS key in one of the following formats:

Alias - The name of the key. For example, alias/MyKey.
Key ID - The KMS key ID of the key. For example, ae4aa6d49-a4d8-9df9-a475-4ff6d7898456. Amazon Web Services X-Ray does not support asymmetric KMS keys.
ARN - The full Amazon Resource Name of the key ID or alias. For example, arn:aws:kms:us-east-2:123456789012:key/ae4aa6d49-a4d8-9df9-a475-4ff6d7898456. Use this format to specify a key in a different account.

Omit this key if you set Type to NONE.

Type

Required: Yes
Type: string

The type of encryption. Set to KMS to use your own key for encryption. Set to NONE for default encryption.

Result Syntax

[
    'EncryptionConfig' => [
        'KeyId' => '<string>',
        'Status' => 'UPDATING|ACTIVE',
        'Type' => 'NONE|KMS',
    ],
]

Result Details

Members

EncryptionConfig

Type: EncryptionConfig structure

The new encryption configuration.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

PutResourcePolicy

$result = $client->putResourcePolicy([/* ... */]);
$promise = $client->putResourcePolicyAsync([/* ... */]);

Sets the resource policy to grant one or more Amazon Web Services services and accounts permissions to access X-Ray. Each resource policy will be associated with a specific Amazon Web Services account. Each Amazon Web Services account can have a maximum of 5 resource policies, and each policy name must be unique within that account. The maximum size of each resource policy is 5KB.

Parameter Syntax

$result = $client->putResourcePolicy([
    'BypassPolicyLockoutCheck' => true || false,
    'PolicyDocument' => '<string>', // REQUIRED
    'PolicyName' => '<string>', // REQUIRED
    'PolicyRevisionId' => '<string>',
]);

Parameter Details

Members

BypassPolicyLockoutCheck

Type: boolean

A flag to indicate whether to bypass the resource policy lockout safety check.

Setting this value to true increases the risk that the policy becomes unmanageable. Do not set this value to true indiscriminately.

Use this parameter only when you include a policy in the request and you intend to prevent the principal that is making the request from making a subsequent PutResourcePolicy request.

The default value is false.

PolicyDocument

Required: Yes
Type: string

The resource policy document, which can be up to 5kb in size.

PolicyName

Required: Yes
Type: string

The name of the resource policy. Must be unique within a specific Amazon Web Services account.

PolicyRevisionId

Type: string

Specifies a specific policy revision, to ensure an atomic create operation. By default the resource policy is created if it does not exist, or updated with an incremented revision id. The revision id is unique to each policy in the account.

If the policy revision id does not match the latest revision id, the operation will fail with an InvalidPolicyRevisionIdException exception. You can also provide a PolicyRevisionId of 0. In this case, the operation will fail with an InvalidPolicyRevisionIdException exception if a resource policy with the same name already exists.

Result Syntax

[
    'ResourcePolicy' => [
        'LastUpdatedTime' => <DateTime>,
        'PolicyDocument' => '<string>',
        'PolicyName' => '<string>',
        'PolicyRevisionId' => '<string>',
    ],
]

Result Details

Members

ResourcePolicy

Type: ResourcePolicy structure

The resource policy document, as provided in the PutResourcePolicyRequest.

Errors

MalformedPolicyDocumentException:
Invalid policy document provided in request.
LockoutPreventionException:
The provided resource policy would prevent the caller of this request from calling PutResourcePolicy in the future.
InvalidPolicyRevisionIdException:
A policy revision id was provided which does not match the latest policy revision. This exception is also if a policy revision id of 0 is provided via PutResourcePolicy and a policy with the same name already exists.
PolicySizeLimitExceededException:
Exceeded the maximum size for a resource policy.
PolicyCountLimitExceededException:
Exceeded the maximum number of resource policies for a target Amazon Web Services account.
ThrottledException:
The request exceeds the maximum number of requests per second.

PutTelemetryRecords

$result = $client->putTelemetryRecords([/* ... */]);
$promise = $client->putTelemetryRecordsAsync([/* ... */]);

Used by the Amazon Web Services X-Ray daemon to upload telemetry.

Parameter Syntax

$result = $client->putTelemetryRecords([
    'EC2InstanceId' => '<string>',
    'Hostname' => '<string>',
    'ResourceARN' => '<string>',
    'TelemetryRecords' => [ // REQUIRED
        [
            'BackendConnectionErrors' => [
                'ConnectionRefusedCount' => <integer>,
                'HTTPCode4XXCount' => <integer>,
                'HTTPCode5XXCount' => <integer>,
                'OtherCount' => <integer>,
                'TimeoutCount' => <integer>,
                'UnknownHostCount' => <integer>,
            ],
            'SegmentsReceivedCount' => <integer>,
            'SegmentsRejectedCount' => <integer>,
            'SegmentsSentCount' => <integer>,
            'SegmentsSpilloverCount' => <integer>,
            'Timestamp' => <integer || string || DateTime>, // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

EC2InstanceId

Type: string

Hostname

Type: string

ResourceARN

Type: string

TelemetryRecords

Required: Yes
Type: Array of TelemetryRecord structures

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

PutTraceSegments

$result = $client->putTraceSegments([/* ... */]);
$promise = $client->putTraceSegmentsAsync([/* ... */]);

Uploads segment documents to Amazon Web Services X-Ray. The X-Ray SDK generates segment documents and sends them to the X-Ray daemon, which uploads them in batches. 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 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. This 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.

Parameter Syntax

$result = $client->putTraceSegments([
    'TraceSegmentDocuments' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

TraceSegmentDocuments

Required: Yes
Type: Array of strings

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

Result Syntax

[
    'UnprocessedTraceSegments' => [
        [
            'ErrorCode' => '<string>',
            'Id' => '<string>',
            'Message' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

UnprocessedTraceSegments

Type: Array of UnprocessedTraceSegment structures

Segments that failed processing.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Applies tags to an existing Amazon Web Services X-Ray group or sampling rule.

Parameter Syntax

$result = $client->tagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'Tags' => [ // REQUIRED
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Members

ResourceARN

Required: Yes
Type: string

The Amazon Resource Number (ARN) of an X-Ray group or sampling rule.

Tags

Required: Yes
Type: Array of Tag structures

A map that contains one or more tag keys and tag values to attach to an X-Ray group or sampling rule. For more information about ways to use tags, see Tagging Amazon Web Services resources in the Amazon Web Services General Reference.

The following restrictions apply to tags:

Maximum number of user-applied tags per resource: 50
Maximum tag key length: 128 Unicode characters
Maximum tag value length: 256 Unicode characters
Valid values for key and value: a-z, A-Z, 0-9, space, and the following characters: _ . : / = + - and @
Tag keys and values are case sensitive.
Don't use aws: as a prefix for keys; it's reserved for Amazon Web Services use. You cannot edit or delete system tags.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.
ResourceNotFoundException:
The resource was not found. Verify that the name or Amazon Resource Name (ARN) of the resource is correct.
TooManyTagsException:
You have exceeded the maximum number of tags you can apply to this resource.

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes tags from an Amazon Web Services X-Ray group or sampling rule. You cannot edit or delete system tags (those with an aws: prefix).

Parameter Syntax

$result = $client->untagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'TagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

ResourceARN

Required: Yes
Type: string

The Amazon Resource Number (ARN) of an X-Ray group or sampling rule.

TagKeys

Required: Yes
Type: Array of strings

Keys for one or more tags that you want to remove from an X-Ray group or sampling rule.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.
ResourceNotFoundException:
The resource was not found. Verify that the name or Amazon Resource Name (ARN) of the resource is correct.

UpdateGroup

$result = $client->updateGroup([/* ... */]);
$promise = $client->updateGroupAsync([/* ... */]);

Updates a group resource.

Parameter Syntax

$result = $client->updateGroup([
    'FilterExpression' => '<string>',
    'GroupARN' => '<string>',
    'GroupName' => '<string>',
    'InsightsConfiguration' => [
        'InsightsEnabled' => true || false,
        'NotificationsEnabled' => true || false,
    ],
]);

Parameter Details

Members

FilterExpression

Type: string

The updated filter expression defining criteria by which to group traces.

GroupARN

Type: string

The ARN that was generated upon creation.

GroupName

Type: string

The case-sensitive name of the group.

InsightsConfiguration

Type: InsightsConfiguration structure

The structure containing configurations related to insights.

The InsightsEnabled boolean can be set to true to enable insights for the group or false to disable insights for the group.
The NotificationsEnabled boolean can be set to true to enable insights notifications for the group. Notifications can only be enabled on a group with InsightsEnabled set to true.

Result Syntax

[
    'Group' => [
        'FilterExpression' => '<string>',
        'GroupARN' => '<string>',
        'GroupName' => '<string>',
        'InsightsConfiguration' => [
            'InsightsEnabled' => true || false,
            'NotificationsEnabled' => true || false,
        ],
    ],
]

Result Details

Members

Group

Type: Group structure

The group that was updated. Contains the name of the group that was updated, the ARN of the group that was updated, the updated filter expression, and the updated insight configuration assigned to the group.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

UpdateSamplingRule

$result = $client->updateSamplingRule([/* ... */]);
$promise = $client->updateSamplingRuleAsync([/* ... */]);

Modifies a sampling rule's configuration.

Parameter Syntax

$result = $client->updateSamplingRule([
    'SamplingRuleUpdate' => [ // REQUIRED
        'Attributes' => ['<string>', ...],
        'FixedRate' => <float>,
        'HTTPMethod' => '<string>',
        'Host' => '<string>',
        'Priority' => <integer>,
        'ReservoirSize' => <integer>,
        'ResourceARN' => '<string>',
        'RuleARN' => '<string>',
        'RuleName' => '<string>',
        'ServiceName' => '<string>',
        'ServiceType' => '<string>',
        'URLPath' => '<string>',
    ],
]);

Parameter Details

Members

SamplingRuleUpdate

Required: Yes
Type: SamplingRuleUpdate structure

The rule and fields to change.

Result Syntax

[
    'SamplingRuleRecord' => [
        'CreatedAt' => <DateTime>,
        'ModifiedAt' => <DateTime>,
        'SamplingRule' => [
            'Attributes' => ['<string>', ...],
            'FixedRate' => <float>,
            'HTTPMethod' => '<string>',
            'Host' => '<string>',
            'Priority' => <integer>,
            'ReservoirSize' => <integer>,
            'ResourceARN' => '<string>',
            'RuleARN' => '<string>',
            'RuleName' => '<string>',
            'ServiceName' => '<string>',
            'ServiceType' => '<string>',
            'URLPath' => '<string>',
            'Version' => <integer>,
        ],
    ],
]

Result Details

Members

SamplingRuleRecord

Type: SamplingRuleRecord structure

The updated rule definition and metadata.

Errors

InvalidRequestException:
The request is missing required parameters or has invalid parameters.
ThrottledException:
The request exceeds the maximum number of requests per second.

Shapes

Alias

Description

An alias for an edge.

Members

Name

Type: string

The canonical name of the alias.

Names

Type: Array of strings

A list of names for the alias, including the canonical name.

Type

Type: string

The type of the alias.

AnnotationValue

Description

Value of a segment annotation. Has one of three value types: Number, Boolean, or String.

Members

BooleanValue

Type: boolean

Value for a Boolean annotation.

NumberValue

Type: double

Value for a Number annotation.

StringValue

Type: string

Value for a String annotation.

AnomalousService

Description

The service within the service graph that has anomalously high fault rates.

Members

ServiceId

Type: ServiceId structure

AvailabilityZoneDetail

Description

A list of Availability Zones corresponding to the segments in a trace.

Members

Name

Type: string

The name of a corresponding Availability Zone.

BackendConnectionErrors

Description

Members

ConnectionRefusedCount

Type: int

HTTPCode4XXCount

Type: int

HTTPCode5XXCount

Type: int

OtherCount

Type: int

TimeoutCount

Type: int

UnknownHostCount

Type: int

Edge

Description

Information about a connection between two services. An edge can be a synchronous connection, such as typical call between client and service, or an asynchronous link, such as a Lambda function which retrieves an event from an SNS queue.

Members

Aliases

Type: Array of Alias structures

Aliases for the edge.

EdgeType

Type: string

Describes an asynchronous connection, with a value of link.

EndTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The end time of the last segment on the edge.

ReceivedEventAgeHistogram

Type: Array of HistogramEntry structures

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.

ReferenceId

Type: int

Identifier of the edge. Unique within a service map.

ResponseTimeHistogram

Type: Array of HistogramEntry structures

A histogram that maps the spread of client response times on an edge. Only populated for synchronous edges.

StartTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The start time of the first segment on the edge.

SummaryStatistics

Type: EdgeStatistics structure

Response statistics for segments on the edge.

EdgeStatistics

Description

Response statistics for an edge.

Members

ErrorStatistics

Type: ErrorStatistics structure

Information about requests that failed with a 4xx Client Error status code.

FaultStatistics

Type: FaultStatistics structure

Information about requests that failed with a 5xx Server Error status code.

OkCount

Type: long (int|float)

The number of requests that completed with a 2xx Success status code.

TotalCount

Type: long (int|float)

The total number of completed requests.

TotalResponseTime

Type: double

The aggregate response time of completed requests.

EncryptionConfig

Description

A configuration document that specifies encryption configuration settings.

Members

KeyId

Type: string

The ID of the KMS key used for encryption, if applicable.

Status

Type: string

The encryption status. While the status is UPDATING, X-Ray may encrypt data with a combination of the new and old settings.

Type

Type: string

The type of encryption. Set to KMS for encryption with KMS keys. Set to NONE for default encryption.

ErrorRootCause

Description

The root cause of a trace summary error.

Members

ClientImpacting

Type: boolean

A flag that denotes that the root cause impacts the trace client.

Services

Type: Array of ErrorRootCauseService structures

A list of services corresponding to an error. A service identifies a segment and it contains a name, account ID, type, and inferred flag.

ErrorRootCauseEntity

Description

A collection of segments and corresponding subsegments associated to a trace summary error.

Members

Exceptions

Type: Array of RootCauseException structures

The types and messages of the exceptions.

Name

Type: string

The name of the entity.

Remote

Type: boolean

A flag that denotes a remote subsegment.

ErrorRootCauseService

Description

A collection of fields identifying the services in a trace summary error.

Members

AccountId

Type: string

The account ID associated to the service.

EntityPath

Type: Array of ErrorRootCauseEntity structures

The path of root cause entities found on the service.

Inferred

Type: boolean

A Boolean value indicating if the service is inferred from the trace.

Name

Type: string

The service name.

Names

Type: Array of strings

A collection of associated service names.

Type

Type: string

The type associated to the service.

ErrorStatistics

Description

Information about requests that failed with a 4xx Client Error status code.

Members

OtherCount

Type: long (int|float)

The number of requests that failed with untracked 4xx Client Error status codes.

ThrottleCount

Type: long (int|float)

The number of requests that failed with a 419 throttling status code.

TotalCount

Type: long (int|float)

The total number of requests that failed with a 4xx Client Error status code.

FaultRootCause

Description

The root cause information for a trace summary fault.

Members

ClientImpacting

Type: boolean

A flag that denotes that the root cause impacts the trace client.

Services

Type: Array of FaultRootCauseService structures

A list of corresponding services. A service identifies a segment and it contains a name, account ID, type, and inferred flag.

FaultRootCauseEntity

Description

A collection of segments and corresponding subsegments associated to a trace summary fault error.

Members

Exceptions

Type: Array of RootCauseException structures

The types and messages of the exceptions.

Name

Type: string

The name of the entity.

Remote

Type: boolean

A flag that denotes a remote subsegment.

FaultRootCauseService

Description

A collection of fields identifying the services in a trace summary fault.

Members

AccountId

Type: string

The account ID associated to the service.

EntityPath

Type: Array of FaultRootCauseEntity structures

The path of root cause entities found on the service.

Inferred

Type: boolean

A Boolean value indicating if the service is inferred from the trace.

Name

Type: string

The service name.

Names

Type: Array of strings

A collection of associated service names.

Type

Type: string

The type associated to the service.

FaultStatistics

Description

Information about requests that failed with a 5xx Server Error status code.

Members

OtherCount

Type: long (int|float)

The number of requests that failed with untracked 5xx Server Error status codes.

TotalCount

Type: long (int|float)

The total number of requests that failed with a 5xx Server Error status code.

ForecastStatistics

Description

The predicted high and low fault count. This is used to determine if a service has become anomalous and if an insight should be created.

Members

FaultCountHigh

Type: long (int|float)

The upper limit of fault counts for a service.

FaultCountLow

Type: long (int|float)

The lower limit of fault counts for a service.

Group

Description

Details and metadata for a group.

Members

FilterExpression

Type: string

The filter expression defining the parameters to include traces.

GroupARN

Type: string

The Amazon Resource Name (ARN) of the group generated based on the GroupName.

GroupName

Type: string

The unique case-sensitive name of the group.

InsightsConfiguration

Type: InsightsConfiguration structure

The structure containing configurations related to insights.

The InsightsEnabled boolean can be set to true to enable insights for the group or false to disable insights for the group.
The NotificationsEnabled boolean can be set to true to enable insights notifications through Amazon EventBridge for the group.

GroupSummary

Description

Details for a group without metadata.

Members

FilterExpression

Type: string

The filter expression defining the parameters to include traces.

GroupARN

Type: string

The ARN of the group generated based on the GroupName.

GroupName

Type: string

The unique case-sensitive name of the group.

InsightsConfiguration

Type: InsightsConfiguration structure

The structure containing configurations related to insights.

The InsightsEnabled boolean can be set to true to enable insights for the group or false to disable insights for the group.
The NotificationsEnabled boolean can be set to true to enable insights notifications. Notifications can only be enabled on a group with InsightsEnabled set to true.

HistogramEntry

Description

An entry in a histogram for a statistic. A histogram maps the range of observed values on the X axis, and the prevalence of each value on the Y axis.

Members

Count

Type: int

The prevalence of the entry.

Value

Type: double

The value of the entry.

Http

Description

Information about an HTTP request.

Members

ClientIp

Type: string

The IP address of the requestor.

HttpMethod

Type: string

The request method.

HttpStatus

Type: int

The response status.

HttpURL

Type: string

The request URL.

UserAgent

Type: string

The request's user agent string.

Insight

Description

When fault rates go outside of the expected range, X-Ray creates an insight. Insights tracks emergent issues within your applications.

Members

Categories

Type: Array of strings

The categories that label and describe the type of insight.

ClientRequestImpactStatistics

Type: RequestImpactStatistics structure

The impact statistics of the client side service. This includes the number of requests to the client service and whether the requests were faults or okay.

EndTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, at which the insight ended.

GroupARN

Type: string

The Amazon Resource Name (ARN) of the group that the insight belongs to.

GroupName

Type: string

The name of the group that the insight belongs to.

InsightId

Type: string

The insights unique identifier.

RootCauseServiceId

Type: ServiceId structure

RootCauseServiceRequestImpactStatistics

Type: RequestImpactStatistics structure

The impact statistics of the root cause service. This includes the number of requests to the client service and whether the requests were faults or okay.

StartTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, at which the insight began.

State

Type: string

The current state of the insight.

Summary

Type: string

A brief description of the insight.

TopAnomalousServices

Type: Array of AnomalousService structures

The service within the insight that is most impacted by the incident.

InsightEvent

Description

X-Ray reevaluates insights periodically until they are resolved, and records each intermediate state in an event. You can review incident events in the Impact Timeline on the Inspect page in the X-Ray console.

Members

ClientRequestImpactStatistics

Type: RequestImpactStatistics structure

The impact statistics of the client side service. This includes the number of requests to the client service and whether the requests were faults or okay.

EventTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, at which the event was recorded.

RootCauseServiceRequestImpactStatistics

Type: RequestImpactStatistics structure

The impact statistics of the root cause service. This includes the number of requests to the client service and whether the requests were faults or okay.

Summary

Type: string

A brief description of the event.

TopAnomalousServices

Type: Array of AnomalousService structures

The service during the event that is most impacted by the incident.

InsightImpactGraphEdge

Description

The connection between two service in an insight impact graph.

Members

ReferenceId

Type: int

Identifier of the edge. Unique within a service map.

InsightImpactGraphService

Description

Information about an application that processed requests, users that made requests, or downstream services, resources, and applications that an application used.

Members

AccountId

Type: string

Identifier of the Amazon Web Services account in which the service runs.

Edges

Type: Array of InsightImpactGraphEdge structures

Connections to downstream services.

Name

Type: string

The canonical name of the service.

Names

Type: Array of strings

A list of names for the service, including the canonical name.

ReferenceId

Type: int

Identifier for the service. Unique within the service map.

Type

Type: string

Identifier for the service. Unique within the service map.

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.
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.
remote - A downstream service of indeterminate type.

InsightSummary

Description

Information that describes an insight.

Members

Categories

Type: Array of strings

Categories The categories that label and describe the type of insight.

ClientRequestImpactStatistics

Type: RequestImpactStatistics structure

The impact statistics of the client side service. This includes the number of requests to the client service and whether the requests were faults or okay.

EndTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, at which the insight ended.

GroupARN

Type: string

The Amazon Resource Name (ARN) of the group that the insight belongs to.

GroupName

Type: string

The name of the group that the insight belongs to.

InsightId

Type: string

The insights unique identifier.

LastUpdateTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, that the insight was last updated.

RootCauseServiceId

Type: ServiceId structure

RootCauseServiceRequestImpactStatistics

Type: RequestImpactStatistics structure

The impact statistics of the root cause service. This includes the number of requests to the client service and whether the requests were faults or okay.

StartTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time, in Unix seconds, at which the insight began.

State

Type: string

The current state of the insight.

Summary

Type: string

A brief description of the insight.

TopAnomalousServices

Type: Array of AnomalousService structures

The service within the insight that is most impacted by the incident.

InsightsConfiguration

Description

The structure containing configurations related to insights.

Members

InsightsEnabled

Type: boolean

Set the InsightsEnabled value to true to enable insights or false to disable insights.

NotificationsEnabled

Type: boolean

Set the NotificationsEnabled value to true to enable insights notifications. Notifications can only be enabled on a group with InsightsEnabled set to true.

InstanceIdDetail

Description

A list of EC2 instance IDs corresponding to the segments in a trace.

Members

Id

Type: string

Type: long (int|float)

The number of requests that have resulted in a fault,

OkCount

Type: long (int|float)

The number of successful requests.

TotalCount

Type: long (int|float)

The total number of requests to the service.

ResourceARNDetail

Description

A list of resources ARNs corresponding to the segments in a trace.

Members

ARN

Type: string

The ARN of a corresponding resource.

ResourceNotFoundException

Description

The resource was not found. Verify that the name or Amazon Resource Name (ARN) of the resource is correct.

Members

Message

Type: string

ResourceName

Type: string

ResourcePolicy

Description

A resource policy grants one or more Amazon Web Services services and accounts permissions to access X-Ray. Each resource policy is associated with a specific Amazon Web Services account.

Members

LastUpdatedTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

When the policy was last updated, in Unix time seconds.

PolicyDocument

Type: string

The resource policy document, which can be up to 5kb in size.

PolicyName

Type: string

The name of the resource policy. Must be unique within a specific Amazon Web Services account.

PolicyRevisionId

Type: string

Returns the current policy revision id for this policy name.

ResponseTimeRootCause

Description

The root cause information for a response time warning.

Members

ClientImpacting

Type: boolean

A flag that denotes that the root cause impacts the trace client.

Services

Type: Array of ResponseTimeRootCauseService structures

A list of corresponding services. A service identifies a segment and contains a name, account ID, type, and inferred flag.

ResponseTimeRootCauseEntity

Description

A collection of segments and corresponding subsegments associated to a response time warning.

Members

Coverage

Type: double

The type and messages of the exceptions.

Name

Type: string

The name of the entity.

Remote

Type: boolean

A flag that denotes a remote subsegment.

ResponseTimeRootCauseService

Description

A collection of fields identifying the service in a response time warning.

Members

AccountId

Type: string

The account ID associated to the service.

EntityPath

Type: Array of ResponseTimeRootCauseEntity structures

The path of root cause entities found on the service.

Inferred

Type: boolean

A Boolean value indicating if the service is inferred from the trace.

Name

Type: string

The service name.

Names

Type: Array of strings

A collection of associated service names.

Type

Type: string

The type associated to the service.

RootCauseException

Description

The exception associated with a root cause.

Members

Message

Type: string

The message of the exception.

Name

Type: string

The name of the exception.

RuleLimitExceededException

Description

You have reached the maximum number of sampling rules.

Members

Message

Type: string

SamplingRule

Description

A sampling rule that services use to decide whether to instrument a request. Rule fields can match properties of the service, or properties of a request. The service can ignore rules that don't match its properties.

Members

Attributes

Type: Associative array of custom strings keys (AttributeKey) to strings

Matches attributes derived from the request.

FixedRate

Required: Yes
Type: double

The percentage of matching requests to instrument, after the reservoir is exhausted.

HTTPMethod

Required: Yes
Type: string

Matches the HTTP method of a request.

Host

Required: Yes
Type: string

Matches the hostname from a request URL.

Priority

Required: Yes
Type: int

The priority of the sampling rule.

ReservoirSize

Required: Yes
Type: int

A fixed number of matching requests to instrument per second, prior to applying the fixed rate. The reservoir is not used directly by services, but applies to all services using the rule collectively.

ResourceARN

Required: Yes
Type: string

Matches the ARN of the Amazon Web Services resource on which the service runs.

RuleARN

Type: string

The ARN of the sampling rule. Specify a rule by either name or ARN, but not both.

RuleName

Type: string

The name of the sampling rule. Specify a rule by either name or ARN, but not both.

ServiceName

Required: Yes
Type: string

Matches the name that the service uses to identify itself in segments.

ServiceType

Required: Yes
Type: string

Matches the origin that the service uses to identify its type in segments.

URLPath

Required: Yes
Type: string

Matches the path from a request URL.

Version

Required: Yes
Type: int

The version of the sampling rule format (1).

SamplingRuleRecord

Description

A SamplingRule and its metadata.

Members

CreatedAt

Type: timestamp (string|DateTime or anything parsable by strtotime)

When the rule was created.

ModifiedAt

Type: timestamp (string|DateTime or anything parsable by strtotime)

When the rule was last modified.

SamplingRule

Type: SamplingRule structure

The sampling rule.

SamplingRuleUpdate

Description

A document specifying changes to a sampling rule's configuration.

Members

Attributes

Type: Associative array of custom strings keys (AttributeKey) to strings

Matches attributes derived from the request.

FixedRate

Type: double

The percentage of matching requests to instrument, after the reservoir is exhausted.

HTTPMethod

Type: string

Matches the HTTP method of a request.

Host

Type: string

Matches the hostname from a request URL.

Priority

Type: int

The priority of the sampling rule.

ReservoirSize

Type: int

ResourceARN

Type: string

Matches the ARN of the Amazon Web Services resource on which the service runs.

RuleARN

Type: string

The ARN of the sampling rule. Specify a rule by either name or ARN, but not both.

RuleName

Type: string

The name of the sampling rule. Specify a rule by either name or ARN, but not both.

ServiceName

Type: string

Matches the name that the service uses to identify itself in segments.

ServiceType

Type: string

Matches the origin that the service uses to identify its type in segments.

URLPath

Type: string

Matches the path from a request URL.

SamplingStatisticSummary

Description

Aggregated request sampling data for a sampling rule across all services for a 10-second window.

Members

BorrowCount

Type: int

The number of requests recorded with borrowed reservoir quota.

RequestCount

Type: int

The number of requests that matched the rule.

RuleName

Type: string

The name of the sampling rule.

SampledCount

Type: int

The number of requests recorded.

Timestamp

Type: timestamp (string|DateTime or anything parsable by strtotime)

The start time of the reporting window.

SamplingStatisticsDocument

Description

Request sampling results for a single rule from a service. Results are for the last 10 seconds unless the service has been assigned a longer reporting interval after a previous call to GetSamplingTargets.

Members

BorrowCount

Type: int

The number of requests recorded with borrowed reservoir quota.

ClientID

Required: Yes
Type: string

A unique identifier for the service in hexadecimal.

RequestCount

Required: Yes
Type: int

The number of requests that matched the rule.

RuleName

Required: Yes
Type: string

The name of the sampling rule.

SampledCount

Required: Yes
Type: int

The number of requests recorded.

Timestamp

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The current time.

SamplingStrategy

Description

The name and value of a sampling rule to apply to a trace summary.

Members

Name

Type: string

The name of a sampling rule.

Value

Type: double

The value of a sampling rule.

SamplingTargetDocument

Description

Temporary changes to a sampling rule configuration. To meet the global sampling target for a rule, X-Ray calculates a new reservoir for each service based on the recent sampling results of all services that called GetSamplingTargets.

Members

FixedRate

Type: double

The percentage of matching requests to instrument, after the reservoir is exhausted.

Interval

Type: int

The number of seconds for the service to wait before getting sampling targets again.

ReservoirQuota

Type: int

The number of requests per second that X-Ray allocated for this service.

ReservoirQuotaTTL

Type: timestamp (string|DateTime or anything parsable by strtotime)

When the reservoir quota expires.

RuleName

Type: string

The name of the sampling rule.

Segment

Description

A segment from a trace that has been ingested by the X-Ray service. The segment can be compiled from documents uploaded with PutTraceSegments, or an inferred segment for a downstream service, generated from a subsegment sent by the service that called it.

For the full segment document schema, see Amazon Web Services X-Ray Segment Documents in the Amazon Web Services X-Ray Developer Guide.

Members

Document

Type: string

The segment document.

Id

Type: string

The segment's ID.

Service

Description

Information about an application that processed requests, users that made requests, or downstream services, resources, and applications that an application used.

Members

AccountId

Type: string

Identifier of the Amazon Web Services account in which the service runs.

DurationHistogram

Type: Array of HistogramEntry structures

A histogram that maps the spread of service durations.

Edges

Type: Array of Edge structures

Connections to downstream services.

EndTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The end time of the last segment that the service generated.

Name

Type: string

The canonical name of the service.

Names

Type: Array of strings

A list of names for the service, including the canonical name.

ReferenceId

Type: int

Identifier for the service. Unique within the service map.

ResponseTimeHistogram

Type: Array of HistogramEntry structures

A histogram that maps the spread of service response times.

Root

Type: boolean

Indicates that the service was the first service to process a request.

StartTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The start time of the first segment that the service generated.

State

Type: string

The service's state.

SummaryStatistics

Type: ServiceStatistics structure

Aggregated statistics for the service.

Type

Type: string

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.

ServiceId

Description

Members

AccountId

Type: string

Name

Type: string

Names

Type: Array of strings

Type

Type: string

ServiceStatistics

Description

Response statistics for a service.

Members

ErrorStatistics

Type: ErrorStatistics structure

Information about requests that failed with a 4xx Client Error status code.

FaultStatistics

Type: FaultStatistics structure

Information about requests that failed with a 5xx Server Error status code.

OkCount

Type: long (int|float)

The number of requests that completed with a 2xx Success status code.

TotalCount

Type: long (int|float)

The total number of completed requests.

TotalResponseTime

Type: double

The aggregate response time of completed requests.

Tag

Description

A map that contains tag keys and tag values to attach to an Amazon Web Services X-Ray group or sampling rule. For more information about ways to use tags, see Tagging Amazon Web Services resources in the Amazon Web Services General Reference.

The following restrictions apply to tags:

Maximum number of user-applied tags per resource: 50
Tag keys and values are case sensitive.
Don't use aws: as a prefix for keys; it's reserved for Amazon Web Services use. You cannot edit or delete system tags.

Members

Key

Required: Yes
Type: string

A tag key, such as Stage or Name. A tag key cannot be empty. The key can be a maximum of 128 characters, and can contain only Unicode letters, numbers, or separators, or the following special characters: + - = . _ : /

Value

Required: Yes
Type: string

An optional tag value, such as Production or test-only. The value can be a maximum of 255 characters, and contain only Unicode letters, numbers, or separators, or the following special characters: + - = . _ : /

TelemetryRecord

Description

Members

BackendConnectionErrors

Type: BackendConnectionErrors structure

SegmentsReceivedCount

Type: int

SegmentsRejectedCount

Type: int

SegmentsSentCount

Type: int

SegmentsSpilloverCount

Type: int

Timestamp

Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

ThrottledException

Description

The request exceeds the maximum number of requests per second.

Members

Message

Type: string

TimeSeriesServiceStatistics

Description

A list of TimeSeriesStatistic structures.

Members

EdgeSummaryStatistics

Type: EdgeStatistics structure

Response statistics for an edge.

ResponseTimeHistogram

Type: Array of HistogramEntry structures

The response time histogram for the selected entities.

ServiceForecastStatistics

Type: ForecastStatistics structure

The forecasted high and low fault count values.

ServiceSummaryStatistics

Type: ServiceStatistics structure

Response statistics for a service.

Timestamp

Type: timestamp (string|DateTime or anything parsable by strtotime)

Timestamp of the window for which statistics are aggregated.

TooManyTagsException

Description

You have exceeded the maximum number of tags you can apply to this resource.

Members

Message

Type: string

ResourceName

Type: string

Trace

Description

A collection of segment documents with matching trace IDs.

Members

Duration

Type: double

The length of time in seconds between the start time of the root segment and the end time of the last segment that completed.

Id

Type: string

The unique identifier for the request that generated the trace's segments and subsegments.

LimitExceeded

Type: boolean

LimitExceeded is set to true when the trace has exceeded the Trace document size limit. For more information about this limit and other X-Ray limits and quotas, see Amazon Web Services X-Ray endpoints and quotas.

Segments

Type: Array of Segment structures

Segment documents for the segments and subsegments that comprise the trace.

TraceSummary

Description

Metadata generated from the segment documents in a trace.

Members

Annotations

Type: Associative array of custom strings keys (AnnotationKey) to ValueWithServiceIds structuress

Annotations from the trace's segment documents.

AvailabilityZones

Type: Array of AvailabilityZoneDetail structures

A list of Availability Zones for any zone corresponding to the trace segments.

Duration

Type: double

The length of time in seconds between the start time of the root segment and the end time of the last segment that completed.

EntryPoint

Type: ServiceId structure

The root of a trace.

ErrorRootCauses

Type: Array of ErrorRootCause structures

A collection of ErrorRootCause structures corresponding to the trace segments.

FaultRootCauses

Type: Array of FaultRootCause structures

A collection of FaultRootCause structures corresponding to the trace segments.

HasError

Type: boolean

The root segment document has a 400 series error.

HasFault

Type: boolean

The root segment document has a 500 series error.

HasThrottle

Type: boolean

One or more of the segment documents has a 429 throttling error.

Http

Type: Http structure

Information about the HTTP request served by the trace.

Id

Type: string

The unique identifier for the request that generated the trace's segments and subsegments.

InstanceIds

Type: Array of InstanceIdDetail structures

A list of EC2 instance IDs for any instance corresponding to the trace segments.

IsPartial

Type: boolean

One or more of the segment documents is in progress.

MatchedEventTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The matched time stamp of a defined event.

ResourceARNs

Type: Array of ResourceARNDetail structures

A list of resource ARNs for any resource corresponding to the trace segments.

ResponseTime

Type: double

The length of time in seconds between the start and end times of the root segment. If the service performs work asynchronously, the response time measures the time before the response is sent to the user, while the duration measures the amount of time before the last traced activity completes.

ResponseTimeRootCauses

Type: Array of ResponseTimeRootCause structures

A collection of ResponseTimeRootCause structures corresponding to the trace segments.

Revision

Type: int

The revision number of a trace.

ServiceIds

Type: Array of ServiceId structures

Service IDs from the trace's segment documents.

Users

Type: Array of TraceUser structures

Users from the trace's segment documents.

TraceUser

Description

Information about a user recorded in segment documents.

Members

ServiceIds

Type: Array of ServiceId structures

Services that the user's request hit.

UserName

Type: string

The user's name.

UnprocessedStatistics

Description

Sampling statistics from a call to GetSamplingTargets that X-Ray could not process.

Members

ErrorCode

Type: string

The error code.

Message

Type: string

The error message.

RuleName

Type: string

The name of the sampling rule.

UnprocessedTraceSegment

Description

Information about a segment that failed processing.

Members

ErrorCode

Type: string

The error that caused processing to fail.

Id

Type: string

The segment's ID.

Message

Type: string

The error message.

ValueWithServiceIds

Description

Information about a segment annotation.

Members

AnnotationValue

Type: AnnotationValue structure

Values of the annotation.

ServiceIds

Type: Array of ServiceId structures

Services to which the annotation applies.

Namespaces

Classes

Interfaces

Traits

Exceptions

Functions

AWS X-Ray 2016-04-12

Operation Summary

Paginators

Operations

BatchGetTraces

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateGroup

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateSamplingRule

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

DeleteGroup

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

DeleteResourcePolicy

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

DeleteSamplingRule

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetEncryptionConfig

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetGroup

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetGroups

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors