Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Migrieren Sie zu Ruby OpenTelemetry Verwenden Sie die folgenden Codebeispiele und Anleitungen für die manuelle OpenTelemetry Instrumentierung, um Ihre Ruby-Anwendungen vom X-Ray SDK zur Instrumentierung zu migrieren. **Topics** + [Instrumentieren Sie Ihre Lösungen manuell mit dem SDK](#manual-instrumentation-ruby) + [Nachverfolgung eingehender Anfragen (Rails-Instrumentierung)](#tracing-incoming-requests-ruby) + [AWS SDK-Instrumentierung](#aws-sdk-instrumentation-ruby) + [Instrumentieren von ausgehenden HTTP-Aufrufen](#http-instrumentation-ruby) + [Instrumentierungsunterstützung für andere Bibliotheken](#xray-migration-libraries-ruby) + [Manuelles Erstellen von Trace-Daten](#manual-trace-creation-ruby) + [Manuelle Lambda-Instrumentierung](#lambda-instrumentation-ruby) ## Instrumentieren Sie Ihre Lösungen manuell mit dem SDK ------ #### [ Tracing setup with X-Ray SDK ] X-Ray X-Ray-SDK SDK for Ruby mussten Sie Ihren Code mit Service-Plug-ins konfigurieren. ``` require 'aws-xray-sdk' XRay.recorder.configure(plugins: [:ec2, :elastic_beanstalk]) ``` ------ #### [ Tracing setup with OpenTelemetry SDK ] **Anmerkung** X-Ray Remote Sampling kann derzeit nicht für OpenTelemetry Ruby konfiguriert werden. Platzieren Sie für eine Ruby on Rails-Anwendung Ihren Konfigurationscode in einem Rails-Initialisierer. Weitere Informationen finden Sie unter [Erste Schritte mit ](https://opentelemetry.io/docs/languages/ruby/getting-started/#initialization). Für alle manuell instrumentierten Ruby-Programme müssen Sie die `OpenTelemetry::SDK.configure` Methode verwenden, um das Ruby-SDK zu konfigurieren. OpenTelemetry Installieren Sie zunächst die folgenden Pakete: ``` bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-propagator-xray ``` Als Nächstes konfigurieren Sie das OpenTelemetry SDK mithilfe des Konfigurationscodes, der bei der Initialisierung Ihres Programms ausgeführt wird. Es wird empfohlen, die folgenden Komponenten zu konfigurieren: + `OTLP Exporter`— Erforderlich für den Export von Traces an den CloudWatch Agent und den OpenTelemetry Collector + `An AWS X-Ray Propagator`— Erforderlich für die Weitergabe des Trace-Kontextes an AWS Dienste, die in X-Ray integriert sind ``` require 'opentelemetry-sdk' require 'opentelemetry-exporter-otlp' # Import the gem containing the AWS X-Ray for OTel Ruby ID Generator and propagator require 'opentelemetry-propagator-xray' OpenTelemetry::SDK.configure do |c| c.service_name = 'my-service-name' c.add_span_processor( # Use the BatchSpanProcessor to send traces in groups instead of one at a time OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new( # Use the default OLTP Exporter to send traces to the ADOT Collector OpenTelemetry::Exporter::OTLP::Exporter.new( # The OpenTelemetry Collector is running as a sidecar and listening on port 4318 endpoint:"http://127.0.0.1:4318/v1/traces" ) ) ) # The X-Ray Propagator injects the X-Ray Tracing Header into downstream calls c.propagators = [OpenTelemetry::Propagator::XRay::TextMapPropagator.new] end ``` OpenTelemetry SDKs haben auch das Konzept der Bibliotheksinstrumentierung. Wenn Sie diese aktivieren, werden automatisch Bereiche für Bibliotheken wie das AWS SDK erstellt. OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen. Um alle Instrumentierungen zu aktivieren, installieren Sie zuerst das Paket: `opentelemetry-instrumentation-all` ``` bundle add opentelemetry-instrumentation-all ``` Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen wie unten gezeigt zu aktivieren: ``` require 'opentelemetry/instrumentation/all' ... OpenTelemetry::SDK.configure do |c| ... c.use_all() # Enable all instrumentations end ``` OpenTelemetry SDKs haben auch das Konzept der Bibliotheksinstrumentierung. Wenn Sie diese aktivieren, werden automatisch Bereiche für Bibliotheken wie das AWS SDK erstellt. OpenTelemetry bietet die Möglichkeit, alle Bibliotheksinstrumentierungen zu aktivieren oder anzugeben, welche Bibliotheksinstrumentierungen aktiviert werden sollen. Um alle Instrumentierungen zu aktivieren, installieren Sie zuerst das Paket: `opentelemetry-instrumentation-all` ``` bundle add opentelemetry-instrumentation-all ``` Aktualisieren Sie als Nächstes die Konfiguration, um alle Bibliotheksinstrumentierungen wie unten gezeigt zu aktivieren: ``` require 'opentelemetry/instrumentation/all' ... OpenTelemetry::SDK.configure do |c| ... c.use_all() # Enable all instrumentations end ``` ------ ## Nachverfolgung eingehender Anfragen (Rails-Instrumentierung) ------ #### [ With X-Ray SDK ] Mit dem X-Ray SDK wird das X-Ray-Tracing bei der Initialisierung für das Rails-Framework konfiguriert. **Beispiel** — \_xray.rb config/initializers/aws ``` Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true } ``` ------ #### [ With OpenTelemetry SDK ] Installieren Sie zunächst die folgenden Pakete: ``` bundle add opentelemetry-instrumentation-rack opentelemetry-instrumentation-rails opentelemetry-instrumentation-action_pack opentelemetry-instrumentation-active_record opentelemetry-instrumentation-action_view ``` Aktualisieren Sie als Nächstes die Konfiguration, um die Instrumentierung für Ihre Rails-Anwendung zu aktivieren, wie unten gezeigt: ``` # During SDK configuration OpenTelemetry::SDK.configure do |c| ... c.use 'OpenTelemetry::Instrumentation::Rails' c.use 'OpenTelemetry::Instrumentation::Rack' c.use 'OpenTelemetry::Instrumentation::ActionPack' c.use 'OpenTelemetry::Instrumentation::ActiveSupport' c.use 'OpenTelemetry::Instrumentation::ActionView' ... end ``` ------ ## AWS SDK-Instrumentierung ------ #### [ With X-Ray SDK ] Um ausgehende AWS Anfragen vom AWS SDK zu instrumentieren, werden die AWS SDK-Clients wie im folgenden Beispiel mit X-Ray gepatcht: ``` require 'aws-xray-sdk' require 'aws-sdk-s3' # Patch AWS SDK clients XRay.recorder.configure(plugins: [:aws_sdk]) # Use the instrumented client s3 = Aws::S3::Client.new s3.list_buckets ``` ------ #### [ With OpenTelemetry SDK ] AWS Das SDK for Ruby V3 bietet Unterstützung für das Aufzeichnen und Ausgeben OpenTelemetry von Spuren. Informationen zur Konfiguration OpenTelemetry für einen Service-Client finden Sie unter [Konfiguration von Observability-Funktionen im AWS SDK for Ruby](sdk-for-ruby/v3/developer-guide/observability.html). ------ ## Instrumentieren von ausgehenden HTTP-Aufrufen Wenn Sie HTTP-Aufrufe an externe Dienste tätigen, müssen Sie die Aufrufe möglicherweise manuell instrumentieren, wenn die automatische Instrumentierung nicht verfügbar ist oder nicht genügend Details liefert. ------ #### [ With X-Ray SDK ] Um Downstream-Aufrufe zu instrumentieren, wurde das X-Ray-SDK SDK for Ruby verwendet, um die `net/http` Bibliothek zu patchen, die Ihre Anwendung verwendet: ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http] } XRay.recorder.configure(config) ``` ------ #### [ With OpenTelemetry SDK ] Um die `net/http` Instrumentierung zu aktivieren OpenTelemetry, installieren Sie zunächst das `opentelemetry-instrumentation-net_http` Paket: ``` bundle add opentelemetry-instrumentation-net_http ``` Aktualisieren Sie als Nächstes die Konfiguration, um die `net/http` Instrumentierung wie folgt zu aktivieren: ``` OpenTelemetry::SDK.configure do |c| ... c.use 'OpenTelemetry::Instrumentation::Net::HTTP' ... end ``` ------ ## Instrumentierungsunterstützung für andere Bibliotheken Die vollständige Liste der unterstützten Bibliotheksinstrumentationen für OpenTelemetry Ruby finden Sie unter [opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation). Alternativ können Sie in der OpenTelemetry Registry suchen, um herauszufinden, ob Instrumentierung OpenTelemetry unterstützt wird. Weitere Informationen finden Sie unter [Registrierung](https://opentelemetry.io/ecosystem/registry/). ## Manuelles Erstellen von Trace-Daten ------ #### [ With X-Ray SDK ] Mit X-Ray mussten Sie für das `aws-xray-sdk` Paket manuell Segmente und deren untergeordnete Untersegmente erstellen, um Ihre Anwendung zu verfolgen. Möglicherweise haben Sie Ihren Segmenten oder Untersegmenten auch X-Ray-Anmerkungen und -Metadaten hinzugefügt: ``` require 'aws-xray-sdk' ... # Start a segment segment = XRay.recorder.begin_segment('my-service') # Add annotations (indexed key-value pairs) segment.annotations[:user_id] = 'user-123' segment.annotations[:payment_status] = 'completed' # Add metadata (non-indexed data) segment.metadata[:order] = { id: 'order-456', items: [ { product_id: 'prod-1', quantity: 2 }, { product_id: 'prod-2', quantity: 1 } ], total: 67.99 } # Add metadata to a specific namespace segment.metadata(namespace: 'payment') do |metadata| metadata[:transaction_id] = 'tx-789' metadata[:payment_method] = 'credit_card' end # Create a subsegment with annotations and metadata segment.subsegment('payment-processing') do |subsegment1| subsegment1.annotations[:payment_id] = 'pay-123' subsegment1.metadata[:details] = { amount: 67.99, currency: 'USD' } # Create a nested subsegment subsegment1.subsegment('operation-2') do |subsegment2| # Do more work... end end # Close the segment segment.close ``` ------ #### [ With OpenTelemetry SDK ] Sie können benutzerdefinierte Zeitspannen verwenden, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Untersegmente umgewandelt. Standardmäßig sind Spans. `INTERNAL` Erstellen Sie zunächst einen Tracer, um Spans zu generieren, die Sie mit der Methode abrufen können. `OpenTelemetry.tracer_provider.tracer('')` Dadurch wird eine Tracer-Instanz bereitgestellt, die global in der Konfiguration Ihrer Anwendung registriert ist. OpenTelemetry Es ist üblich, einen einzigen Tracer für eine gesamte Anwendung zu haben. Erstellen Sie einen OpenTelemetry Tracer und verwenden Sie ihn, um Spans zu erstellen: ``` require 'opentelemetry-sdk' ... # Get a tracer tracer = OpenTelemetry.tracer_provider.tracer('my-application') # Create a server span (equivalent to X-Ray segment) tracer.in_span('my-application', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span| # Do work... # Create nested spans of default kind INTERNAL will become an X-Ray subsegment tracer.in_span('operation-1') do |child_span1| # Set attributes (equivalent to X-Ray annotations and metadata) child_span1.set_attribute('key', 'value') # Do more work... tracer.in_span('operation-2') do |child_span2| # Do more work... end end end ``` **Hinzufügen von Anmerkungen und Metadaten zu Traces mit SDK OpenTelemetry ** Verwenden Sie die `set_attribute` Methode, um jedem Bereich Attribute hinzuzufügen. Beachten Sie, dass alle diese Span-Attribute standardmäßig in Metadaten in X-Rohdaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, können Sie diesen Attributschlüssel zur `aws.xray.annotations` Attributliste hinzufügen. Weitere Informationen finden Sie unter [Aktivieren der benutzerdefinierten X-Ray-Anmerkungen.](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations) ``` # SERVER span will become an X-Ray segment tracer.in_span('my-server-operation', kind: OpenTelemetry::Trace::SpanKind::SERVER) do |span| # Your server logic here span.set_attribute('attribute.key', 'attribute.value') span.set_attribute("metadataKey", "metadataValue") span.set_attribute("annotationKey1", "annotationValue") # Create X-Ray annotations span.set_attribute("aws.xray.annotations", ["annotationKey1"]) end ``` ------ ## Manuelle Lambda-Instrumentierung ------ #### [ With X-Ray SDK ] Nachdem *Active Tracing* auf Lambda aktiviert wurde, sind keine zusätzlichen Konfigurationen erforderlich, um das X-Ray SDK zu verwenden. Lambda erstellt ein Segment, das den Lambda-Handler-Aufruf darstellt, und Sie können Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ohne zusätzliche Konfiguration erstellen. ------ #### [ With OpenTelemetry SDK ] Betrachten Sie das folgende Beispiel für einen Lambda-Funktionscode (ohne Instrumentierung): ``` require 'json' def lambda_handler(event:, context:) # TODO implement { statusCode: 200, body: JSON.generate('Hello from Lambda!') } end ``` Um Ihr Lambda manuell zu instrumentieren, müssen Sie: 1. Füge die folgenden Edelsteine für dein Lambda hinzu ``` gem 'opentelemetry-sdk' gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-propagator-xray' gem 'aws-distro-opentelemetry-exporter-xray-udp' gem 'opentelemetry-instrumentation-aws_lambda' gem 'opentelemetry-propagator-xray', '~> 0.24.0' # Requires version v0.24.0 or higher ``` 1. Initialisieren Sie OpenTelemetry das SDK außerhalb Ihres Lambda-Handlers. Es wird empfohlen, das OpenTelemetry SDK zu konfigurieren mit: 1. Ein einfacher Span-Prozessor mit einem X-Ray-UDP-Span-Exporter zum Senden von Traces an den UDP-X-Ray-Endpunkt von Lambda 1. Ein Röntgen-Lambda-Propagator 1. `service_name`Konfiguration, die auf den Namen der Lambda-Funktion gesetzt werden soll 1. Fügen Sie in Ihrer Lambda-Handler-Klasse die folgenden Zeilen hinzu, um Ihren Lambda-Handler zu instrumentieren: ``` class Handler extend OpenTelemetry::Instrumentation::AwsLambda::Wrap ... instrument_handler :process end ``` Der folgende Code demonstriert die Lambda-Funktion nach den erforderlichen Änderungen. Sie können zusätzliche benutzerdefinierte Bereiche erstellen, um die automatisch bereitgestellten Bereiche zu ergänzen. ``` require 'json' require 'opentelemetry-sdk' require 'aws/distro/opentelemetry/exporter/xray/udp' require 'opentelemetry/propagator/xray' require 'opentelemetry/instrumentation/aws_lambda' # Initialize OpenTelemetry SDK outside handler OpenTelemetry::SDK.configure do |c| # Configure the AWS Distro for OpenTelemetry X-Ray Lambda exporter c.add_span_processor( OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new( AWS::Distro::OpenTelemetry::Exporter::XRay::UDP::AWSXRayUDPSpanExporter.new ) ) # Configure X-Ray Lambda propagator c.propagators = [OpenTelemetry::Propagator::XRay.lambda_text_map_propagator] # Set minimal resource information c.resource = OpenTelemetry::SDK::Resources::Resource.create({ OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => ENV['AWS_LAMBDA_FUNCTION_NAME'] }) c.use 'OpenTelemetry::Instrumentation::AwsLambda' end module LambdaFunctions class Handler extend OpenTelemetry::Instrumentation::AwsLambda::Wrap def self.process(event:, context:) "Hello!" end instrument_handler :process end end ``` ------ Im Folgenden finden Sie ein Beispiel für eine Trace-Map einer instrumentierten Lambda-Funktion, die in Ruby geschrieben wurde. ![Trace-Map in der CloudWatch Konsole für Ruby.](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/deprecation_ruby.png) Sie können Lambda-Ebenen auch verwenden, um Ihr Lambda OpenTelemetry zu konfigurieren. Weitere Informationen finden Sie unter [OpenTelemetry AWS-Lambda](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/aws_lambda#usage) Instrumentation.