Usar regras de amostragem com a API do X-Ray

O AWS X-Ray SDK usa a API do X-Ray para obter regras de amostragem, informar os resultados da amostragem e obter cotas. Você pode usar essas APIs para compreender melhor como as regras de amostragem funcionam ou para implementar a amostragem em uma linguagem que não seja compatível com o X-Ray SDK.

Comece obtendo todas as regras de amostragem com GetSamplingRules.

$ aws xray get-sampling-rules
{
    "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
        }
    ]
}

A saída inclui a regra padrão e regras personalizadas. Consulte Regras de amostragem se você ainda não tiver criado regras de amostragem.

Avalie as regras em relação às solicitações de entrada em ordem crescente de prioridade. Quando houver uma correspondência de regras, use a taxa fixa e o tamanho de reservatório para tomar uma decisão de amostragem. Registre as solicitações amostradas e ignore (para fins de rastreamento) as solicitações não amostradas. Pare de avaliar as regras quando uma decisão de amostragem for tomada.

O tamanho de um reservatório de regras é o número de destino de rastreamentos a serem registrados por segundo antes da aplicação da taxa fixa. O reservatório é aplicado em todos os serviços cumulativamente. Portanto, você não pode usá-lo diretamente. No entanto, se ele for diferente de zero, você poderá tomar emprestado um rastreamento por segundo do reservatório até que o X-Ray atribua uma cota. Antes de receber uma cota, registre a primeira solicitação a cada segundo, e aplique a taxa fixa nas solicitações adicionais. A taxa fixa é um valor decimal entre 0 e 1,00 (100%).

O exemplo a seguir mostra uma chamada para GetSamplingTargets com detalhes sobre as decisões de amostragem tomadas nos últimos 10 segundos.

$ 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",
        "ClientID": "ABCDEF1234567890ABCDEF10",
        "Timestamp": "2018-07-07T00:20:06",
        "RequestCount": 10500,
        "SampledCount": 31,
        "BorrowCount": 0
    }
]'
{
    "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": []
}
  

A resposta do X-Ray inclui uma cota para ser usada no lugar de empréstimos do reservatório. Neste exemplo, o serviço tomou emprestado 10 rastreamentos do reservatório em 10 segundos e aplicou a taxa fixa de 10% para as outras 100 solicitações, o que resulta em um total de 20 solicitações amostradas. A cota é válida por cinco minutos (indicada pela vida útil) ou até que uma nova cota seja atribuída. O X-Ray também pode atribuir um intervalo de emissão de relatórios maior do que o padrão, embora isso não ocorra aqui.

Os outros dois campos na resposta podem indicar problemas com a entrada. Compare a LastRuleModification com a data da última vez em que você chamou as GetSamplingRules. Se ela for mais recente, obtenha uma nova cópia das regras. UnprocessedStatistics pode incluir erros que indicam que uma regra foi excluída, que o documento de estatísticas na entrada era muito antigo ou erros de permissões.