View a markdown version of this page

Instrumentierung von Java-Code in AWS Lambda - AWS Lambda
Verwenden Sie Powertools für AWS Lambda (Java) und AWS SAM zur RückverfolgungVerwenden von Powertools für AWS Lambda (Java) und die AWS CDK zur RückverfolgungVerwenden von ADOT zur Instrumentierung Ihrer Java-FunktionenVerwenden Sie das X-Ray SDK zur Instrumentierung Ihrer Java-FunktionenAktivieren der Nachverfolgung mit der Lambda-KonsoleAktivieren der Nachverfolgung mit der Lambda-APIDie Protokollierung wird aktiviert mit CloudFormationInterpretieren einer Ablaufverfolgung X-RaySpeichern von Laufzeitabhängigkeiten in einer Ebene (X-Ray SDK)X-Ray Ablaufverfolgung in Beispielanwendungen (SDK) X-Ray

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.

Instrumentierung von Java-Code in AWS Lambda

Lambda lässt sich mit integrieren AWS X-Ray , um Ihnen bei der Verfolgung, dem Debuggen und der Optimierung von Lambda-Anwendungen zu helfen. Sie können es verwenden X-Ray, um eine Anfrage zu verfolgen, während sie Ressourcen in Ihrer Anwendung durchläuft. Dazu können Lambda-Funktionen und andere Dienste gehören. AWS

Um Ablaufverfolgungsdaten an diese zu senden X-Ray, können Sie eine von zwei SDK-Bibliotheken verwenden:

Jedes der SDKs bietet Möglichkeiten, Ihre Telemetriedaten an den Dienst zu senden. X-Ray Anschließend können Sie X-Ray die Leistungskennzahlen Ihrer Anwendung anzeigen, filtern und Einblicke in sie gewinnen, um Probleme und Optimierungsmöglichkeiten zu identifizieren.

Wichtig

Die X-Ray und Powertools for AWS Lambda SDKs sind Teil einer eng integrierten Instrumentierungslösung, die von angeboten wird. AWS Die ADOT Lambda Layers sind Teil eines branchenweiten Standards für die Verfolgung von Instrumenten, die im Allgemeinen mehr Daten erfassen, aber möglicherweise nicht für alle Anwendungsfälle geeignet sind. Mit beiden Lösungen können Sie eine durchgängige Ablaufverfolgung implementieren. X-Ray Weitere Informationen zur Auswahl zwischen diesen Optionen finden Sie unter Auswahl zwischen der AWS Distribution for Open Telemetry und SDKs. X-Ray

Verwenden Sie Powertools für AWS Lambda (Java) und AWS SAM zur Rückverfolgung

Folgen Sie den unten stehenden Schritten, um eine Hello World Java-Beispielanwendung mit integrierten Powertools for AWS Lambda (Java) -Modulen mithilfe von herunterzuladen, zu erstellen und bereitzustellen. AWS SAM Diese Anwendung implementiert ein grundlegendes API-Backend und verwendet Powertools zum Ausgeben von Protokollen, Metriken und Traces. Es besteht aus einem Amazon-API-Gateway-Endpunkt und einer Lambda-Funktion. Wenn Sie eine GET-Anfrage an den API Gateway-Endpunkt senden, ruft die Lambda-Funktion auf, sendet Protokolle und Metriken im Embedded Metric Format an und sendet CloudWatch Traces an. AWS X-Ray Die Funktion gibt eine hello world-Nachricht zurück.

Voraussetzungen

Zur Durchführung der Schritte in diesem Abschnitt benötigen Sie Folgendes:

