Exemples de X-Ray utilisant AWS CLI

Pour obtenir une liste de traces

L'batch-get-tracesexemple suivant récupère une liste de traces spécifiées par un ID. Le suivi complet inclut un document pour chaque segment, compilé à partir de l'ensemble des documents de segments reçus pour le même ID de suivi.

aws xray batch-get-traces \
    --trace-ids 1-5d82881a-0a9126e92a73e971eed891b9

Sortie :

{
    "Traces": [
        {
            "Id": "1-5d82881a-0a9126e92a73e971eed891b9",
            "Duration": 0.232,
            "Segments": [
                {
                    "Id": "54aff5735b12dd28",
                    "Document": "{\"id\":\"54aff5735b12dd28\",\"name\":\"Scorekeep\",\"start_time\":1.568835610432E9,\"end_time\":1.568835610664E9,\"http\":{\"request\":{\"url\":\"http://scorekeep-env-1.m4fg2pfzpv.us-east-2.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"curl/7.59.0\",\"client_ip\":\"52.95.4.28\",\"x_forwarded_for\":true},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"Sample Application-1\",\"deployment_id\":3,\"environment_name\":\"Scorekeep-env-1\"},\"ec2\":{\"availability_zone\":\"us-east-2b\",\"instance_id\":\"i-0e3cf4d2de0f3f37a\"},\"xray\":{\"sdk_version\":\"1.1.0\",\"sdk\":\"X-Ray for Java\"}},\"service\":{\"runtime\":\"OpenJDK 64-Bit Server VM\",\"runtime_version\":\"1.8.0_222\"},\"trace_id\":\"1-5d82881a-0a9126e92a73e971eed891b9\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"2d6900034ccfe558\",\"name\":\"DynamoDB\",\"start_time\":1.568835610658E9,\"end_time\":1.568835610664E9,\"http\":{\"response\":{\"status\":200,\"content_length\":61}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"TPEIDNDUROMLPOV17U4A79555NVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}"
                },
                {
                    "Id": "0f278b6334c34e6b",
                    "Document": "{\"id\":\"0f278b6334c34e6b\",\"name\":\"DynamoDB\",\"start_time\":1.568835610658E9,\"end_time\":1.568835610664E9,\"parent_id\":\"2d6900034ccfe558\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":61}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"TPEIDNDUROMLPOV17U4A79555NVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-5d82881a-0a9126e92a73e971eed891b9\",\"origin\":\"AWS::DynamoDB::Table\"}"
                }
            ]
        }
    ],
    "UnprocessedTraceIds": []
}

Pour plus d'informations, voir Using the AWS X-Ray API with the AWS CLI in the AWS X-Ray Developer Guide.

Pour créer un groupe

L'create-groupexemple suivant crée une ressource de groupe nomméeAdminGroup. Le groupe obtient une expression de filtre qui définit les critères du groupe sous la forme d'un segment lié à un service spécifique à l'origine d'une panne ou d'une erreur.

aws xray create-group \
   --group-name "AdminGroup" \
   --filter-expression "service(\"mydomain.com\") {fault OR error}"

Sortie :

