AWS SDK for Ruby에서 관찰성 기능 구성 - AWS SDK for Ruby
서비스 클라이언트에 대한 OTelProvider 구성모든 서비스 클라이언트에 대한 OTelProvider 구성사용자 지정 원격 측정 공급자 구성스팬 속성

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AWS SDK for Ruby에서 관찰성 기능 구성

관찰성은 시스템이 내보내는 데이터에서 시스템의 현재 상태를 추론할 수 있는 범위입니다. 내보내는 데이터를 일반적으로 원격 측정이라고 합니다. AWS SDK for Ruby는 트레이스를 원격 측정 신호로 제공할 수 있습니다. TelemetryProvider를 연결해 원격 측정 데이터를 수집하고 관찰성 백엔드로 전송할 수 있습니다. SDK는 현재 원격 측정 공급자로 OpenTelemetry(OTel)를 지원하며 OpenTelemetry에는 AWS X-Ray 또는 Amazon CloudWatch를 사용하는 등 원격 측정 데이터를 내보내는 다양한 방법이 있습니다. Ruby용 OpenTelemetry 내보내기에 대한 자세한 내용은 OpenTelemetry 웹 사이트의 Exporters를 참조하세요.

기본적으로 SDK는 원격 측정 데이터를 기록하거나 내보내지 않습니다. 이 주제에서는 원격 측정 출력을 구성하고 내보내는 방법을 설명합니다.

특정 서비스에 대해 또는 전역적으로 원격 측정을 구성할 수 있습니다. SDK for Ruby는 OpenTelemetry 공급자를 제공합니다. 원하는 사용자 지정 원격 측정 공급자를 정의할 수도 있습니다.

서비스 클라이언트에 대한 OTelProvider 구성

SDK for Ruby는 OTelProvider라는 OpenTelemetry 공급자를 제공합니다. 다음 예제에서는 Amazon Simple Storage Service 서비스 클라이언트에 대해 OpenTelemetry를 사용하여 원격 측정 내보내기를 구성합니다. 이 간단한 예제에서는 코드를 실행할 때 OpenTelemetry의 OTEL_TRACES_EXPORTER 환경 변수를 사용하여 트레이스를 콘솔 출력으로 내보냅니다. OTEL_TRACES_EXPORTER에 대한 자세한 내용은 OpenTelemetry 설명서의 Exporter Selection을 참조하세요.

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

이전 코드 예제에서는 서비스 클라이언트에 대해 트레이스 출력을 구성하는 단계를 보여줍니다.

  1. OpenTelemetry 종속 항목이 필요합니다.

    1. Aws::Telemetry::OTelProvider를 사용하는 데 필요한 opentelemetry-sdk.

    2. 원격 측정 데이터를 내보내는 데 필요한 opentelemetry-exporter-otlp.

  2. OpenTelemetry::SDK.configure를 직접적으로 호출하여 OpenTelemetry SDK를 구성 기본값으로 설정합니다.

  3. SDK for Ruby의 OpenTelemetry 공급자를 사용해 OTelProvider의 인스턴스를 생성하여 추적하려는 서비스 클라이언트에 구성 옵션으로 전달합니다.

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

이 단계를 사용하면 해당 서비스 클라이언트에서 직접적으로 호출되는 모든 메서드가 트레이스 데이터를 내보내게 됩니다.

Amazon S3의 list_buckets 메서드에 대한 직접 호출에서 생성된 트레이스 출력의 예는 다음과 같습니다.

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

이전 트레이스 출력에는 두 가지 범위의 데이터가 있습니다. 각 트레이스 항목은 하나 이상의 속성에서 이벤트에 대한 추가 메타데이터를 제공합니다.

모든 서비스 클라이언트에 대한 OTelProvider 구성

이전 섹션에서 설명한 대로 특정 서비스 클라이언트에 대해 원격 측정을 켜는 대신 전역적으로 원격 측정을 켤 수 있습니다.

모든 AWS 서비스 클라이언트에 대해 원격 측정 데이터를 내보내려는 경우 서비스 클라이언트를 생성하기 전에 Aws.config에서 원격 측정 공급자를 설정할 수 있습니다.

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

이 구성을 사용하면 이후에 생성된 모든 서비스 클라이언트가 자동으로 원격 측정을 내보냅니다. Aws.config를 사용하여 글로벌 설정을 지정하는 방법에 대한 자세한 내용은 Aws.config 섹션을 참조하세요.

사용자 지정 원격 측정 공급자 구성

OpenTelemetry를 원격 측정 공급자로 사용하지 않으려는 경우를 위해 AWS SDK for Ruby는 사용자 지정 공급자 구현을 지원합니다. AWS SDK for Ruby GitHub 리포지토리에서 제공되는 OTelProvider 구현을 예시로 참고하면 도움이 될 수 있습니다. 추가 컨텍스트는 AWS SDK for Ruby API 참조에 있는 Module: Aws::Telemetry의 참고 사항을 확인하세요.

스팬 속성

트레이스는 원격 측정의 출력입니다. 트레이스는 하나 이상의 스팬으로 구성됩니다. 스팬에는 메서드 직접 호출에 적합한 경우 자동으로 포함되는 추가 메타데이터가 포함된 속성이 있습니다. 다음은 SDK for Ruby에서 지원하는 속성 목록입니다. 여기서:

  • 속성 이름 - 트레이스에 나타나는 데이터를 레이블링하는 데 사용되는 이름입니다.

  • 유형 - 값의 데이터 유형입니다.

  • 설명 - 값이 나타내는 내용에 대한 설명입니다.

Attribute Name Type Description
오류 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.
작은 정보

OpenTelemetry-Ruby에는 SDK for Ruby의 기존 원격 측정 지원과 통합된 추가 구현이 있습니다. 자세한 내용은 open-telemetry GitHub 리포지토리의 OpenTelemetry AWS-SDK Instrumentation을 참조하세요.