Configuración de las características de observabilidad en AWS SDK para Ruby - AWS SDK for Ruby
Configuración de un OTelProvider para un cliente de servicioConfiguración de un OTelProvider para todos los clientes de servicioConfiguración de un proveedor de telemetría personalizadoAtributos del intervalo

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Configuración de las características de observabilidad en AWS SDK para Ruby

La observabilidad es la medida en que se puede deducir el estado actual de un sistema a partir de los datos que emite. Los datos emitidos se denominan comúnmente “telemetría”. El AWS SDK para Ruby puede proporcionar los rastros como una señal de telemetría. Puede conectar un TelemetryProvider para recopilar y enviar datos de telemetría a un backend de observabilidad. Actualmente, el SDK es compatible con OpenTelemetry (OTel) como proveedor de telemetría y OpenTelemetry tiene muchas formas de exportar los datos de telemetría, incluido el uso de AWS X-Ray o Amazon CloudWatch. Para obtener más información sobre los exportadores de OpenTelemetry para Ruby, consulte Exportadores en el sitio web de OpenTelemetry.

De forma predeterminada, el SDK no registrará ni emitirá ningún dato de telemetría. En este tema se explica cómo configurar y emitir la salida de telemetría.

La telemetría se puede configurar para un servicio específico o de forma global. El SDK para Ruby proporciona un proveedor de OpenTelemetry. También puede definir un proveedor de telemetría personalizado de su elección.

Configuración de un OTelProvider para un cliente de servicio

El SDK para Ruby proporciona un proveedor de OpenTelemetry llamado OTelProvider. El siguiente ejemplo configura la exportación de telemetría mediante OpenTelemetry para el cliente del servicio Amazon Simple Storage Service. En este sencillo ejemplo, la variable de entorno OTEL_TRACES_EXPORTER de OpenTelemetry se utiliza para exportar los rastros a la salida de la consola cuando se ejecuta el código. Para obtener más información sobre OTEL_TRACES_EXPORTER, consulte Selección de exportadores en la documentación de OpenTelemetry. 

require 'aws-sdk-s3'
require 'opentelemetry-sdk'
require 'opentelemetry-exporter-otlp'

ENV['OTEL_TRACES_EXPORTER'] ||= 'console'

OpenTelemetry::SDK.configure

otel_provider = Aws::Telemetry::OTelProvider.new
client = Aws::S3::Client.new(telemetry_provider: otel_provider)
client.list_buckets

El ejemplo de código anterior muestra los pasos para configurar la salida de rastreo para un cliente de servicio:

  1. Requiere dependencias de OpenTelemetry.

    1. opentelemetry-sdk para usar Aws::Telemetry::OTelProvider.

    2. opentelemetry-exporter-otlp para exportar datos de telemetría.

  2. Llame a OpenTelemetry::SDK.configure para configurar el OpenTelemetry SDK con sus valores de configuración predeterminados.

  3. Con el SDK del proveedor de OpenTelemetry de Ruby, se crea una instancia del OTelProvider para pasarla como opción de configuración al cliente de servicio que desea rastrear.

    otel_provider = Aws::Telemetry::OTelProvider.new
client = Aws::S3::Client.new(telemetry_provider: otel_provider)

Con estos pasos, cualquier método que se invoque en ese cliente de servicio emitirá datos de rastreo.

A continuación, se muestra un ejemplo del resultado de rastreo generado por la llamada al método list_buckets de Amazon S3:

#<struct OpenTelemetry::SDK::Trace::SpanData
 name="Handler.NetHttp",
 kind=:internal,
 status=#<OpenTelemetry::Trace::Status:0x000000011da17bd8 @code=1, @description="">,
 parent_span_id="\xBFb\xC9\xFD\xA6F!\xE1",
 total_recorded_attributes=7,
 total_recorded_events=0,
 total_recorded_links=0,
 start_timestamp=1736190567061767000,
 end_timestamp=1736190567317160000,
 attributes=
  {"http.method"=>"GET",
   "net.protocol.name"=>"http",
   "net.protocol.version"=>"1.1",
   "net.peer.name"=>"s3.amazonaws.com",
   "net.peer.port"=>"443",
   "http.status_code"=>"200",
   "aws.request_id"=>"22HSH7NQTYMB5NHQ"},
 links=nil,
 events=nil,
 resource=
  #<OpenTelemetry::SDK::Resources::Resource:0x000000011e0bf990
   @attributes=
    {"service.name"=>"unknown_service",
     "process.pid"=>37013,
     "process.command"=>"example.rb",
     "process.runtime.name"=>"ruby",
     "process.runtime.version"=>"3.3.0",
     "process.runtime.description"=>"ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]",
     "telemetry.sdk.name"=>"opentelemetry",
     "telemetry.sdk.language"=>"ruby",
     "telemetry.sdk.version"=>"1.6.0"}>,
 instrumentation_scope=#<struct OpenTelemetry::SDK::InstrumentationScope name="aws.s3.client", version="">,
 span_id="\xEF%\x9C\xB5\x8C\x04\xDB\x7F",
 trace_id=" \xE7\xF1\xF8\x9D\e\x16/\xAC\xE6\x1A\xAC%j\x81\xD8",
 trace_flags=#<OpenTelemetry::Trace::TraceFlags:0x000000011d994328 @flags=1>,
 tracestate=#<OpenTelemetry::Trace::Tracestate:0x000000011d990638 @hash={}>>
