Configurando o X-Ray SDK para Go

Você pode especificar a configuração do X-Ray SDK for Go por meio de variáveis de ambiente, Configure chamando com Config um objeto 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 o aplicativo.

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.

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 X-Ray console para determinar quais solicitações devem ser registradas. A regra padrão rastreia a primeira solicitação a cada segundo e cinco por cento de todas as solicitações adicionais em todos os serviços que enviam rastreamentos para X-Ray. Crie regras adicionais no X-Ray console para personalizar a quantidade de dados gravados para cada um dos seus aplicativos.

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.

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 X-Ray amostragem não está disponível ou usar regras locais exclusivamente.

{
  "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 alvo fixo é aplicado por cada instância do gravador de forma independente, em vez de ser gerenciado pelo X-Ray serviço. À 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.

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.

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

Registro em log

X-Ray usa a seguinte interface para registro. 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
)

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

Variáveis de ambiente

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

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

Usar Configure

Você também pode configurar o X-Ray SDK for Go usando Configure o método. Configureusa um argumento, um Config objeto, com os seguintes campos opcionais.