SDKs e plataformas compatíveis Escolha sua abordagem de amostragem adaptável Configuração do SDK local

Configurar amostragem adaptável

A falta de rastreamentos críticos durante picos de anomalias pode dificultar a análise da causa raiz. No entanto, a manutenção de altas taxas de amostragem é cara. A amostragem adaptativa do X-Ray proporciona visibilidade completa das anomalias e controla os custos durante as operações normais. Com a amostragem adaptativa, você define uma taxa máxima de amostragem, e o X-Ray se ajusta automaticamente dentro desse limite. O X-Ray calcula o aumento mínimo necessário para capturar rastreamentos de erros. Se sua taxa de base capturar dados suficientes, nenhum aumento ocorrerá. Você só paga pela amostragem extra quando necessário.

Benefícios do uso da amostragem adaptável:

Visibilidade completa do incidente: obtenha rastreamentos completos durante os incidentes sem intervenção manual. O X-Ray ajusta automaticamente as taxas de amostragem para capturar rastreamentos de erros e, depois, retorna às taxas normais.
Visibilidade da causa raiz: confira sempre a origem dos problemas. O X-Ray captura dados de erros críticos mesmo quando a amostragem completa do traço não é acionada.
Otimize os custos: breves aumentos de amostragem (até 1 minuto) e períodos de espera automático evitam a sobreamostragem. Você só paga pelos dados necessários para diagnosticar problemas.

Tópicos

SDKs e plataformas compatíveis
Escolha sua abordagem de amostragem adaptável
Configuração do SDK local

SDKs e plataformas compatíveis

SDK compatível: a amostragem adaptável requer a versão mais recente do SDK do ADOT.

Linguagem compatível: Java (versão v2.11.5 ou superior)

Sua aplicação deve ser instrumentada com o SDK do ADOT compatível e executada com o agente do Amazon CloudWatch ou o coletor do OpenTelemetry.

Por exemplo, o Amazon EC2, o Amazon ECS e o Amazon EKS são plataformas comuns nas quais o AWS Application Signals fornece orientações para ativar o SDK do ADOT e o agente do Amazon CloudWatch.

Escolha sua abordagem de amostragem adaptável

A amostragem adaptável é compatível com duas abordagens: Aumento de amostragem e Captura de extensões de anomalias. Elas podem ser aplicadas de maneira independente ou podem ser combinadas.

Aumento de amostragem

O aumento adaptável de amostragem se baseia em regras de amostragem e funciona com o modelo existente de amostragem com base no principal do X-Ray. Amostragem baseada em principais significa que as decisões de amostragem são tomadas no serviço raiz, e o indicador de amostragem é passado downstream para todos os serviços na cadeia de chamadas.

Aumento baseado em regras: o aumento está sempre vinculado a uma regra específica de amostragem do X-Ray. Cada regra pode definir sua própria taxa máxima de aumento e comportamento de espera.
Amostragem baseada em principal: as decisões de amostragem são tomadas no serviço raiz, e o indicador de amostragem é passado downstream para todos os serviços na cadeia de chamadas.
Orientado por anomalias: o X-Ray depende do SDK para relatar estatísticas de anomalias. Quando o X-Ray detecta anomalias, como erros ou alta latência, ele usa essas estatísticas para calcular uma taxa de aumento apropriada (até o máximo configurado).

Relatórios de anomalias

Cada serviço de aplicativo na cadeia de chamadas pode emitir estatísticas de anomalias por meio do SDK necessário:

Serviço raiz: deve ser executado em um SDK e uma plataforma compatíveis para permitir o aumento da amostragem. Se o serviço raiz não for compatível, nenhum aumento ocorrerá.
Serviços downstream: os serviços downstream relatam apenas anomalias; eles não podem tomar decisões de amostragem. Quando um serviço downstream está executando um SDK compatível, as anomalias detectadas podem acionar um aumento na amostragem. Quando um serviço downstream não é compatível (por exemplo, executando um SDK antigo), anomalias nesse serviço não acionarão um aumento. Esses serviços ainda podem propagar o contexto downstream quando seguem a propagação padrão do contexto (como contexto de rastreamento e bagagem do W3C). Isso garante que os SDKs compatíveis em outros serviços downstream possam relatar anomalias que desencadeiam um aumento.

Aumentar o tempo e o escopo

Atraso do gatilho: um aumento de amostragem pode começar em apenas 10 segundos após o X-Ray detectar uma anomalia.
Período de aumento: depois que o X-Ray aciona um aumento, ele dura até 1 minuto antes de retornar à taxa de base de amostragem.
Aumento de espera: após a ocorrência de um aumento, o X-Ray só acionará outro impulso para a mesma regra depois que a janela de espera tiver passado.

