Configurar o X-Ray SDK para Go

Você pode especificar a configuração do X-Ray SDK para Go por meio de variáveis de ambiente chamando Configure com um objeto Config ou assumindo valores padrão. As variáveis de ambiente têm prioridade sobre os valores de Config, que têm precedência sobre qualquer valor padrão.

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, importe um dos seguintes pacotes.

"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
"github.com/aws/aws-xray-sdk-go/awsplugins/ecs"
"github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk"

Cada plug-in tem uma chamada de função Init() explícita que carrega o plug-in.

exemplo ec2.Init()

import (
	"os"

	"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
	"github.com/aws/aws-xray-sdk-go/xray"
)

func init() {
  // conditionally load plugin
  if os.Getenv("ENVIRONMENT") == "production" {
    ec2.Init()
  }

  xray.Configure(xray.Config{
    ServiceVersion: "1.2.3",
  })
}

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 fornecer regras de backup, aponte para o arquivo JSON de amostragem local usando o NewCentralizedStrategyWithFilePath.

exemplo main.go: regra de amostragem local

s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

Para usar somente regras locais, aponte para o arquivo JSON de amostragem local usando o NewLocalizedStrategyFromFilePath.

exemplo main.go: desabilitar a amostragem

s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})

Registro em log

nota

Os campos xray.Config{} LogLevel e LogFormat estão defasados a partir da versão 1.0.0-rc.10.

O X-Ray usa a interface a seguir para registro em log. O registrador em log padrão grava em stdout em LogLevelInfo e acima.

type Logger interface {
	Log(level LogLevel, msg fmt.Stringer)
}

const (
	LogLevelDebug LogLevel = iota + 1
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)

exemplo gravar em io.Writer

xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError))

Variáveis de ambiente

É possível usar variáveis de ambiente para configurar o X-Ray SDK para Go. O SDK é compatível com as variáveis a seguir.

• 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.

• AWS_XRAY_TRACING_NAME: defina o nome do serviço que o SDK usa para segmentos.

• AWS_XRAY_DAEMON_ADDRESS: defina o host e a porta do receptor do daemon do X-Ray. Por padrão, o SDK envia dados de rastreamento para 127.0.0.1:2000. 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.

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

Usar Configure

Você também pode configurar o X-Ray SDK para Go usando o método Configure. O Configure usa um argumento, um objeto Config, com os campos opcionais a seguir.

DaemonAddr

Essa string especifica o host e a porta do receptor do daemon do X-Ray. Se não especificado, o X-Ray usará o valor da variável de ambiente AWS_XRAY_DAEMON_ADDRESS. Se esse valor não estiver definido, "127.0.0.1:2000" será usado.

ServiceVersion

Essa sequência de caracteres especifica a versão do serviço. Se não especificado, o X-Ray usará a string vazia ("").

SamplingStrategy

Esse objeto SamplingStrategy especifica quais de suas chamadas do aplicativo são rastreadas. Se não especificado, o X-Ray usará uma LocalizedSamplingStrategy, que usa a estratégia conforme definido em xray/resources/DefaultSamplingRules.json.

StreamingStrategy

Esse StreamingStrategy objeto especifica se um segmento deve ser transmitido quando RequiresStreamingretorna verdadeiro. Se não especificado, o X-Ray usará uma DefaultStreamingStrategy, que transmitirá um segmento amostrado se o número de subsegmentos for superior a 20.

ExceptionFormattingStrategy

Esse objeto ExceptionFormattingStrategy especifica como você deseja lidar com várias exceções. Se não especificado, o X-Ray usará uma DefaultExceptionFormattingStrategy com um XrayError do tipo error, a mensagem de erro e o rastreamento de pilha.