Configurar recursos de observabilidade no AWS SDK para Ruby - AWS SDK para Ruby
Configurar um OTelProvider para um cliente de serviçoConfiguração de um OTelProvider para todos os clientes de serviçoConfigurar um provedor de telemetria personalizadoAtributos de extensão

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á.

Configurar recursos de observabilidade no AWS SDK para Ruby

Observabilidade é a medida em que o estado atual de um sistema pode ser identificado com base nos dados que ele emite. Os dados emitidos são chamados, com frequência, de telemetria. O AWS SDK para Ruby pode fornecer os rastreamentos como um sinal de telemetria. Você pode conectar um TelemetryProvider para coletar e enviar dados de telemetria para um backend de observabilidade. Atualmente, o SDK comporta o OpenTelemetry (OTel) como provedor de telemetria e o OpenTelemetry tem várias maneiras de exportar seus dados de telemetria, inclusive usando o AWS X-Ray ou o Amazon CloudWatch. Para acessar mais informações sobre os exportadores para OpenTelemetry para Ruby, consulte a seção Exportadores no site do OpenTelemetry.

Por padrão, o SDK não registrará nem emitirá dados de telemetria. Este tópico explica como configurar e emitir a saída de telemetria.

A telemetria pode ser configurada para um serviço específico ou globalmente. O SDK para Ruby fornece um provedor do OpenTelemetry. Você também pode definir um provedor de telemetria personalizado de sua escolha.

Configurar um OTelProvider para um cliente de serviço

O SDK para Ruby fornece um provedor do OpenTelemetry chamado OTelProvider. O exemplo a seguir configura a exportação de telemetria usando o OpenTelemetry para o cliente do serviço Amazon Simple Storage Service. Neste exemplo simples, a variável de ambiente OTEL_TRACES_EXPORTER do OpenTelemetry é usada para exportar os rastreamentos para a saída do console quando você executa o código. Para saber mais sobre OTEL_TRACES_EXPORTER, consulte Seleção do exportador na documentação do 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

O exemplo de código anterior mostra as etapas para configurar a saída de rastreamento para um cliente de serviço:

  1. Exigir dependências do OpenTelemetry.

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

    2. opentelemetry-exporter-otlp para exportar dados de telemetria.

  2. Chame OpenTelemetry::SDK.configure para configurar o SDK do OpenTelemetry com suas configurações padrão.

  3. Usando o SDK para o provedor OpenTelemetry do Ruby, crie uma instância do OTelProvider para passar como uma opção de configuração para o cliente de serviço que você deseja rastrear.

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

Usando essas etapas, qualquer método chamado nesse cliente de serviço emitirá dados de rastreamento.

Um exemplo da saída de rastreamento gerada a partir da chamada para o método list_buckets do Amazon S3 é o seguinte:

#<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={}>>

A saída de rastreamento anterior tem dois intervalos de dados. Cada entrada de rastreamento fornece metadados adicionais sobre o evento em um ou mais atributos.

Configuração de um OTelProvider para todos os clientes de serviço

Em vez de ativar a telemetria para um cliente de serviço específico, como explicado na seção anterior, você tem a opção de ativar a telemetria globalmente.

Para emitir dados de telemetria para todos os clientes de serviço da AWS, você pode configurar o provedor de telemetria em Aws.config antes de criar os clientes de serviço.

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

Com essa configuração, qualquer cliente de serviço criado posteriormente emitirá a telemetria de forma automática. Para saber mais sobre como usar Aws.config para definir configurações globais, consulte Aws.config.

Configurar um provedor de telemetria personalizado

Se você não quiser usar o OpenTelemetry como seu provedor de telemetria, o AWS SDK para Ruby comporta a implementação de um provedor personalizado. Pode ser útil usar a implementação de OTelProvider que está disponível no repositório GitHub do AWS SDK para Ruby como exemplo. Para ter mais contexto, consulte as notas Module: Aws::Telemetry na Referência da API AWS SDK para Ruby.

Atributos de extensão

Os rastreamentos são os resultados da telemetria. Os rastreamentos consistem em uma ou mais extensões. As extensões possuem atributos que incluem metadados adicionais que são automaticamente incluídos quando apropriado para a chamada do método. Veja a seguir uma lista dos atributos aceitos pelo SDK para Ruby, onde:

  • Nome do atributo: o nome usado para rotular os dados que aparecem no rastreamento.

  • Tipo: o tipo de dados do valor.

  • Descrição: uma descrição do que o valor representa.

Attribute Name Type Description
erro 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.
dica

O OpenTelemetry-Ruby possui implementações adicionais que são integradas ao SDK para o suporte de telemetria já existente no Ruby. Para acessar mais informações, consulte a instrumentação do AWS SDK do OpenTelemetry no repositório GitHub open-telemetry.