Configurar o X-Ray SDK para Python

O X-Ray SDK para Python tem uma classe chamada xray_recorder, que fornece o gravador global. Você pode configurar o gravador global para personalizar o middleware que cria segmentos para chamadas HTTP de entrada.

Plug-ins de serviço

Use plugins para registrar informações sobre o serviço que hospeda a aplicação.

Plug-ins

• Amazon EC2 — EC2Plugin adiciona o ID da instância, a zona de disponibilidade e o grupo de CloudWatch registros.

• Elastic Beanstalk: o ElasticBeanstalkPlugin adiciona o nome do ambiente, o rótulo da versão e o ID de implantação.

• Amazon ECS: o ECSPlugin adiciona o ID do contêiner.

Para usar um plug-in, chame configure no xray_recorder.

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

xray_recorder.configure(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()

nota

Como os plugins são passados como uma tupla, inclua uma , à direita ao especificar um único plug-in. Por exemplo, plugins = ('EC2Plugin',).

Você também pode usar variáveis de ambiente, que têm precedência sobre valores definidos no código, para configurar o gravador.

Configure plug-ins antes de bibliotecas de patches para gravar chamadas downstream.

O SDK também usa as configurações do plug-in para definir o campo origin no segmento. Isso indica o tipo de AWS recurso que executa seu aplicativo. Quando você usa vários plug-ins, o SDK usa a seguinte ordem de resolução para determinar a origem: ElasticBeanstalk > EKS > ECS > EC2.

Regras de amostragem

O SDK usa as regras de amostragem que você define no console do X-Ray para determinar quais solicitações serão registradas. A regra padrão rastreia a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais em todos os serviços que enviam rastreamentos ao X-Ray. Crie regras adicionais no console do X-Ray para personalizar a quantidade de dados registrados para cada uma das aplicações.

O SDK aplica regras personalizadas na ordem em que elas estão definidas. Se uma solicitação corresponder a várias regras personalizadas, o SDK aplicará somente a primeira regra.

nota

Se o SDK não conseguir acessar o X-Ray para obter regras de amostragem, ele reverte para uma regra local padrão da primeira solicitação recebida no início de cada segundo e cinco por cento de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar APIs de amostragem ou não conseguir se conectar ao daemon do X-Ray, que atua como um proxy de TCP para chamadas de API feitas pelo SDK.

Você também pode configurar o SDK para carregar regras de amostragem de um documento JSON. O SDK pode usar regras locais como backup para casos em que a amostragem do X-Ray não está disponível ou usar exclusivamente regras locais.

exemplo sampling-rules.json

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

Este exemplo define uma regra personalizada e uma regra padrão. A regra personalizada aplica uma taxa de amostragem de 5% sem um número mínimo de solicitações para rastrear os caminhos em /api/move/. A regra padrão rastreia a primeira solicitação a cada segundo e 10% das solicitações adicionais.

A desvantagem de definir regras localmente é que o destino fixo é aplicado por instância do gravador de forma independente, em vez de ser gerenciado pelo serviço X-Ray. À medida que você implanta mais hosts, a taxa fixa é multiplicada, dificultando o controle da quantidade de dados registrados.

Ativado AWS Lambda, você não pode modificar a taxa de amostragem. Se sua função for chamada por um serviço instrumentado, as chamadas que geraram solicitações que foram amostradas por esse serviço serão registradas pelo Lambda. Se o rastreamento ativo estiver habilitado e nenhum cabeçalho de rastreamento estiver presente, o Lambda tomará a decisão de amostragem.

Para configurar regras de amostragem de backup, chame xray_recorder.configure, conforme mostrado no exemplo a seguir, em que rules é um dicionário de regras ou o caminho absoluto para um arquivo JSON que contém regras de amostragem.

xray_recorder.configure(sampling_rules=rules)

Para usar somente regras locais, configure o gravador com um LocalSampler.

from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())

Você também pode configurar o gravador global para desabilitar a amostragem e instrumentar todas as solicitações de entrada.

exemplo main.py: desabilitar a amostragem

xray_recorder.configure(sampling=False)

Registro em log

O SDK usa o módulo logging integrado do Python com um nível de registro em log WARNING padrão. Obtenha uma referência ao agente de log para a classe aws_xray_sdk e chame setLevel nela para configurar o nível de log diferente para a biblioteca e o restante de seu aplicativo.

exemplo app.py: Registrar em log

logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

Use logs de depuração para identificar problemas como subsegmentos não fechados ao gerar subsegmentos manualmente.

Configuração do gravador no código

Configurações adicionais estão disponíveis no método configure no xray_recorder.

• context_missing: defina como LOG_ERROR para evitar o lançamento de exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto.

• daemon_address: defina o host e a porta do receptor do daemon do X-Ray.

• service: defina um nome de serviço para o SDK usar para segmentos.

• plugins— Registre informações sobre os AWS recursos do seu aplicativo.

• sampling: defina como False para desabilitar a amostragem.

• sampling_rules: defina o caminho do arquivo JSON que contém suas regras de amostragem.

exemplo main.py: desabilitar exceções de contexto ausente

from aws_xray_sdk.core import xray_recorder

xray_recorder.configure(context_missing='LOG_ERROR')

Configuração do gravador com o Django

Se você usar a estrutura do Django, poderá usar o arquivo settings.py do Django para configurar as opções no gravador global.

• AUTO_INSTRUMENT (Somente para Django): registre os subsegmentos para operações de renderização de banco de dados e de modelo integrados.

• AWS_XRAY_CONTEXT_MISSING: defina como LOG_ERROR para evitar o lançamento de exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto.

• AWS_XRAY_DAEMON_ADDRESS: defina o host e a porta do receptor do daemon do X-Ray.

• AWS_XRAY_TRACING_NAME: defina um nome de serviço para o SDK usar para segmentos.

• PLUGINS— Registre informações sobre os AWS recursos do seu aplicativo.

• SAMPLING: defina como False para desabilitar a amostragem.

• SAMPLING_RULES: defina o caminho do arquivo JSON que contém suas regras de amostragem.

Para habilitar a configuração do gravador em settings.py, adicione o middleware do Django à lista de aplicativos instalados.

exemplo settings.py: aplicações instalados

INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]

Configurar as configurações disponíveis em um dict chamado XRAY_RECORDER.

exemplo settings.py: aplicações instalados

XRAY_RECORDER = {
    'AUTO_INSTRUMENT': True,
    'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
    'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
    'AWS_XRAY_TRACING_NAME': 'My application',
    'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
    'SAMPLING': False,
}

Variáveis de ambiente

É possível usar variáveis de ambiente para configurar o X-Ray SDK para Python. O SDK é compatível com as seguintes variáveis:

• AWS_XRAY_TRACING_NAME: defina um nome de serviço para o SDK usar para segmentos. Substitui o nome do serviço definido programaticamente.

• AWS_XRAY_SDK_ENABLED: quando definido como false, desabilita o SDK. Por padrão, o SDK está habilitado, a menos que a variável de ambiente esteja definida como falsa.

  • Quando desabilitado, o gravador global gera automaticamente segmentos e subsegmentos fictícios que não são enviados para o daemon, e a aplicação automática de patches está desabilitada. Os middlewares são gravados como um wrapper pelo gravador global. Toda a geração de segmentos e subsegmentos pelo middleware também se torna segmentos fictícios e subsegmentos fictícios.

  • Defina o valor de AWS_XRAY_SDK_ENABLED por meio da variável de ambiente ou por meio de interação direta com o objeto global_sdk_config da biblioteca de aws_xray_sdk. As configurações para a variável de ambiente substituem essas interações.

• AWS_XRAY_DAEMON_ADDRESS: defina o host e a porta do receptor do daemon do X-Ray. Por padrão, o SDK usa 127.0.0.1:2000 para dados de rastreamento (UDP) e para amostragem (TCP). Use essa variável se você tiver configurado o daemon para escutar em uma porta diferente ou se ele estiver sendo executado em um host diferente.

  Formato

  • Mesma porta: address:port

  • Portas diferentes: tcp:address:port udp:address:port

• AWS_XRAY_CONTEXT_MISSING: defina como RUNTIME_ERROR para lançar exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto.

  Valores válidos

  • RUNTIME_ERROR: lance uma exceção de tempo de execução.

  • LOG_ERROR: registre um erro e continue (padrão).

  • IGNORE_ERROR: ignore o erro e continue.

  Erros relativos a segmentos ou subsegmentos ausentes poderão ocorrer quando você tentar usar um cliente instrumentado no código de inicialização que é executado quando nenhuma solicitação estiver aberta ou em um código que gere um novo thread.

As variáveis de ambiente substituem os valores definidos no código.