View a markdown version of this page

Configuración de las funciones de observabilidad en el 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 funciones de observabilidad en el 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 for Ruby puede proporcionar las trazas 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 admite OpenTelemetry (OTel) como proveedor de telemetría y OpenTelemetry tiene muchas formas de exportar los datos de telemetría, incluso mediante Amazon. AWS X-Ray CloudWatch Para obtener más información sobre OpenTelemetry los exportadores de Ruby, consulta Exportadores en el sitio web. 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 for Ruby proporciona un OpenTelemetry proveedor. 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 for Ruby proporciona un OpenTelemetry proveedor llamado OTelProvider. El siguiente ejemplo configura la exportación de telemetría mediante OpenTelemetry el cliente del servicio Amazon Simple Storage Service. En este sencillo ejemplo, la variable de OTEL_TRACES_EXPORTER entorno from OpenTelemetry se utiliza para exportar las trazas a la salida de la consola cuando se ejecuta el código. Para obtener más informaciónOTEL_TRACES_EXPORTER, consulte la sección Selección de exportadores en la OpenTelemetry documentación. 

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. Requerir OpenTelemetry dependencias.

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

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

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

  3. Con el SDK del OpenTelemetry proveedor de Ruby, crea una instancia de la opción de configuración OTelProvider para pasarla al cliente de servicio que deseas 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 del AWS servicio, puede configurar el proveedor de telemetría Aws.config antes de crear los clientes del 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 quieres usarlo OpenTelemetry como proveedor de telemetría, el AWS SDK para Ruby te permite implementar un proveedor personalizado. Podría ser útil usar como ejemplo la OTelProviderimplementación que está disponible en el GitHub repositorio AWS SDK for 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.

Nombre de atributo Tipo Descripción
error Booleano Cierto si la unidad de trabajo no tuvo éxito. De lo contrario, devuelve false.
exception.message Cadena La excepción o el mensaje de error.
exception.stacktrace Cadena Un stacktrace tal como lo proporciona el motor de ejecución del idioma, si está disponible.
exception.type Cadena El tipo (nombre completo) de la excepción o error.
rpc.system Cadena El identificador del sistema remoto está establecido en 'aws-api'.
rpc.method Cadena El nombre de la operación que se invoca.
rpc.service Cadena El nombre del servicio remoto.
aws.request_id Cadena El identificador de AWS solicitud devuelto en los encabezados de respuesta, por intento de HTTP. Siempre que es posible, se utiliza el último ID de solicitud.
code.function Cadena El nombre del método o la función.
code.namespace Cadena El espacio de nombres dentro del cual code.function se define.
http.status_code Largo El código de estado de la respuesta HTTP.
http.request_content_length Largo El tamaño del cuerpo de la carga útil de la solicitud en bytes.
http.response_content_length Largo El tamaño del cuerpo de la carga útil de la respuesta en bytes.
http.method Cadena El método de solicitud HTTP.
net.protocol.name Cadena El nombre del protocolo de la capa de aplicación.
net.protocol.version Cadena La versión del protocolo de capa de aplicación (p. ej., 1.0, 1.1, 2.0).
net.peer.name Cadena El nombre de host remoto lógico.
net.peer.port Cadena El número de puerto remoto lógico.
sugerencia

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