Instrumentieren von Ruby-Code in AWS Lambda

Lambda ist mit AWS X-Ray integriert, um Ihnen zu ermöglichen, Lambda-Anwendungen zu verfolgen, zu debuggen und zu optimieren. Sie können mit X-Ray eine Anforderung verfolgen, während sie Ressourcen in Ihrer Anwendung durchläuft, von der Frontend-API bis hin zu Speicher und Datenbank im Backend. Indem Sie einfach die X-Ray-SDK-Bibliothek zu Ihrer Build-Konfiguration hinzufügen, können Sie Fehler und Latenz für jeden Aufruf aufzeichnen, den Ihre Funktion an einen AWS-Service durchführt.

Nachdem Sie die aktive Nachverfolgung konfiguriert haben, können Sie bestimmte Anfragen über Ihre Anwendung beobachten. Das X-Ray-Service-Diagramm zeigt Informationen über Ihre Anwendung und alle ihre Komponenten an. Das folgende Beispiel zeigt eine Anwendung mit zwei Funktionen. Die primäre Funktion verarbeitet Ereignisse und gibt manchmal Fehler zurück. Die zweite Funktion ganz oben verarbeitet Fehler, die in der Protokollgruppe der ersten Protokollgruppe erscheinen, und verwendet das AWS-SDK, um X-Ray, Amazon Simple Storage Service (Amazon S3) und Amazon CloudWatch Logs aufzurufen.

Gehen Sie folgendermaßen vor, um die aktive Nachverfolgung Ihrer Lambda-Funktion mit der Konsole umzuschalten:

Ihre Funktion benötigt die Berechtigung zum Hochladen von Trace-Daten zu X-Ray. Wenn Sie die aktive Nachverfolgung in der Lambda-Konsole aktivieren, fügt Lambda der Ausführungsrolle Ihrer Funktion die erforderlichen Berechtigungen hinzu. Andernfalls fügen Sie der Ausführungsrolle die AWSXRayDaemonWriteAccess-Richtlinie hinzu.

X-Ray verfolgt nicht alle Anfragen an Ihre Anwendung nach. X-Ray wendet einen Sampling-Algorithmus an, um sicherzustellen, dass die Nachverfolgung effizient ist, und stellt dennoch ein repräsentatives Beispiel aller Anfragen bereit. Die Samplingrate beträgt 1 Anforderung pro Sekunde und 5 Prozent aller weiteren Anforderungen. Sie können die X-Ray-Samplingrate nicht für Ihre Funktionen konfigurieren.

In X-Ray, zeichnet eine Ablaufverfolgung Informationen zu einer Anforderung auf, die von einem oder mehreren Services verarbeitet wird. Lambda zeichnet 2 Segmente pro Trace auf, wodurch zwei Knoten im Dienstgraphen entstehen. In der folgenden Abbildung werden diese beiden Knoten hervorgehoben:

Der erste Knoten auf der linken Seite stellt den Lambda-Service dar, der die Aufrufanforderung empfängt. Der zweite Knoten stellt Ihre spezifische Lambda-Funktion dar. Das folgende Beispiel zeigt eine Nachverfolgung mit diesen zwei Segmenten. Beide heißen my-function, aber einer hat einen Ursprung von AWS::Lambda und der andere hat einen Ursprung von AWS::Lambda::Function. Wenn das AWS::Lambda-Segment einen Fehler anzeigt, hatte der Lambda-Service ein Problem. Wenn das AWS::Lambda::Function-Segment einen Fehler anzeigt, ist bei Ihrer Funktion ein Problem aufgetreten.

Dieses Beispiel erweitert das AWS::Lambda::Function-Segment, um seine drei Untersegmente anzuzeigen.

Das Funktionssegment im alten Stil enthält die folgenden Untersegmente:

Das Funktionssegment im neuen Stil enthält kein Invocation-Untersegment. Stattdessen werden Kundenuntersegmente direkt an das Funktionssegment angehängt. Weitere Informationen über die Struktur der alten und neuen Funktionssegmente finden Sie unter Grundlegendes zu X-Ray-Ablaufverfolgungen.

Sie können Ihren Handler-Code instrumentieren, um Metadaten aufzuzeichnen und Downstream-Aufrufe nachzuverfolgen. Um Details zu Aufrufen aufzuzeichnen, die Ihr Handler an andere Ressourcen und Services macht, verwenden Sie das X-Ray-SDK für Ruby. Um das SDK zu erhalten, fügen Sie das aws-xray-sdk-Paket den Abhängigkeiten Ihrer Anwendung hinzu.

# Gemfile
source 'https://rubygems.org'

