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
<a name="observability"></a>

 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](https://docs.aws.amazon.com/xray/?icmpid=docs_homepage_devtools) CloudWatch](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov) Para obtener más información sobre OpenTelemetry los exportadores de Ruby, consulta [Exportadores](https://opentelemetry.io/docs/languages/ruby/exporters) 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
<a name="config-otel"></a>

El SDK for Ruby proporciona un OpenTelemetry proveedor llamado [https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry/OTelProvider.html](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry/OTelProvider.html). 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ón`OTEL_TRACES_EXPORTER`, consulte la sección [Selección de exportadores](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#exporter-selection) 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. [https://rubygems.org/gems/opentelemetry-sdk](https://rubygems.org/gems/opentelemetry-sdk) para usar `Aws::Telemetry::OTelProvider`. 

   1. [https://rubygems.org/gems/opentelemetry-exporter-otlp](https://rubygems.org/gems/opentelemetry-exporter-otlp) para exportar datos de telemetría.

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

1.  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:

### Ejemplo de salida de OpenTelemetry rastreo
<a name="otel-trace-output"></a>

```
#<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
<a name="otel-global"></a>

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`](setup-config.md#config). 

## Configuración de un proveedor de telemetría personalizado
<a name="custom-telem"></a>

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 [`OTelProvider`implementación](https://github.com/aws/aws-sdk-ruby/blob/version-3/gems/aws-sdk-core/lib/aws-sdk-core/telemetry/otel.rb) que está disponible en el GitHub repositorio AWS SDK for Ruby. Para obtener más información sobre el contexto, consulte las notas de [https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry.html](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Telemetry.html) en la *Referencia de la API de AWS SDK para Ruby *. 

## Atributos del intervalo
<a name="span-attributes"></a>

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](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_sdk) Instrumentation en el repositorio. `open-telemetry` GitHub