Configuración del SDK de X-Ray para Go

Puede especificar la configuración del SDK de X-Ray para Go a través de variables de entorno, llamando a Configure con un objeto Config o suponiendo valores predeterminados. Las variables de entorno tienen prioridad sobre los valores Config, que tienen prioridad sobre cualquier valor predeterminado.

Complementos del servicio

Utilice plugins para registrar información sobre el servicio que aloja la aplicación.

Complementos

• Amazon EC2: EC2Plugin agrega el ID de la instancia, la zona de disponibilidad y el grupo de CloudWatch registros.

• Elastic Beanstalk: ElasticBeanstalkPlugin añade el nombre de entorno, la etiqueta de versión y el ID de implementación.

• Amazon ECS: ECSPlugin agrega el ID de contenedor.

Para utilizar un complemento, importe uno de los siguientes paquetes.

"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 complemento tiene una llamada de función Init() explícita que lo carga.

ejemplo 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",
  })
}

El SDK también usa la configuración del complemento para establecer el campo origin en el segmento. Esto indica el tipo de AWS recurso que ejecuta la aplicación. Cuando utilizas varios complementos, el SDK utiliza el siguiente orden de resolución para determinar el origen: ElasticBeanstalk > EKS > ECS > EC2.

Reglas de muestreo

El SDK utiliza las reglas de muestreo que define el usuario en la consola de X-Ray para determinar qué solicitudes registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el 5 % de las solicitudes adicionales de todos los servicios que envían rastros a X-Ray. Cree reglas adicionales en la consola de X-Ray para personalizar la cantidad de datos registrados para cada una de sus aplicaciones.

El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con varias reglas personalizadas, el SDK solo aplica la primera regla.

nota

Si el SDK no puede comunicarse con X-Ray para obtener las reglas de muestreo, vuelve a la regla local predeterminada de la primera solicitud recibida al principio de cada segundo y del cinco por ciento de las solicitudes adicionales por host. Eso puede ocurrir si el host no tiene permiso para llamar a las API de muestreo o no puede conectarse al daemon de X-Ray, que actúa como proxy TCP para las llamadas a las API realizadas por el SDK.

También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar las reglas locales como respaldo para los casos en que el muestreo de X-Ray no esté disponible, o puede usar las reglas locales exclusivamente.

ejemplo 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
  }
}

En este ejemplo se define una regla personalizada y una regla predeterminada. La regla personalizada aplica un porcentaje de muestreo del 5 % sin un número mínimo de solicitudes de rastreo para las rutas incluidas bajo /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y el 10 % de las solicitudes adicionales.

La desventaja de definir las reglas localmente es que el objetivo establecido lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser administrado por el servicio de X-Ray. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados.

Sí AWS Lambda, no puedes modificar la frecuencia de muestreo. Si un servicio instrumentado llama a su función, Lambda registrará las llamadas que generaron solicitudes muestreadas por ese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma la decisión de muestreo.

Para proporcionar reglas de copia de seguridad, apunte al archivo JSON de muestreo local mediante NewCentralizedStrategyWithFilePath.

ejemplo main.go: regla de muestreo local

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

Para utilizar solo reglas locales, apunte al archivo JSON de muestreo local mediante NewLocalizedStrategyFromFilePath.

ejemplo main.go — Deshabilitar el muestreo

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

Registro

nota

Los campos xray.Config{} LogLevel y LogFormat están obsoletos desde la versión 1.0.0-rc.10.

X-Ray utiliza la siguiente interfaz para el registro. El registrador predeterminado escribe en stdout a LogLevelInfo y superior.

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

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

ejemplo escribir en io.Writer

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

Variables de entorno

Puede usar variables de entorno con el fin de configurar el SDK de X-Ray para Go. El SDK admite las siguientes variables.

• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en RUNTIME_ERROR para generar excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.

  Valores válidos

  • RUNTIME_ERROR: lance una excepción de tiempo de ejecución.

  • LOG_ERROR: registre un error y continúe (predeterminado).

  • IGNORE_ERROR: ignore el error y continúe.

  Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar un cliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o en el código que inicia un nuevo subproceso.

• AWS_XRAY_TRACING_NAME: establezca el nombre de servicio que el SDK utiliza para los segmentos.

• AWS_XRAY_DAEMON_ADDRESS: establezca el host y el puerto del oyente del daemon de X-Ray. De forma predeterminada, el SDK envía los datos de rastreo a 127.0.0.1:2000. Use esta variable si ha configurado el daemon para que escuche en un puerto diferente o si se ejecuta en un host diferente.

Las variables de entorno anulan los valores equivalentes establecidos en el código.

Uso de la opción configure

También puede configurar el SDK de X-Ray para Go con el método Configure. Configure toma un argumento, un objeto Config, con los siguientes campos opcionales.

DaemonAddr

Esta cadena especifica el host y el puerto del oyente del daemon de X-Ray. Si no se especifica, X-Ray utiliza el valor de la variable de entorno AWS_XRAY_DAEMON_ADDRESS. Si dicho valor no está establecido, utiliza "127.0.0.1:2000".

ServiceVersion

Esta cadena especifica la versión del servicio. Si no se especifica, X-Ray utiliza la cadena vacía (“”).

SamplingStrategy

Este objeto SamplingStrategy especifica las llamadas de aplicación a las que se realiza seguimiento. Si no se especifica, X-Ray utiliza una LocalizedSamplingStrategy, que adopta la estrategia tal como se define en xray/resources/DefaultSamplingRules.json.

StreamingStrategy

Este StreamingStrategy objeto especifica si se debe transmitir un segmento cuando RequiresStreamingdevuelve el valor verdadero. Si no se especifica, X-Ray utiliza un DefaultStreamingStrategy que transmite un segmento muestreado si el número de subsegmentos es mayor que 20.

ExceptionFormattingStrategy

Este objeto ExceptionFormattingStrategy especifica la forma en que desea gestionar diversas excepciones. Si no se especifica, X-Ray utiliza una DefaultExceptionFormattingStrategy con un XrayError de tipo error, el mensaje de error y rastro de la pila.