Stellen Sie ein Beispiel bereit AWS SAM Anwendung

  1. Initialisieren Sie die Anwendung mit der Hello World Java-Vorlage.

    sam init --app-template hello-world-powertools-java --name sam-app --package-type Zip --runtime java11 --no-tracing

  2. Entwickeln Sie die App.

    cd sam-app && sam build

  3. Stellen Sie die Anwendung bereit.

    sam deploy --guided

  4. Folgen Sie den Anweisungen auf dem Bildschirm. Um die im interaktiven Erlebnis bereitgestellten Standardoptionen zu akzeptieren, drücken Sie Enter.

    Anmerkung

    Für ist die Autorisierung HelloWorldFunction möglicherweise nicht definiert. Ist das in Ordnung? , stellen Sie sicher, dass Sie eintreteny.

  5. Rufen Sie die URL der bereitgestellten Anwendung ab:

    aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

  6. Rufen Sie den API-Endpunkt auf:

    curl -X GET <URL_FROM_PREVIOUS_STEP>

    Wenn der Link erfolgreich ausgeführt wurde, sehen Sie die folgende Antwort:

    {"message":"hello world"}

  7. Führen Sie sam traces aus, um die Traces für die Funktion zu erhalten.

    sam traces

    Das Nachverfolgungsergebnis sieht folgendermaßen aus:

    New XRay Service Graph
  Start time: 2025-02-03 14:31:48+01:00
  End time: 2025-02-03 14:31:48+01:00
  Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-y9Iu1FLJJBGD - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 5.587
  Reference Id: 1 - client - sam-app-HelloWorldFunction-y9Iu1FLJJBGD - Edges: [0]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 3] at (2025-02-03T14:31:48.500000) with id (1-63dd0cc4-3c869dec72a586875da39777) and duration (5.603s)
 - 5.587s - sam-app-HelloWorldFunction-y9Iu1FLJJBGD [HTTP: 200]
 - 4.053s - sam-app-HelloWorldFunction-y9Iu1FLJJBGD
   - 1.181s - Initialization
   - 4.037s - Invocation
     - 1.981s - ## handleRequest
       - 1.840s - ## getPageContents
   - 0.000s - Overhead

  8. Dies ist ein öffentlicher API-Endpunkt, der über das Internet zugänglich ist. Es wird empfohlen, dass Sie den Endpunkt nach dem Testen löschen.

    sam delete

Verwenden von Powertools für AWS Lambda (Java) und die AWS CDK zur Rückverfolgung

Folgen Sie den unten stehenden Schritten, um eine Hello World Java-Beispielanwendung mit integrierten Powertools for AWS Lambda (Java) -Modulen mithilfe von herunterzuladen, zu erstellen und bereitzustellen. AWS CDK Diese Anwendung implementiert ein grundlegendes API-Backend und verwendet Powertools zum Ausgeben von Protokollen, Metriken und Traces. Es besteht aus einem Amazon-API-Gateway-Endpunkt und einer Lambda-Funktion. Wenn Sie eine GET-Anfrage an den API Gateway-Endpunkt senden, ruft die Lambda-Funktion auf, sendet Protokolle und Metriken im Embedded Metric Format an und sendet CloudWatch Traces an. AWS X-Ray Die Funktion gibt eine Hello-World-Nachricht zurück.

Voraussetzungen

Zur Durchführung der Schritte in diesem Abschnitt benötigen Sie Folgendes:

Stellen Sie ein Beispiel bereit AWS CDK Anwendung

  1. Erstellen Sie ein Projektverzeichnis für Ihre neue Anwendung.

    mkdir hello-world
cd hello-world

  2. Initialisieren Sie die App.

    cdk init app --language java

  3. Erstellen Sie ein Maven-Projekt mit dem folgenden Befehl:

    mkdir app
cd app
mvn archetype:generate -DgroupId=helloworld -DartifactId=Function -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

  4. Öffnen Sie pom.xml im hello-world\app\Function-Verzeichnis und ersetzen Sie den vorhandenen Code durch den folgenden Code, der Abhängigkeiten und Maven-Plugins für Powertools enthält.

    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>helloworld</groupId>
  <artifactId>Function</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Function</name>
  <url>http://maven.apache.org</url>