#<struct OpenTelemetry::SDK::Trace::SpanData
 name="S3.ListBuckets",
 kind=:client,
 status=#<OpenTelemetry::Trace::Status:0x000000011da17bd8 @code=1, @description="">,
 parent_span_id="\x00\x00\x00\x00\x00\x00\x00\x00",
 total_recorded_attributes=5,
 total_recorded_events=0,
 total_recorded_links=0,
 start_timestamp=1736190567054410000,
 end_timestamp=1736190567327916000,
 attributes={"rpc.system"=>"aws-api", "rpc.service"=>"S3", "rpc.method"=>"ListBuckets", "code.function"=>"list_buckets", "code.namespace"=>"Aws::Plugins::Telemetry"},
 links=nil,
 events=nil,
 resource=
  #<OpenTelemetry::SDK::Resources::Resource:0x000000011e0bf990
   @attributes=
    {"service.name"=>"unknown_service",
     "process.pid"=>37013,
     "process.command"=>"example.rb",
     "process.runtime.name"=>"ruby",
     "process.runtime.version"=>"3.3.0",
     "process.runtime.description"=>"ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]",
     "telemetry.sdk.name"=>"opentelemetry",
     "telemetry.sdk.language"=>"ruby",
     "telemetry.sdk.version"=>"1.6.0"}>,
 instrumentation_scope=#<struct OpenTelemetry::SDK::InstrumentationScope name="aws.s3.client", version="">,
 span_id="\xBFb\xC9\xFD\xA6F!\xE1",
 trace_id=" \xE7\xF1\xF8\x9D\e\x16/\xAC\xE6\x1A\xAC%j\x81\xD8",
 trace_flags=#<OpenTelemetry::Trace::TraceFlags:0x000000011d994328 @flags=1>,
 tracestate=#<OpenTelemetry::Trace::Tracestate:0x000000011d990638 @hash={}>>

La salida de rastreo anterior tiene dos intervalos de datos. Cada entrada de rastreo proporciona metadatos adicionales sobre el evento en uno o más atributos.

Configuración de un OTelProvider para todos los clientes de servicio

En lugar de activar la telemetría para un cliente de servicio específico, como se ha explicado en la sección anterior, tiene la opción de activar la telemetría de forma global.

Para emitir datos de telemetría para todos los clientes de servicio de AWS, puede configurar el proveedor de telemetría en Aws.config antes de crear clientes de servicio.

otel_provider = Aws::Telemetry::OTelProvider.new 
Aws.config[:telemetry_provider] = otel_provider

Con esta configuración, cualquier cliente de servicio que se cree posteriormente emitirá automáticamente la telemetría. Para obtener más información sobre el uso de Aws.config para configurar ajustes global, consulte Aws.config.

Configuración de un proveedor de telemetría personalizado

Si no quiere usar OpenTelemetry como proveedor de telemetría, el AWS SDK para Ruby le permite implementar un proveedor personalizado. Podría ser útil usar como ejemplo la implementación de OTelProvider que está disponible en el repositorio de GitHub de AWS SDK para Ruby. Para obtener más información sobre el contexto, consulte las notas de Module: Aws::Telemetry en la Referencia de la API de AWS SDK para Ruby.

Atributos del intervalo

Los rastros son el resultado de la telemetría. Un conjunto de rastros consta de uno o varios intervalos. Los rastros tienen atributos que incluyen metadatos adicionales que se incluyen automáticamente cuando es apropiado para la llamada del método. A continuación, se muestra una lista de los atributos compatibles con el SDK para Ruby, donde:

  • Nombre del atributo: el nombre que se usa para etiquetar los datos que aparecen en el rastro.

  • Tipo: el tipo de datos del valor.

  • Descripción: una descripción de lo que representa el valor.

Attribute Name Type Description
error Boolean True if the unit of work was unsuccessful. Otherwise, false.
exception.message String The exception or error message.
exception.stacktrace String A stacktrace as provided by the language runtime if available.
exception.type String The type (fully qualified name) of the exception or error.
rpc.system String The remote system identifier set to 'aws-api'.
rpc.method String The name of the operation being invoked.
rpc.service String The name of the remote service.
aws.request_id String The AWS request ID returned in the response headers, per HTTP attempt. The latest request ID is used when possible.
code.function String The method or function name.
code.namespace String The namespace within which code.function is defined.
http.status_code Long The HTTP response status code.
http.request_content_length Long The size of the request payload body in bytes.
http.response_content_length Long The size of the response payload body in bytes.
http.method String The HTTP request method.
net.protocol.name String The name of the application layer protocol.
net.protocol.version String The version of the application layer protocol (e.g. 1.0, 1.1, 2.0).
net.peer.name String The logical remote hostname.
net.peer.port String The logical remote port number.
sugerencia

OpenTelemetry-Ruby tiene implementaciones adicionales que se integran con el SDK para el soporte de telemetría actual de Ruby. Para obtener más información, consulte OpenTelemetry AWS-SDK Instrumentation en el repositorio de open-telemetry GitHub.