gem 'aws-xray-sdk', '0.11.4'
gem 'aws-sdk-lambda', '1.39.0'
gem 'test-unit', '3.3.5'

Um AWS SDK-Clients zu instrumentieren, benötigen Sie das aws-xray-sdk/lambda-Modul, nachdem Sie einen Client im Initialisierungscode erstellt haben.

# lambda_function.rb
require 'logger'
require 'json'
require 'aws-sdk-lambda'
$client = Aws::Lambda::Client.new()
$client.get_account_settings()

require 'aws-xray-sdk/lambda'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  ...

In X-Ray, zeichnet eine Ablaufverfolgung Informationen zu einer Anforderung auf, die von einem oder mehreren Services verarbeitet wird. Lambda zeichnet 2 Segmente pro Trace auf, wodurch zwei Knoten im Dienstgraphen entstehen. In der folgenden Abbildung werden diese beiden Knoten hervorgehoben:

Der erste Knoten auf der linken Seite stellt den Lambda-Service dar, der die Aufrufanforderung empfängt. Der zweite Knoten stellt Ihre spezifische Lambda-Funktion dar. Das folgende Beispiel zeigt eine Nachverfolgung mit diesen zwei Segmenten. Beide heißen my-function, aber einer hat einen Ursprung von AWS::Lambda und der andere hat einen Ursprung von AWS::Lambda::Function. Wenn das AWS::Lambda-Segment einen Fehler anzeigt, hatte der Lambda-Service ein Problem. Wenn das AWS::Lambda::Function-Segment einen Fehler anzeigt, ist bei Ihrer Funktion ein Problem aufgetreten.

Dieses Beispiel erweitert das AWS::Lambda::Function-Segment, um seine drei Untersegmente anzuzeigen.

Das Funktionssegment im alten Stil enthält die folgenden Untersegmente:

Das Funktionssegment im neuen Stil enthält kein Invocation-Untersegment. Stattdessen werden Kundenuntersegmente direkt an das Funktionssegment angehängt. Weitere Informationen über die Struktur der alten und neuen Funktionssegmente finden Sie unter Grundlegendes zu X-Ray-Ablaufverfolgungen.

Sie können auch HTTP-Clients instrumentieren, SQL-Abfragen aufzeichnen und benutzerdefinierte Untersegmente mit Anmerkungen und Metadaten erstellen. Weitere Informationen finden Sie unter Das X-Ray-SDK für Ruby im AWS X-Ray-Entwicklerhandbuch.

Aktivieren der aktiven Ablaufverfolgung mit der Lambda-API

Verwenden Sie die folgenden API-Operationen, um die Protokollierungskonfiguration mit der AWS CLI oder dem AWS-SDK zu verwalten:

Der folgende AWS CLI-Beispielbefehl aktiviert die aktive Nachverfolgung für eine Funktion mit dem Namen my-function.

aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

Der Ablaufverfolgungsmodus ist Teil der versionsspezifischen Konfiguration, wenn Sie eine Version Ihrer Funktion veröffentlichen. Sie können den Ablaufverfolgungsmodus für eine veröffentlichte Version nicht ändern.

Aktivieren von aktiver Ablaufverfolgung mit CloudFormation

Verwenden Sie die AWS::Lambda::Function-Eigenschaft, um die Nachverfolgung für eine CloudFormation-Ressource in einer TracingConfig-Vorlage zu aktivieren.

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Verwenden Sie für eine AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function-Ressource die Eigenschaft Tracing.

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Speichern von Laufzeitabhängigkeiten in einer Ebene

Wenn Sie das X-Ray-SDK verwenden, um mit AWS-SDK-Clients Ihren Funktionscode zu instrumentieren, kann Ihr Bereitstellungspaket ziemlich groß werden. Um Laufzeitabhängigkeiten bei jeder Aktualisierung des Funktionscodes zu vermeiden, verpacken Sie das X-Ray-SDK in einer Lambda-Ebene.

Das folgende Beispiel zeigt eine AWS::Serverless::LayerVersion-Ressource, die das X-Ray-SDK für Ruby speichert.

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-ruby-lib
      Description: Dependencies for the blank-ruby sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - ruby2.5

Bei dieser Konfiguration aktualisieren Sie die Bibliotheksebene nur, wenn Sie Ihre Laufzeitabhängigkeiten ändern. Da das Funktionsbereitstellungspaket nur Ihren Code enthält, kann dies dazu beitragen, die Upload-Zeiten zu reduzieren.

Das Erstellen einer Ebene für Abhängigkeiten erfordert Build-Konfigurationsänderungen, um das Ebenen-Archiv vor der Bereitstellung zu generieren. Ein funktionierendes Beispiel finden Sie in der Beispielanwendung blank-ruby .