{
    "GroupName": "AdminGroup",
    "GroupARN": "arn:aws:xray:us-west-2:123456789012:group/AdminGroup/123456789",
    "FilterExpression": "service(\"mydomain.com\") {fault OR error}"
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour créer une règle d'échantillonnage

L'create-sampling-ruleexemple suivant crée une règle pour contrôler le comportement d'échantillonnage pour les applications instrumentées. Les règles sont fournies par un JSON fichier. La majorité des champs de règle d'échantillonnage sont obligatoires pour créer la règle.

aws xray create-sampling-rule \
    --cli-input-json file://9000-base-scorekeep.json

Contenu de 9000-base-scorekeep.json :

{
    "SamplingRule": {
        "RuleName": "base-scorekeep",
        "ResourceARN": "*",
        "Priority": 9000,
        "FixedRate": 0.1,
        "ReservoirSize": 5,
        "ServiceName": "Scorekeep",
        "ServiceType": "*",
        "Host": "*",
        "HTTPMethod": "*",
        "URLPath": "*",
        "Version": 1
    }
}

Sortie :

{
    "SamplingRuleRecord": {
        "SamplingRule": {
            "RuleName": "base-scorekeep",
            "RuleARN": "arn:aws:xray:us-west-2:123456789012:sampling-rule/base-scorekeep",
            "ResourceARN": "*",
            "Priority": 9000,
            "FixedRate": 0.1,
            "ReservoirSize": 5,
            "ServiceName": "Scorekeep",
            "ServiceType": "*",
            "Host": "*",
            "HTTPMethod": "*",
            "URLPath": "*",
            "Version": 1,
            "Attributes": {}
        },
        "CreatedAt": 1530574410.0,
        "ModifiedAt": 1530574410.0
    }
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour supprimer un groupe

L'delete-groupexemple suivant supprime la ressource de groupe spécifiée.

aws xray delete-group \
    --group-name "AdminGroup" \
    --group-arn "arn:aws:xray:us-east-2:123456789012:group/AdminGroup/123456789"

Cette commande ne produit aucun résultat.

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour supprimer une règle d'échantillonnage

L'delete-sampling-ruleexemple suivant supprime la règle d'échantillonnage spécifiée. Vous pouvez spécifier le groupe en utilisant soit le nom du groupe, soit le groupeARN.

aws xray delete-sampling-rule \
    --rule-name polling-scorekeep

Sortie :

{
    "SamplingRuleRecord": {
        "SamplingRule": {
            "RuleName": "polling-scorekeep",
            "RuleARN": "arn:aws:xray:us-west-2:123456789012:sampling-rule/polling-scorekeep",
            "ResourceARN": "*",
            "Priority": 5000,
            "FixedRate": 0.003,
            "ReservoirSize": 0,
            "ServiceName": "Scorekeep",
            "ServiceType": "*",
            "Host": "*",
            "HTTPMethod": "GET",
            "URLPath": "/api/state/*",
            "Version": 1,
            "Attributes": {}
        },
        "CreatedAt": 1530574399.0,
        "ModifiedAt": 1530574399.0
    }
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour récupérer la configuration de chiffrement

L'get-encryption-configexemple suivant récupère la configuration de chiffrement actuelle de vos données AWS X-Ray.

aws xray get-encryption-config

Sortie :

{
    "EncryptionConfig": {
        "KeyId": "ae4aa6d49-a4d8-9df9-a475-4ff6d7898456",
        "Status": "ACTIVE",
        "Type": "NONE"
    }
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour récupérer un groupe

L'get-groupexemple suivant affiche les détails de la ressource de groupe spécifiée. Les détails incluent le nom du groupe, le groupe ARN et l'expression de filtre qui définit les critères pour ce groupe. Les groupes peuvent également être récupérés parARN.

aws xray get-group \
    --group-name "AdminGroup"

Sortie :

{
    "Group": [
        {
            "GroupName": "AdminGroup",
            "GroupARN": "arn:aws:xray:us-west-2:123456789012:group/AdminGroup/123456789",
            "FilterExpression": "service(\"mydomain.com\") {fault OR error}"
        }
    ]
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour récupérer tous les groupes

L'exemple suivant affiche les détails de tous les groupes actifs.

aws xray get-groups

Sortie :

{
    "Groups": [
        {
            "GroupName": "AdminGroup",
            "GroupARN": "arn:aws:xray:us-west-2:123456789012:group/AdminGroup/123456789",
            "FilterExpression": "service(\"example.com\") {fault OR error}"
        },
        {
            "GroupName": "SDETGroup",
            "GroupARN": "arn:aws:xray:us-west-2:123456789012:group/SDETGroup/987654321",
            "FilterExpression": "responsetime > 2"
        }
    ]
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour récupérer toutes les règles d'échantillonnage

L'get-sampling-rulesexemple suivant affiche les détails de toutes les règles d'échantillonnage disponibles. :

aws xray get-sampling-rules

Sortie :

{
    "SamplingRuleRecords": [
        {
            "SamplingRule": {
                "RuleName": "Default",
                "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
                "ResourceARN": "*",
                "Priority": 10000,
                "FixedRate": 0.01,
                "ReservoirSize": 0,
                "ServiceName": "*",
                "ServiceType": "*",
                "Host": "*",
                "HTTPMethod": "*",
                "URLPath": "*",
                "Version": 1,
                "Attributes": {}
            },
            "CreatedAt": 0.0,
            "ModifiedAt": 1530558121.0
        },
        {
            "SamplingRule": {
                "RuleName": "base-scorekeep",
                "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
                "ResourceARN": "*",
                "Priority": 9000,
                "FixedRate": 0.1,
                "ReservoirSize": 2,
                "ServiceName": "Scorekeep",
                "ServiceType": "*",
                "Host": "*",
                "HTTPMethod": "*",
                "URLPath": "*",
                "Version": 1,
                "Attributes": {}
            },
            "CreatedAt": 1530573954.0,
            "ModifiedAt": 1530920505.0
        },
        {
            "SamplingRule": {
                "RuleName": "polling-scorekeep",
                "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
                "ResourceARN": "*",
                "Priority": 5000,
                "FixedRate": 0.003,
                "ReservoirSize": 0,
                "ServiceName": "Scorekeep",
                "ServiceType": "*",
                "Host": "*",
                "HTTPMethod": "GET",
                "URLPath": "/api/state/*",
                "Version": 1,
                "Attributes": {}
            },
            "CreatedAt": 1530918163.0,
            "ModifiedAt": 1530918163.0
        }
    ]
}

Pour plus d'informations, consultez la section Using Sampling Rules with the X-Ray API du AWS X-Ray Developer Guide.

Pour demander un quota d'échantillonnage

L'get-sampling-targetsexemple suivant demande un quota d'échantillonnage pour les règles que le service utilise pour échantillonner les demandes. La réponse de AWS X-Ray inclut un quota qui peut être utilisé au lieu d'emprunter au réservoir.

aws xray get-sampling-targets \
    --sampling-statistics-documents '[ { "RuleName": "base-scorekeep", "ClientID": "ABCDEF1234567890ABCDEF10", "Timestamp": "2018-07-07T00:20:06, "RequestCount": 110, "SampledCount": 20, "BorrowCount": 10 }, { "RuleName": "polling-scorekeep", 31, "BorrowCount": 0 } ]'

Sortie :

{
    "SamplingTargetDocuments": [
        {
            "RuleName": "base-scorekeep",
            "FixedRate": 0.1,
            "ReservoirQuota": 2,
            "ReservoirQuotaTTL": 1530923107.0,
            "Interval": 10
        },
        {
            "RuleName": "polling-scorekeep",
            "FixedRate": 0.003,
            "ReservoirQuota": 0,
            "ReservoirQuotaTTL": 1530923107.0,
            "Interval": 10
        }
    ],
    "LastRuleModification": 1530920505.0,
    "UnprocessedStatistics": []
}

Pour plus d'informations, consultez la section Using Sampling Rules with the X-Ray API du AWS X-Ray Developer Guide.

Pour obtenir un graphique de service

L'exemple suivant affiche un document au cours d'une période spécifiée qui décrit les services traitant les demandes entrantes et les services en aval qu'ils appellent en conséquence. :

aws xray get-service-graph \
    --start-time 1568835392.0
    --end-time 1568835446.0

Sortie :

{
    "Services": [
        {
            "ReferenceId": 0,
            "Name": "Scorekeep",
            "Names": [
                "Scorekeep"
            ],
            "Root": true,
            "Type": "AWS::ElasticBeanstalk::Environment",
            "State": "active",
            "StartTime": 1568835392.0,
            "EndTime": 1568835446.0,
            "Edges": [
                {
                    "ReferenceId": 1,
                    "StartTime": 1568835392.0,
                    "EndTime": 1568835446.0,
                    "SummaryStatistics": {
                        "OkCount": 14,
                        "ErrorStatistics": {
                            "ThrottleCount": 0,
                            "OtherCount": 0,
                            "TotalCount": 0
                        },
                        "FaultStatistics": {
                            "OtherCount": 0,
                            "TotalCount": 0
                        },
                        "TotalCount": 14,
                        "TotalResponseTime": 0.13
                    },
                    "ResponseTimeHistogram": [
                        {
                            "Value": 0.008,
                            "Count": 1
                        },
                        {
                            "Value": 0.005,
                            "Count": 7
                        },
                        {
                            "Value": 0.009,
                            "Count": 1
                        },
                        {
                            "Value": 0.021,
                            "Count": 1
                        },
                        {
                            "Value": 0.038,
                            "Count": 1
                        },
                        {
                            "Value": 0.007,
                            "Count": 1
                        },
                        {
                            "Value": 0.006,
                            "Count": 2
                        }
                    ],
                    "Aliases": []
                },

                ... TRUNCATED FOR BREVITY ...

            ]
        }
    ],
    "StartTime": 1568835392.0,
    "EndTime": 1568835446.0,
    "ContainsOldGroupVersions": false
}

Pour plus d'informations, voir Using the AWS X-Ray API with the AWS CLI in the AWS X-Ray Developer Guide.

Pour obtenir un résumé des traces

L'get-trace-summariesexemple suivant récupère IDs les métadonnées des traces disponibles dans un laps de temps spécifié.

aws xray get-trace-summaries \
    --start-time 1568835392.0 \
    --end-time 1568835446.0

Sortie :

[
    "http://scorekeep-env-1.123456789.us-east-2.elasticbeanstalk.com/api/move/VSAE93HF/GSSD2NTB/DP0PCC09",
    "http://scorekeep-env-1.123456789.us-east-2.elasticbeanstalk.com/api/move/GCQ2B35P/FREELDFT/4LRE643M",
    "http://scorekeep-env-1.123456789.us-east-2.elasticbeanstalk.com/api/game/VSAE93HF/GSSD2NTB/starttime/1568835513",
    "http://scorekeep-env-1.123456789.us-east-2.elasticbeanstalk.com/api/move/4MQNA5NN/L99KK2RF/null"
]

Pour plus d'informations, voir Using the AWS X-Ray API with the AWS CLI in the AWS X-Ray Developer Guide.

Pour mettre à jour la configuration de chiffrement

Ce qui suitput-encryption-config``example updates the encryption configuration for AWS X-Ray data to use the default AWS managed KMS key ``aws/xray.

aws xray put-encryption-config \
    --type KMS \
    --key-id alias/aws/xray

Sortie :

{
    "EncryptionConfig": {
        "KeyId": "arn:aws:kms:us-west-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
        "Status": "UPDATING",
        "Type": "KMS"
    }
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour télécharger un segment

L'put-trace-segmentsexemple suivant télécharge des documents segmentés dans AWS X-Ray. Le document de segment est consommé sous forme de liste de documents de JSON segment.

aws xray put-trace-segments \
    --trace-segment-documents "{\"id\":\"20312a0e2b8809f4\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5832862d-a43aafded3334a971fe312db\",\"start_time\":1.479706157195E9,\"end_time\":1.479706157202E9,\"parent_id\":\"79736b962fe3239e\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"SCAU23OM6M8FO38UASGC7785ARVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"

Sortie :

{
    "UnprocessedTraceSegments": []
}

Pour plus d'informations, consultez la section Sending Trace Data to AWS X-Ray du AWS X-Ray Developer Guide.

Pour mettre à jour un groupe

L'update-groupexemple suivant met à jour les critères d'acceptation des traces dans le groupe nomméAdminGroup. Vous pouvez spécifier le groupe souhaité en utilisant soit le nom du groupe, soit le groupeARN.

aws xray update-group \
    --group-name "AdminGroup" \
    --group-arn "arn:aws:xray:us-west-2:123456789012:group/AdminGroup/123456789" \
    --filter-expression "service(\"mydomain.com\") {fault}"

Sortie :

{
    "GroupName": "AdminGroup",
    "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/AdminGroup/123456789",
    "FilterExpression": "service(\"mydomain.com\") {fault}"
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.

Pour mettre à jour une règle d'échantillonnage

L'update-sampling-ruleexemple suivant modifie la configuration d'une règle d'échantillonnage. Les règles sont consommées à partir d'un JSON fichier. Seuls les champs mis à jour sont obligatoires.

aws xray update-sampling-rule \
   --cli-input-json file://1000-default.json

Contenu de 1000-default.json :

{
    "SamplingRuleUpdate": {
        "RuleName": "Default",
        "FixedRate": 0.01,
        "ReservoirSize": 0
    }
}

Sortie :

{
    "SamplingRuleRecords": [
        {
            "SamplingRule": {
                "RuleName": "Default",
                "RuleARN": "arn:aws:xray:us-west-2:123456789012:sampling-rule/Default",
                "ResourceARN": "*",
                "Priority": 10000,
                "FixedRate": 0.01,
                "ReservoirSize": 0,
                "ServiceName": "*",
                "ServiceType": "*",
                "Host": "*",
                "HTTPMethod": "*",
                "URLPath": "*",
                "Version": 1,
                "Attributes": {}
            },
            "CreatedAt": 0.0,
            "ModifiedAt": 1529959993.0
        }
   ]
}

Pour plus d'informations, consultez la section Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec le AWS X-Ray API dans le guide du développeur de AWS X-Ray.