<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <log4j.version>2.17.2</log4j.version>
</properties>
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>software.amazon.lambda</groupId>
            <artifactId>powertools-tracing</artifactId>
            <version>1.3.0</version>
        </dependency>
        <dependency>
            <groupId>software.amazon.lambda</groupId>
            <artifactId>powertools-metrics</artifactId>
            <version>1.3.0</version>
        </dependency>
        <dependency>
            <groupId>software.amazon.lambda</groupId>
            <artifactId>powertools-logging</artifactId>
            <version>1.3.0</version>
        </dependency>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-lambda-java-core</artifactId>
            <version>1.2.2</version>
        </dependency>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-lambda-java-events</artifactId>
            <version>3.11.1</version>
        </dependency>
  </dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>aspectj-maven-plugin</artifactId>
            <version>1.14.0</version>
            <configuration>
                <source>${maven.compiler.source}</source>
                <target>${maven.compiler.target}</target>
                <complianceLevel>${maven.compiler.target}</complianceLevel>
                <aspectLibraries>
                    <aspectLibrary>
                        <groupId>software.amazon.lambda</groupId>
                        <artifactId>powertools-tracing</artifactId>
                    </aspectLibrary>
                    <aspectLibrary>
                        <groupId>software.amazon.lambda</groupId>
                        <artifactId>powertools-metrics</artifactId>
                    </aspectLibrary>
                    <aspectLibrary>
                        <groupId>software.amazon.lambda</groupId>
                        <artifactId>powertools-logging</artifactId>
                    </aspectLibrary>
                </aspectLibraries>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.4.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <transformers>
                                <transformer
                                        implementation="com.github.edwgiz.maven_shade_plugin.log4j2_cache_transformer.PluginsCacheFileTransformer">
                                </transformer>
                            </transformers>
                            <createDependencyReducedPom>false</createDependencyReducedPom>
                            <finalName>function</finalName>

                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>com.github.edwgiz</groupId>
                        <artifactId>maven-shade-plugin.log4j2-cachefile-transformer</artifactId>
                        <version>2.15</version>
                    </dependency>
                </dependencies>
        </plugin>
    </plugins>
</build>
</project>

  5. Erstellen Sie das hello-world\app\src\main\resource-Verzeichnis und erstellen Sie log4j.xml für die Protokollkonfiguration.

    mkdir -p src/main/resource
cd src/main/resource
touch log4j.xml

  6. Öffnen Sie log4j.xml und fügen Sie den folgenden Code hinzu.

    <?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <Console name="JsonAppender" target="SYSTEM_OUT">
            <JsonTemplateLayout eventTemplateUri="classpath:LambdaJsonLayout.json" />
        </Console>
    </Appenders>
    <Loggers>
        <Logger name="JsonLogger" level="INFO" additivity="false">
            <AppenderRef ref="JsonAppender"/>
        </Logger>
        <Root level="info">
            <AppenderRef ref="JsonAppender"/>
        </Root>
    </Loggers>
</Configuration>

  7. Öffnen Sie App.java aus dem hello-world\app\Function\src\main\java\helloworld-Verzeichnis und ersetzen Sie den vorhandenen Code durch den folgenden Code. Dies ist der Code für die Lambda-Funktion.

    package helloworld;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;
import java.util.stream.Collectors;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import software.amazon.lambda.powertools.logging.Logging;
import software.amazon.lambda.powertools.metrics.Metrics;
import software.amazon.lambda.powertools.tracing.CaptureMode;
import software.amazon.lambda.powertools.tracing.Tracing;

import static software.amazon.lambda.powertools.tracing.CaptureMode.*;

/**
 * Handler for requests to Lambda function.
 */
public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
    Logger log = LogManager.getLogger(App.class);


    @Logging(logEvent = true)
    @Tracing(captureMode = DISABLED)
    @Metrics(captureColdStart = true)
    public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
        Map<String, String> headers = new HashMap<>();
        headers.put("Content-Type", "application/json");
        headers.put("X-Custom-Header", "application/json");

        APIGatewayProxyResponseEvent response = new APIGatewayProxyResponseEvent()
                .withHeaders(headers);
        try {
            final String pageContents = this.getPageContents("https://checkip.amazonaws.com");
            String output = String.format("{ \"message\": \"hello world\", \"location\": \"%s\" }", pageContents);

            return response
                    .withStatusCode(200)
                    .withBody(output);
        } catch (IOException e) {
            return response
                    .withBody("{}")
                    .withStatusCode(500);
        }
    }
    @Tracing(namespace = "getPageContents")
    private String getPageContents(String address) throws IOException {
        log.info("Retrieving {}", address);
        URL url = new URL(address);
        try (BufferedReader br = new BufferedReader(new InputStreamReader(url.openStream()))) {
            return br.lines().collect(Collectors.joining(System.lineSeparator()));
        }
    }
}

  8. Öffnen Sie HelloWorldStack.java aus dem hello-world\src\main\java\com\myorg-Verzeichnis und ersetzen Sie den vorhandenen Code durch den folgenden Code. Dieser Code verwendet den Lambda-Konstruktor und den ApiGatewayv 2-Konstruktor, um eine REST-API und eine Lambda-Funktion zu erstellen.

    package com.myorg;

