Exemplos do X-Ray usando a AWS CLI - AWS Command Line Interface
Ações

Exemplos do X-Ray usando a AWS CLI

Os exemplos de código a seguir mostram como realizar ações e implementar cenários comuns usando a AWS Command Line Interface com o X-Ray.

Ações são trechos de código de programas maiores e devem ser executadas em contexto. Embora as ações mostrem como chamar perfis de serviço individuais, você pode ver as ações no contexto em seus cenários relacionados.

Cada exemplo inclui um link para o código-fonte completo, em que você pode encontrar instruções sobre como configurar e executar o código.

Tópicos

Ações

O código de exemplo a seguir mostra como usar batch-traces-get.

AWS CLI

Para obter uma lista de rastreamentos

O exemplo batch-get-traces a seguir recupera uma lista de rastreamentos especificados por um ID. O rastreamento completo inclui um documento para cada segmento, compilado a partir de todos os documentos de segmento recebidos com a mesma ID de rastreamento.

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

Saída:

{
    "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": []
}

Para obter mais informações, consulte Como usar a API do AWS X-Ray com a AWS CLI no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte BatchTracesGet na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar create-group.

AWS CLI

Para criar um grupo

O exemplo create-group a seguir cria um recurso de grupo chamado AdminGroup. O grupo obtém uma expressão de filtro que define os critérios do grupo como um segmento relacionado a um serviço específico que causa uma falha ou um erro.

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

Saída:

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

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para obter detalhes da API, consulte CreateGroup na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar create-sampling-rule.

AWS CLI

Para criar uma regra de amostragem

O exemplo create-sampling-rule a seguir cria uma regra para controlar o comportamento de amostragem para aplicações instrumentados. As regras são fornecidas por um arquivo JSON. A maioria dos campos da regra de amostragem é necessária para criar a regra.

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

Conteúdo 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
    }
}

Saída:

{
    "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
    }
}

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte CreateSamplingRule na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar delete-group.

AWS CLI

Para excluir um grupo

O exemplo delete-group a seguir exclui o recurso de grupo especificado.

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

Este comando não produz saída.

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para obter detalhes da API, consulte DeleteGroup na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar delete-sampling-rule.

AWS CLI

Para excluir uma regra de amostragem

O exemplo delete-sampling-rule a seguir exclui a regra de amostragem especificada. Você pode especificar o grupo usando o nome do grupo ou o ARN do grupo.

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

Saída:

{
    "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
    }
}

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte DeleteSamplingRule na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar get-encryption-config.

AWS CLI

Para recuperar a configuração de criptografia

O exemplo get-encryption-config a seguir recupera a configuração de criptografia atual para dados do seu AWS X-Ray.

aws xray get-encryption-config

Saída:

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

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para receber detalhes da API, consulte GetEncryptionConfig na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar get-group.

AWS CLI

Para recuperar um grupo

O exemplo get-group a seguir exibe os detalhes do recurso de grupo especificado. Os detalhes incluem o nome do grupo, o ARN do grupo e a expressão do filtro que define os critérios desse grupo. Os grupos também podem ser recuperados pelo ARN.

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

Saída:

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

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para obter detalhes da API, consulte GetGroup na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar get-groups.

AWS CLI

Para recuperar todos os grupos

O exemplo a seguir exibe detalhes de todos os grupos ativos.

aws xray get-groups

Saída:

{
    "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"
        }
    ]
}

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte GetGroups na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar get-sampling-rules.

AWS CLI

Para recuperar todas as regras de amostragem

O exemplo get-sampling-rules a seguir exibe detalhes de todas as regras de amostragem disponíveis:

aws xray get-sampling-rules

Saída:

{
    "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
        }
    ]
}

Para obter mais informações, consulte Usar regras de amostragem com a API do X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte GetSamplingRules na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar get-sampling-targets.

AWS CLI

Para solicitar uma cota de amostragem

O exemplo get-sampling-targets a seguir solicita uma cota de amostragem para regras que o serviço está usando para solicitações de amostra. A resposta do AWS X-Ray inclui uma cota que pode ser usada no lugar de empréstimos do reservatório.

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 } ]'

Saída:

{
    "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": []
}

Para obter mais informações, consulte Usar regras de amostragem com a API do X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte GetSamplingTargets na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar get-service-graph.

AWS CLI

Para obter um gráfico de serviços

O exemplo a seguir exibe um documento dentro de um período especificado que descreve os serviços que processam solicitações de entrada e serviços downstream que elas chamam como um resultado:

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

Saída:

{
    "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
}

Para obter mais informações, consulte Como usar a API do AWS X-Ray com a AWS CLI no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte GetServiceGraph na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar get-trace-summaries.

AWS CLI

Para obter um resumo do rastreamento

O exemplo get-trace-summaries a seguir recupera os IDs e os metadados de rastreamentos disponíveis dentro de determinado período.

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

Saída:

[
    "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"
]

Para obter mais informações, consulte Como usar a API do AWS X-Ray com a AWS CLI no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte GetTraceSummaries na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar put-encryption-config.

AWS CLI

Para atualizar a configuração de criptografia

O seguinte put-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

Saída:

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

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

O código de exemplo a seguir mostra como usar put-trace-segments.

AWS CLI

Como fazer upload de um segmento

O exemplo put-trace-segments a seguir faz o upload de documentos de segmento para o AWS X-Ray. O documento do segmento é consumido como uma lista de documentos do segmento JSON.

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\"}"

Saída:

{
    "UnprocessedTraceSegments": []
}

Para obter mais informações, consulte Enviar dados de rastreamento para o AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Consulte detalhes da API em PutTraceSegments na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar update-group.

AWS CLI

Para atualizar um grupo

O exemplo update-group a seguir atualiza os critérios pelos quais aceitar rastreamentos no grupo chamado AdminGroup. Você pode especificar o grupo desejado usando o nome do grupo ou o ARN do grupo.

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}"

Saída:

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

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para obter detalhes da API, consulte UpdateGroup na Referência de comandos da AWS CLI.

O código de exemplo a seguir mostra como usar update-sampling-rule.

AWS CLI

Para atualizar uma regra de amostragem

O exemplo update-sampling-rule a seguir modifica a configuração de uma regra de amostragem. As regras são consumidas a partir de um arquivo JSON. Somente os campos que estão sendo atualizados são obrigatórios.

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

Conteúdo de 1000-default.json:

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

Saída:

{
    "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
        }
   ]
}

Para obter mais informações, consulte Definir configurações de amostragem, grupos e criptografia com a API do AWS X-Ray no Guia do desenvolvedor do AWS X-Ray.

  • Para ver detalhes da API, consulte UpdateSamplingRule na Referência de comandos da AWS CLI.