Por exemplo, quando você define cooldown para 10 minutos, quando um aumento termina, nenhum novo aumento poderá ser acionado até a próxima janela de 10 minutos.

Caso especial: quando você define cooldown para 1 minuto, e como o aumento em si pode durar até 1 minuto, os impulsos podem ser acionados de maneira eficaz e contínua se a anomalia persistir.

nota

Use SDKs e plataformas compatíveis para seu serviço raiz. O aumento de amostragem funciona somente com SDKs e plataformas compatíveis. Embora o aumento de amostragem tenha uma alta probabilidade de capturar rastreamentos de anomalias, ele pode não capturar todos os rastreamentos de anomalia.

Aumentar a visibilidade

Quando uma regra de amostragem é configurada com aumento de amostragem adaptável, o X-Ray emite automaticamente métricas fornecidas que permitem monitorar a atividade do aumento.

Nome da métrica – SamplingRate
Dimensão — RuleName (definida como o nome real da regra)

Cada regra com SamplingRateBoost habilitado publicará sua taxa de amostragem efetiva, incluindo a taxa de base e quaisquer aumentos temporários. Isso permite a você:

Monitorar quando os aumentos são acionados
Monitorar a taxa de amostragem efetiva para cada regra
Correlacionar os aumentos com anomalias do aplicativo (como picos de erros ou eventos de latência)

Você pode visualizar essas métricas no Amazon CloudWatch Metrics, em AWS/X-Ray namespace. O valor métrico é um número de ponto flutuante entre 0 e 1, representando a taxa de amostragem efetiva.

Configurar o aumento de amostragem usando regras de amostragem do X-Ray

Você pode habilitar a amostragem adaptável diretamente nas regras existentes de amostragem do X-Ray adicionando um novo campo SamplingRateBoost. Para obter mais informações, consulte Personalizar regras de amostragem. Essa é uma maneira centralizada de permitir a amostragem adaptável sem modificar o código do aplicativo ou aplicar a implantação dele. Quando você habilita a amostragem adaptativa, o X-Ray aumenta automaticamente a amostragem durante anomalias, como picos de erro ou valores discrepantes de latência, mantendo as taxas de amostragem dentro do limite máximo configurado. SamplingRateBoost pode ser aplicado a qualquer regra de amostragem personalizada, exceto à regra de amostragem Default.

O campo SamplingRateBoost define o limite superior e o comportamento da amostragem baseada em anomalias.



"SamplingRateBoost": {
  "MaxRate": 0.25,
  "CooldownWindowMinutes": 10
}

MaxRate define a taxa máxima de amostragem que o X-Ray aplicará ao detectar anomalias. O intervalo de valores é de 0.0 a 1.0. Por exemplo, "MaxRate": 0.25 permite que a amostragem aumente em até 25% das solicitações durante uma janela de anomalia. O X-Ray determina a taxa apropriada entre a sua linha de base e a máxima, dependendo da atividade da anomalia.

CooldownWindowMinutes define a janela de tempo (em minutos) na qual apenas um aumento na taxa de amostragem pode ser acionado. Depois que um aumento ocorre, nenhum aumento adicional é permitido até a próxima janela. O tipo de valor é inteiro (minutos).

Exemplo de regra com amostragem adaptável



{
  "RuleName": "MyAdaptiveRule",
  "Priority": 1,
  "ReservoirSize": 1,
  "FixedRate": 0.05,
  "ServiceName": "*",
  "ServiceType": "*",
  "Host": "*",
  "HTTPMethod": "*",
  "URLPath": "*",
  "SamplingRateBoost": {
    "MaxRate": 0.25,
    "CooldownWindowMinutes": 10
  }
}

Neste exemplo, a amostragem de linha de base é 5% (FixedRate: 0.05). Durante anomalias, o X-Ray pode aumentar a amostragem em até 25% (MaxRate: 0.25). Aumente apenas uma vez a cada 10 minutos.

Configuração da condição de anomalia

Quando nenhuma configuração de condição de anomalia é fornecida, o SDK do ADOT usa códigos de erro HTTP 5xx como condição de anomalia padrão para acionar o aumento da amostragem.

Você também pode ajustar as condições de anomalia localmente no SDK do ADOT compatível usando variáveis de ambiente. Para obter mais informações, consulte Configuração do SDK local.

Captura de extensões de anomalias

A captura da extensão de anomalias garante que as extensões críticas que representam anomalias sejam sempre registradas, mesmo que o rastreamento completo não seja amostrado. Esse recurso complementa o aumento da amostragem, concentrando-se na captura da anomalia em si, em vez de aumentar a amostragem para futuros rastreamentos.

Quando o SDK do ADOT detecta uma anomalia, ele emite essa extensão imediatamente, independentemente da decisão de amostragem. Como o SDK só emite extensões relacionadas à anomalia, esses rastreamentos são parciais, não transações completas de ponta a ponta.