import software.amazon.awscdk.*;
import software.amazon.awscdk.services.apigatewayv2.alpha.*;
import software.amazon.awscdk.services.apigatewayv2.integrations.alpha.HttpLambdaIntegration;
import software.amazon.awscdk.services.apigatewayv2.integrations.alpha.HttpLambdaIntegrationProps;
import software.amazon.awscdk.services.lambda.Code;
import software.amazon.awscdk.services.lambda.Function;
import software.amazon.awscdk.services.lambda.FunctionProps;
import software.amazon.awscdk.services.lambda.Runtime;
import software.amazon.awscdk.services.lambda.Tracing;
import software.amazon.awscdk.services.logs.RetentionDays;
import software.amazon.awscdk.services.s3.assets.AssetOptions;
import software.constructs.Construct;

import java.util.Arrays;
import java.util.List;

import static java.util.Collections.singletonList;
import static software.amazon.awscdk.BundlingOutput.ARCHIVED;

public class HelloWorldStack extends Stack {
    public HelloWorldStack(final Construct scope, final String id) {
        this(scope, id, null);
    }

    public HelloWorldStack(final Construct scope, final String id, final StackProps props) {
        super(scope, id, props);

        List<String> functionPackagingInstructions = Arrays.asList(
                "/bin/sh",
                "-c",
                "cd Function " +
                        "&& mvn clean install " +
                        "&& cp /asset-input/Function/target/function.jar /asset-output/"
        );
        BundlingOptions.Builder builderOptions = BundlingOptions.builder()
                .command(functionPackagingInstructions)
                .image(Runtime.JAVA_11.getBundlingImage())
                .volumes(singletonList(
                        // Mount local .m2 repo to avoid download all the dependencies again inside the container
                        DockerVolume.builder()
                                .hostPath(System.getProperty("user.home") + "/.m2/")
                                .containerPath("/root/.m2/")
                                .build()
                ))
                .user("root")
                .outputType(ARCHIVED);

        Function function = new Function(this, "Function", FunctionProps.builder()
                .runtime(Runtime.JAVA_11)
                .code(Code.fromAsset("app", AssetOptions.builder()
                        .bundling(builderOptions
                                .command(functionPackagingInstructions)
                                .build())
                        .build()))
                .handler("helloworld.App::handleRequest")
                .memorySize(1024)
                .tracing(Tracing.ACTIVE)
                .timeout(Duration.seconds(10))
                .logRetention(RetentionDays.ONE_WEEK)
                .build());

        HttpApi httpApi = new HttpApi(this, "sample-api", HttpApiProps.builder()
                .apiName("sample-api")
                .build());

        httpApi.addRoutes(AddRoutesOptions.builder()
                .path("/")
                .methods(singletonList(HttpMethod.GET))
                .integration(new HttpLambdaIntegration("function", function, HttpLambdaIntegrationProps.builder()
                        .payloadFormatVersion(PayloadFormatVersion.VERSION_2_0)
                        .build()))
                .build());

        new CfnOutput(this, "HttpApi", CfnOutputProps.builder()
                .description("Url for Http Api")
                .value(httpApi.getApiEndpoint())
                .build());
    }
}

  9. Öffnen Sie pom.xml aus dem hello-world-Verzeichnis und ersetzen Sie den vorhandenen Code durch den folgenden Code.

    <?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
         xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.myorg</groupId>
    <artifactId>hello-world</artifactId>
    <version>0.1</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <cdk.version>2.70.0</cdk.version>
        <constructs.version>[10.0.0,11.0.0)</constructs.version>
        <junit.version>5.7.1</junit.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.0.0</version>
                <configuration>
                    <mainClass>com.myorg.HelloWorldApp</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <!-- AWS Cloud Development Kit -->
        <dependency>
            <groupId>software.amazon.awscdk</groupId>
            <artifactId>aws-cdk-lib</artifactId>
            <version>${cdk.version}</version>
        </dependency>
        <dependency>
            <groupId>software.constructs</groupId>
            <artifactId>constructs</artifactId>
            <version>${constructs.version}</version>
        </dependency>
        <dependency>
          <groupId>org.junit.jupiter</groupId>
          <artifactId>junit-jupiter</artifactId>
          <version>${junit.version}</version>
          <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>software.amazon.awscdk</groupId>
            <artifactId>apigatewayv2-alpha</artifactId>
            <version>${cdk.version}-alpha.0</version>
        </dependency>
        <dependency>
            <groupId>software.amazon.awscdk</groupId>
            <artifactId>apigatewayv2-integrations-alpha</artifactId>
            <version>${cdk.version}-alpha.0</version>
        </dependency>
    </dependencies>
