As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Configurando o X-Ray SDK para Go **nota** X-Ray SDK/Daemon Aviso de manutenção — Em 25 de fevereiro de 2026, AWS X-Ray SDKs/Daemon ele entrará no modo de manutenção, onde AWS limitará os lançamentos do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre como migrar para OpenTelemetry, consulte [Migração da X-Ray instrumentação para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry 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. **Topics** + [Plug-ins de serviço](#xray-sdk-go-configuration-plugins) + [Regras de amostragem](#xray-sdk-go-configuration-sampling) + [Registro em log](#xray-sdk-go-configuration-logging) + [Variáveis de ambiente](#xray-sdk-go-configuration-envvars) + [Usar Configure](#xray-sdk-go-configuration-configure) ## Plug-ins de serviço Use `plugins` para registrar informações sobre o serviço que hospeda o aplicativo. **Plugins** + 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. ![Segmente dados de recursos com os plug-ins do Amazon EC2 e do Elastic Beanstalk.](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-go.png) 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. **Example 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 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](xray-console-sampling.md) 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. **nota** Se o SDK não conseguir X-Ray obter regras de amostragem, ele reverte para uma regra local padrão da primeira solicitação a 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 X-Ray daemon, que atua como um proxy 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 X-Ray amostragem não está disponível ou usar regras locais exclusivamente. **Example 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 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`. **Example 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`. **Example 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. 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 ) ``` **Example escreva para `io.Writer`** ``` 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. + `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 X-Ray daemon listener. 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](xray-daemon-configuration.md) 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 for Go usando `Configure` o método. `Configure`usa um argumento, um `Config` objeto, com os seguintes campos opcionais. DaemonAddr Essa string especifica o host e a porta do X-Ray ouvinte daemon. Se não for especificado, X-Ray usa o valor da variável de `AWS_XRAY_DAEMON_ADDRESS` ambiente. 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 for especificado, X-Ray usa a string vazia (“”). SamplingStrategy Esse objeto `SamplingStrategy` especifica quais de suas chamadas do aplicativo são rastreadas. Se não for especificado, X-Ray usa um`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 **RequiresStreaming**retorna **verdadeiro**. Se não for especificado, o X-Ray usará uma `DefaultStreamingStrategy` que transmitirá um segmento amostrado se o número de subsegmentos for maior que 20. ExceptionFormattingStrategy Esse objeto `ExceptionFormattingStrategy` especifica como você deseja lidar com várias exceções. Se não for especificado, X-Ray usa um `DefaultExceptionFormattingStrategy` com um `XrayError` do tipo`error`, a mensagem de erro e o rastreamento de pilha.