Depois que o SDK do ADOT detecta uma extensão de anomalia, ele tenta emitir o maior número possível de extensões do mesmo rastreamento. Todas as extensões emitidas nesse recurso são marcadas com o atributo, aws.trace.flag.sampled = 0. Isso permite distinguir facilmente traços parciais (captura de anomalias) de traços completos (amostragem normal) na pesquisa e análise de transações.

É recomendável integrar a Pesquisa de transações para visualizar e consultar rastreamentos parciais. O exemplo a seguir mostra uma página de serviço no console do Application Signals. O ServiceC é configurado com captura de extensões de anomalias e faz parte de uma cadeia de chamadas em que o aumento da amostragem se aplica. Essas configurações geram rastreamentos completos e parciais. Você pode usar o atributo aws.trace.flag.sampled para distinguir entre os tipos de rastreamento.

A captura de extensões de anomalias só pode ser habilitada ou personalizada por meio do Configuração do SDK local.

Configuração do SDK local

Você pode configurar recursos de amostragem adaptável no SDK do ADOT fornecendo uma configuração YAML por meio de uma variável de ambiente. A configuração local fornece controle refinado sobre condições e limites de anomalias.

Isso é necessário para a captura de extensões de anomalias e opcional para personalizar as condições de aumento de amostragem. Veja a seguir um exemplo de configuração:



version: 1.0
anomalyConditions:
  - errorCodeRegex: "^5\\d\\d$"
    usage: both
  - operations:
      - "/api"
    errorCodeRegex: "^429|5\\d\\d$"
    highLatencyMs: 300
    usage: sampling-boost
  - highLatencyMs: 1000
    usage: anomaly-span-capture

anomalyCaptureLimit:
  anomalyTracesPerSecond: 1

Confira as definições de campo abaixo:

version: versão do esquema do arquivo de configuração
anomalyConditions: define as condições sob as quais as anomalias são detectadas e como elas são usadas
- errorCodeRegex: expressão regular que define quais códigos de status HTTP são considerados anomalias
- operations: lista de operações ou endpoints aos quais a condição se aplica
- highLatencyMs: limite de latência (em milissegundos) acima do qual as extensões são tratadas como anomalias
- usage: define a qual recurso a condição se aplica:
  - both: aplica-se ao aumento de amostragem e à captura de extensões de anomalias (padrão se o uso não for especificado)
  - sampling-boost: usado somente para acionar aumentos de amostragem
  - anomaly-span-capture: usado somente para captura de extensões de anomalias
anomalyCaptureLimit: define os limites para a emissão de rastreamentos com extensões de anomalias.

anomalyTracesPerSecond: número máximo de rastreamentos com extensões de anomalias capturadas por segundo para evitar um volume excessivo de extensões (o valor padrão será 1 se anomalyCaptureLimit não estiver presente).

nota

AnomalyConditions substitui a condição de anomalia padrão para o aumento de amostragem (HTTP 5xx). Se você quiser reter a condição padrão ao usar a configuração local, deverá incluí-la explicitamente em qualquer item de AnomalyConditions.
Para cada item anomalyConditions:
- Quando o campo operations é omitido, a condição se aplica a todas as operações (nível de serviço)
- Quando o campo operations está presente, mas definido como uma lista vazia, a condição se aplica a nenhuma operação, tornando esse item sem operação
- Quando errorCodeRegex e highLatencyMs são omitidos, a condição não tem critérios de anomalia a serem avaliados, tornando esse item sem operação
Relações lógicas:
- Entre os itens em anomalyConditions, o relacionamento é OR.
- Em um único item, vários campos (por exemplo, errorCodeRegex ehighLatencyMs) são combinados com AND.
  
  Por exemplo:
```
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
                
```
  Essa condição significa que o código de status corresponde a 429 ou 5xx E a latência é ≥ 300 ms.

Aplique a configuração local ao SDK do ADOT

Você pode aplicar a configuração local ao SDK do ADOT definindo a variável de ambiente AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG. O valor deve ser um documento YAML válido (em linha ou aninhado).

Por exemplo, o Amazon EC2 e o Amazon ECS definem a variável de ambiente de maneira direta:



AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}"

Para o Amazon EKS, defina a variável de ambiente dentro da especificação do pod como YAML aninhado:



apiVersion: v1
kind: Pod
metadata:
  name: adot-sample
spec:
  containers:
    - name: adot-app
      image: my-app:latest
      env:
        - name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG
          value: |
            version: 1.0
            anomalyConditions:
              - errorCodeRegex: "^500$"
                usage: sampling-boost
              - errorCodeRegex: "^501$"
                usage: anomaly-trace-capture
            anomalyCaptureLimit:
              anomalyTracesPerSecond: 10

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Amostragem

Vinculação direta do console