</project>

  10. Stellen Sie sicher, dass Sie sich im hello-world Verzeichnis befinden, und stellen Sie Ihre Anwendung bereit.

    cdk deploy

  11. Rufen Sie die URL der bereitgestellten Anwendung ab:

    aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?OutputKey==`HttpApi`].OutputValue' --output text

  12. Rufen Sie den API-Endpunkt auf:

    curl -X GET <URL_FROM_PREVIOUS_STEP>

    Wenn der Link erfolgreich ausgeführt wurde, sehen Sie die folgende Antwort:

    {"message":"hello world"}

  13. Führen Sie sam traces aus, um die Traces für die Funktion zu erhalten.

    sam traces

    Das Nachverfolgungsergebnis sieht folgendermaßen aus:

    New XRay Service Graph
  Start time: 2025-02-03 14:59:50+00:00
  End time: 2025-02-03 14:59:50+00:00
  Reference Id: 0 - (Root) AWS::Lambda - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [1]
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.924
  Reference Id: 1 - AWS::Lambda::Function - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: []
   Summary_statistics:
     - total requests: 1
     - ok count(2XX): 1
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0.016
  Reference Id: 2 - client - sam-app-HelloWorldFunction-YBg8yfYtOc9j - Edges: [0]
   Summary_statistics:
     - total requests: 0
     - ok count(2XX): 0
     - error count(4XX): 0
     - fault count(5XX): 0
     - total response time: 0

XRay Event [revision 1] at (2025-02-03T14:59:50.204000) with id (1-63dd2166-434a12c22e1307ff2114f299) and duration (0.924s)
 - 0.924s - sam-app-HelloWorldFunction-YBg8yfYtOc9j [HTTP: 200]
 - 0.016s - sam-app-HelloWorldFunction-YBg8yfYtOc9j
   - 0.739s - Initialization
   - 0.016s - Invocation
     - 0.013s - ## lambda_handler
       - 0.000s - ## app.hello
   - 0.000s - Overhead

  14. Dies ist ein öffentlicher API-Endpunkt, der über das Internet zugänglich ist. Es wird empfohlen, dass Sie den Endpunkt nach dem Testen löschen.

    cdk destroy

Verwenden von ADOT zur Instrumentierung Ihrer Java-Funktionen

ADOT bietet vollständig verwaltete Lambda-Ebenen, die alles packen, was Sie zum Sammeln von Telemetriedaten mit dem OTel-SDK benötigen. Indem Sie diese Ebene verwenden, können Sie Ihre Lambda-Funktionen instrumentieren, ohne einen Funktionscode ändern zu müssen. Sie können Ihren Ebenen auch für die benutzerdefinierte Initialisierung von OTel konfigurieren. Weitere Informationen finden Sie unter Benutzerdefinierte Konfiguration für den ADOT Collector auf Lambda in der ADOT-Dokumentation.

Für Java-Laufzeiten können Sie zwischen zwei Ebenen wählen, die verbraucht werden sollen:

Anweisungen zur Konvertierung von Lambda Telemetrie-API-Ereignissen in Spans finden Sie unter. OpenTelemetry Lambda Telemetry API-Ereignisobjekte in Spans konvertieren OpenTelemetry

Verwenden Sie das X-Ray SDK zur Instrumentierung Ihrer Java-Funktionen

Um Daten über Aufrufe aufzuzeichnen, die Ihre Funktion an andere Ressourcen und Dienste in Ihrer Anwendung tätigt, können Sie das X-Ray SDK für Java zu Ihrer Build-Konfiguration hinzufügen. Das folgende Beispiel zeigt eine Gradle-Build-Konfiguration, die die Bibliotheken enthält, die die automatische Instrumentierung von AWS SDK for Java 2.x Clients aktivieren.

