Esempi di X-Ray con la AWS CLI

Gli esempi di codice seguenti mostrano come eseguire azioni e implementare scenari comuni utilizzando AWS Command Line Interface con X-Ray.

Le operazioni sono estratti di codice da programmi più grandi e devono essere eseguite nel contesto. Sebbene le operazioni mostrino come richiamare le singole funzioni del servizio, è possibile visualizzarle contestualizzate negli scenari correlati.

Ogni esempio include un link al codice sorgente completo, dove è possibile trovare le istruzioni su come configurare ed eseguire il codice nel contesto.

Argomenti

Operazioni

Operazioni

L’esempio di codice seguente mostra come utilizzare batch-traces-get.

AWS CLI

Come ottenere un elenco di tracce

L’esempio batch-get-traces seguente recupera un elenco di tracce specificate da un ID. Il tracciamento completo include un documento per ogni segmento, creato a partire da tutti i documenti di segmento con lo stesso ID di tracciamento ricevuti.


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

Output:


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

Per ulteriori informazioni, consulta Using the AWS X-Ray API with the AWS CLI nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta BatchTracesGet in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare create-group.

AWS CLI

Creazione di un gruppo

Nell’esempio seguente create-group crea un gruppo di risorse denominato AdminGroup. Il gruppo ottiene un’espressione di filtro che definisce i criteri del gruppo come segmento relativo a un servizio specifico che causa un guasto o un errore.


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

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull'API, consulta CreateGroup nella Documentazione di riferimento dei comandi della AWS CLI.

L’esempio di codice seguente mostra come utilizzare create-sampling-rule.

AWS CLI

Come creare una regola di campionamento

Nell’esempio seguente create-sampling-rule crea una regola per controllare il comportamento di campionamento per applicazioni strumentate. Le regole sono fornite da un file JSON. La maggior parte dei campi delle regole di campionamento sono necessari per creare la regola.


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

Contenuto di 9000-base-scorekeep.json.


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

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta CreateSamplingRule in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare delete-group.

AWS CLI

Come eliminare un gruppo

Nell’esempio seguente delete-group elimina il gruppo di risorse specificato.


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

Questo comando non produce alcun output.

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull'API, consulta DeleteGroup nella Documentazione di riferimento dei comandi della AWS CLI.

L’esempio di codice seguente mostra come utilizzare delete-sampling-rule.

AWS CLI

Come eliminare una regola di campionamento

L’esempio delete-sampling-rule seguente elimina la regola di campionamento specificata. È possibile specificare il gruppo utilizzando il nome del gruppo o l’ARN del gruppo.


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

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta DeleteSamplingRule in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare get-encryption-config.

AWS CLI

Come recuperare la configurazione di crittografia

Nell’esempio seguente get-encryption-config recupera la configurazione di crittografia corrente per dati AWS X-Ray.


aws xray get-encryption-config

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta GetEncryptionConfig in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare get-group.

AWS CLI

Come recuperare un gruppo

Nell’esempio seguente get-group visualizza i dettagli relativi alla risorsa di gruppo specificata. I dettagli includono il nome del gruppo, l’ARN del gruppo e l’espressione di filtro che definisce i criteri per quel gruppo. I gruppi possono essere recuperati anche tramite ARN.


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

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per i dettagli dell'API, consulta GetGroup in Riferimento ai comandi della AWS CLI.

L’esempio di codice seguente mostra come utilizzare get-groups.

AWS CLI

Come recuperare tutti i gruppi

L’esempio seguente visualizza i dettagli per tutti i gruppi attivi.


aws xray get-groups

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta GetGroup in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare get-sampling-rules.

AWS CLI

Come recuperare tutte le regole di campionamento

L’esempio get-sampling-rules seguente mostra i dettagli di tutte le regole di campionamento disponibili.:


aws xray get-sampling-rules

Output:


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

Per ulteriori informazioni, consulta Using Sampling Rules with the X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta GetSamplingRules in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare get-sampling-targets.

AWS CLI

Come richiedere una quota di campionamento

Nell’esempio seguente get-sampling-targets richiede una quota di campionamento per le regole utilizzate dal servizio per campionare le richieste. La risposta di AWS X-Ray include una quota che può essere utilizzata al posto del prelievo dalla riserva.


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

Output:


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

Per ulteriori informazioni, consulta Using Sampling Rules with the X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta GetSamplingTargets in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare get-service-graph.

AWS CLI

Come ottenere un grafico dei servizi

L’esempio seguente visualizza un documento entro un periodo di tempo specificato che descrive i servizi che elaborano le richieste in entrata e i servizi downstream che chiamano di conseguenza.:


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

Output:


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

Per ulteriori informazioni, consulta Using the AWS X-Ray API with the AWS CLI nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta GetServiceGraph in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare get-trace-summaries.

AWS CLI

Come ottenere un riepilogo delle tracce

Nell’esempio seguente get-trace-summaries recupera gli ID e i metadati per tracce disponibili entro un intervallo di tempo specificato.


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

Output:


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

Per ulteriori informazioni, consulta Using the AWS X-Ray API with the AWS CLI nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta GetTraceSummaries in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare put-encryption-config.

AWS CLI

Come aggiornare la configurazione della crittografia

Nell’esempio di seguente vengono utilizzati filtri per estendere i risultati ai gruppi di sicurezza che hanno una regola che consente il traffico SSH (porta 22) e una regola che consente il traffico da tutti gli indirizzi (0.0.0.0/0 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

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta PutEncryptionConfig in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare put-trace-segments.

AWS CLI

Come caricare un segmento

Nell’esempio seguente put-trace-segments carica i documenti dei segmenti in AWS X-Ray. Il documento del segmento viene utilizzato come elenco di documenti di 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\"}"

Output:


{
    "UnprocessedTraceSegments": []
}

Per ulteriori informazioni, consulta Sending Trace Data to AWS X-Ray nella Guida per sviluppatori AWS X-Ray.

Per informazioni dettagliate sull’API, consulta PutTraceSegments in AWS CLI Command Reference.

L’esempio di codice seguente mostra come utilizzare update-group.

AWS CLI

Come aggiornare un gruppo

Nell’esempio seguente update-group aggiorna i criteri in base ai quali accettare le tracce nel gruppo denominato AdminGroup. È possibile specificare il gruppo desiderato utilizzando il nome o l’ARN del gruppo.


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

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per i dettagli dell'API, consulta UpdateGroup in Riferimento ai comandi della AWS CLI.

L’esempio di codice seguente mostra come utilizzare update-sampling-rule.

AWS CLI

Come aggiornare una regola di campionamento

Nell’esempio seguente update-sampling-rule modifica la configurazione di una regola di campionamento. Le regole vengono utilizzate da un file JSON. Sono obbligatori solo i campi in fase di aggiornamento.


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

Contenuto di 1000-default.json.


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

Output:


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

Per ulteriori informazioni, consulta Configuring Sampling, Groups, and Encryption Settings with the AWS X-Ray API nella Guida per sviluppatori di AWS X-Ray.

Per informazioni dettagliate sull’API, consulta UpdateSamplingRule in AWS CLI Command Reference.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

WorkSpaces

Esempi di script Bash