Beispiel build.gradle — Abhängigkeiten verfolgen
dependencies {
    implementation platform('software.amazon.awssdk:bom:2.16.1')
    implementation platform('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
    ...
    implementation 'com.amazonaws:aws-xray-recorder-sdk-core'
    implementation 'com.amazonaws:aws-xray-recorder-sdk-aws-sdk'
    implementation 'com.amazonaws:aws-xray-recorder-sdk-aws-sdk-v2-instrumentor'
    ...
}

Nachdem Sie die richtigen Abhängigkeiten hinzugefügt und die erforderlichen Codeänderungen vorgenommen haben, aktivieren Sie die Ablaufverfolgung in der Konfiguration Ihrer Funktion über die Lambda-Konsole oder die API.

Aktivieren der Nachverfolgung mit der Lambda-Konsole

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

So aktivieren Sie die aktive Nachverfolgung

  1. Öffnen Sie die Seite Funktionen der Lambda-Konsole.

  2. Wählen Sie eine Funktion aus.

  3. Wählen Sie Configuration (Konfiguration) und dann Monitoring and operations tools (Überwachungs- und Produktionstools).

  4. Wählen Sie unter Zusätzliche Überwachungstools die Option Bearbeiten aus.

  5. Wählen Sie unter CloudWatch Anwendungssignale die Option Für Lambda-Service-Traces aktivieren aus. AWS X-Ray

  6. Wählen Sie Speichern.

Aktivieren der Nachverfolgung mit der Lambda-API

Konfigurieren Sie die Ablaufverfolgung für Ihre Lambda-Funktion mit dem AWS CLI oder AWS SDK und verwenden Sie die folgenden API-Operationen:

Der folgende AWS CLI Beispielbefehl aktiviert die aktive Ablaufverfolgung für eine Funktion namens 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.

Die Protokollierung wird aktiviert mit CloudFormation

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

Beispiel function-inline.yml — Konfiguration verfolgen
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 Tracing Eigenschaft.

Beispiel template.yml — Konfiguration verfolgen
Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interpretieren einer Ablaufverfolgung X-Ray

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 die AWSXRayDaemonWriteAccess Richtlinie der Ausführungsrolle hinzu.

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

Ein Diagramm, das zwei separate Anwendungen und ihre jeweiligen Servicezuordnungen zeigt X-Ray

X-Ray verfolgt nicht alle Anfragen an Ihre Anwendung zurück. X-Ray wendet einen Stichprobenalgorithmus an, um sicherzustellen, dass die Ablaufverfolgung effizient ist, und liefert gleichzeitig eine repräsentative Stichprobe aller Anfragen. Die Samplingrate beträgt 1 Anforderung pro Sekunde und 5 Prozent aller weiteren Anforderungen. Sie können die X-Ray Samplingrate für Ihre Funktionen nicht konfigurieren.

In X-Ray zeichnet ein Trace Informationen über eine Anfrage auf, die von einem oder mehreren Diensten verarbeitet wird. Lambda zeichnet 2 Segmente pro Trace auf, wodurch zwei Knoten im Dienstgraphen entstehen. In der folgenden Abbildung werden diese beiden Knoten hervorgehoben:

Eine X-Ray Servicekarte mit einer einzigen Funktion.

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.

Ein X-Ray Trace, der die Latenz in jedem Untersegment eines bestimmten Lambda-Aufrufs anzeigt.

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

Anmerkung

AWS implementiert derzeit Änderungen am Lambda-Service. Aufgrund dieser Änderungen können geringfügige Unterschiede in Struktur und Inhalt der Systemprotokollmeldungen und Trace-Segmente auftreten, die von verschiedenen Lambda-Funktionen in Ihrem AWS-Konto.

Der hier gezeigte Beispiel-Trace veranschaulicht das Funktionssegment im alten Stil. Die Unterschiede zwischen den Segmenten im alten und im neuen Stil werden in den folgenden Abschnitten beschrieben.

Diese Änderungen werden in den kommenden Wochen implementiert, und alle Funktionen AWS-Regionen außer China und den GovCloud Regionen werden auf die Verwendung der Protokollnachrichten und Trace-Segmente im neuen Format umgestellt.

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

  • Initialisierung – Stellt die Zeit dar, die für das Laden Ihrer Funktion und das Ausführen des Initialisierungscodes aufgewendet wurde. Dieses Untersegment erscheint nur für das erste Ereignis, das jede Instance Ihrer Funktion verarbeitet.

  • Invocation (Aufruf) – Stellt die Zeit dar, die beim Ausführen Ihres Handler-Codes vergeht.

  • Overhead (Aufwand) – Stellt die Zeit dar, die von der Lambda-Laufzeitumgebung bei der Verarbeitung des nächsten Ereignisses verbraucht wird.

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

Anmerkung

Zu den SnapStart-Funktionen gehört auch ein Restore-Teilsegment. Das Teilsegment Restore zeigt die Zeit an, die Lambda benötigt, um einen Snapshot wiederherzustellen, die Laufzeit zu laden und vorhandene Laufzeit-Hooks nach der Wiederherstellung auszuführen. Der Prozess der Wiederherstellung von Snapshots kann Zeit beinhalten, die für Aktivitäten außerhalb der MicroVM aufgewendet wird. Diese Zeit wird im Restore-Untersegment erfasst. Die Zeit, die Sie außerhalb der microVM für die Wiederherstellung eines Snapshots aufwenden, wird Ihnen nicht in Rechnung gestellt.

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

Preisgestaltung

Im Rahmen des kostenlosen Kontingents können Sie X-Ray Tracing jeden Monat bis zu einem bestimmten Limit kostenlos nutzen. AWS Bei Überschreitung dieses Schwellenwerts X-Ray fallen Gebühren für das Speichern und Abrufen von Traces an. Weitere Informationen finden Sie unter AWS X-Ray Preise.

Speichern von Laufzeitabhängigkeiten in einer Ebene (X-Ray SDK)

Wenn Sie das X-Ray SDK verwenden, um AWS SDK-Clients Ihren Funktionscode zu instrumentieren, kann Ihr Bereitstellungspaket ziemlich umfangreich werden. Um zu vermeiden, dass bei jeder Aktualisierung Ihres Funktionscodes Laufzeitabhängigkeiten hochgeladen werden, packen Sie das X-Ray SDK in eine Lambda-Ebene.

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

Beispiel template.yml — Ebene „Abhängigkeiten“
Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: build/distributions/blank-java.zip
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-java-lib
      Description: Dependencies for the blank-java sample app.
      ContentUri: build/blank-java-lib.zip
      CompatibleRuntimes:
        - java25

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 Änderungen an der Build-Konfiguration, um das Layer-Archiv vor der Bereitstellung zu generieren. Ein funktionierendes Beispiel finden Sie in der https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/java-basic Java-Basic-Beispielanwendung unter. GitHub

X-Ray Ablaufverfolgung in Beispielanwendungen (SDK) X-Ray

Das GitHub Repositorium für dieses Handbuch enthält Beispielanwendungen, die die Verwendung von X-Ray Tracing demonstrieren. Jede Beispielanwendung enthält Skripts für eine einfache Bereitstellung und Bereinigung, eine AWS SAM Vorlage und unterstützende Ressourcen.

Lambda-Beispielanwendungen in Java

  • example-java – Eine Java-Funktion, die zeigt, wie Sie Lambda zur Bearbeitung von Aufträgen verwenden können. Diese Funktion veranschaulicht, wie ein benutzerdefiniertes Eingabeereignisobjekt definiert und deserialisiert, das AWS SDK verwendet und die Ausgabe protokolliert wird.

  • Java-Basis – Eine Sammlung minimaler Java-Funktionen mit Einheitentests und variabler Protokollierungskonfiguration.

  • Java-Ereignisse – Eine Sammlung von Java-Funktionen, die Grundcode für den Umgang mit Ereignissen aus verschiedenen Services wie Amazon API Gateway, Amazon SQS und Amazon Kinesis enthalten. Diese Funktionen verwenden die neueste Version der aws-lambda-java-events-Bibliothek (3.0.0 und neuer). Für diese Beispiele ist das AWS SDK nicht als Abhängigkeit erforderlich.

  • s3-java – Eine Java-Funktion die Benachrichtigungsereignisse aus Amazon S3 verarbeitet und die Java Class Library (JCL) verwendet, um Miniaturansichten aus hochgeladenen Image-Dateien zu erstellen.

  • layer-java – Eine Java-Funktion, die veranschaulicht, wie Sie mit einer Lambda-Ebene Abhängigkeiten getrennt von Ihrem Kernfunktionscode packen können.

Für alle Beispielanwendungen ist die aktive Ablaufverfolgung für Lambda-Funktionen aktiviert. Die s3-java Anwendung zeigt beispielsweise die automatische Instrumentierung von AWS SDK for Java 2.x Clients, die Segmentverwaltung für Tests, benutzerdefinierte Untersegmente und die Verwendung von Lambda-Layern zum Speichern von Laufzeitabhängigkeiten.