使用 Powertools for AWS Lambda (Python) 和 AWS SAM 進行追蹤使用 Powertools for AWS Lambda (Python) 和 AWS CDK 進行追蹤使用 ADOT 來檢測您的 Python 函數使用 X-Ray SDK 來檢測 Python 功能透過 Lambda 主控台來啟用追蹤透過 Lambda API 啟用追蹤使用 AWS CloudFormation 啟用追蹤解讀 X-Ray 追蹤將執行時間相依項存放存在層中 (X-Ray SDK)

在 AWS Lambda 中檢測 Python 程式碼

Lambda 會與 AWS X-Ray 整合，以協助您追蹤、偵錯和最佳化 Lambda 應用程式。您可以使用 X-Ray 來追蹤請求，因為它會周遊您應用程式中的資源，其中可能包含 Lambda 函數和其他 AWS 服務。

若要將追蹤資料傳送至 X-Ray，您可以使用以下三個 SDK 庫之一：

AWS適用於 OpenTelemetry (ADOT) 的發行版 — 安全、可生產就緒且AWS支援的 (OTel) SDK 發行版本 OpenTelemetry 。
適用於 Python 的 AWS X-Ray SDK – 用於生成追蹤資料並將其傳送至 X-Ray 的 SDK。
Powertools for AWS Lambda (Python)：開發人員工具組，可實作無伺服器最佳實務並提高開發人員速度。

每個 SDK 均提供將遙測資料傳送至 X-Ray 服務的方法。然後，您可以使用 X-Ray 來檢視、篩選應用程式的效能指標並獲得洞察，從而識別問題和進行最佳化的機會。

重要

X-Ray 和適用於 AWS Lambda SDK 的 Powertools 包含在 AWS 提供的緊密整合檢測解決方案中。ADOT Lambda Layers 是用於追蹤檢測之業界通用標準的一部分，這類檢測一般會收集更多資料，但可能不適用於所有使用案例。您可以使用任一解決方案在 X-Ray 中實作 end-to-end 追蹤。若要深入了解如何在兩者之間做選擇，請參閱在 AWS Distro for OpenTelemetry 和 X-Ray SDK 之間進行選擇。

章節

使用 Powertools for AWS Lambda (Python) 和 AWS SAM 進行追蹤
使用 Powertools for AWS Lambda (Python) 和 AWS CDK 進行追蹤
使用 ADOT 來檢測您的 Python 函數
使用 X-Ray SDK 來檢測 Python 功能
透過 Lambda 主控台來啟用追蹤
透過 Lambda API 啟用追蹤
使用 AWS CloudFormation 啟用追蹤
解讀 X-Ray 追蹤
將執行時間相依項存放存在層中 (X-Ray SDK)

使用 Powertools for AWS Lambda (Python) 和 AWS SAM 進行追蹤

請依照以下步驟操作，使用 AWS SAM 透過整合式 Powertools for AWS Lambda (Python) 模組，下載、建置和部署範例 Hello World Python 應用程式。此應用程式實作了基本 API 後端，並使用 Powertools 發送日誌、指標和追蹤。其包含 Amazon API Gateway 端點和 Lambda 函數。當您將 GET 請求傳送至 API Gateway 端點時，Lambda 函數會叫用、使用內嵌指標格式將記錄和指標傳送至 CloudWatch，並將追蹤傳送至AWS X-Ray。函數會傳回 hello world 訊息。

必要條件

若要完成本節中的步驟，您必須執行下列各項：

Python 3.9
AWS CLI 第 2 版
AWS SAM CLI 1.75 版或更新版本如果您使用舊版 AWS SAM CLI，請參閱升級 AWS SAM CLI。

部署範例 AWS SAM 應用程式

使用 Hello World Python 範本來初始化應用程式。


sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.9 --no-tracing

建置應用程式。
```
cd sam-app && sam build
```
部署應用程式。
```
sam deploy --guided
```
依照螢幕上的提示操作。若要接受互動體驗中提供的預設選項，請按下 Enter。

注意
因為HelloWorldFunction 可能沒有定義授權，這可以嗎？ ，請務必輸入y。

取得已部署應用程式的 URL：


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

調用 API 端點：
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
成功的話，您將會看到以下回應：
```
{"message":"hello world"}
```

若要取得函數的追蹤，請執行 sam 追蹤。


sam traces

追蹤輸出如下：


New XRay Service Graph
  Start time: 2023-02-03 14:59:50+00:00
  End time: 2023-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 (2023-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

這是可透過網際網路存取的公有 API 端點。建議您在測試後刪除端點。
```
sam delete
```

X-Ray 無法追蹤應用程式的所有請求。X-Ray 會套用取樣演算法以確保追蹤的效率，同時仍提供所有請求的代表範本。取樣率為每秒 1 次請求和 5% 的額外請求。

注意

您無法針對函數設定 X-Ray 取樣率。

使用 Powertools for AWS Lambda (Python) 和 AWS CDK 進行追蹤

請依照以下步驟操作，使用 AWS CDK 透過整合式 Powertools for AWS Lambda (Python) 模組，下載、建置和部署範例 Hello World Python 應用程式。此應用程式實作了基本 API 後端，並使用 Powertools 發送日誌、指標和追蹤。其包含 Amazon API Gateway 端點和 Lambda 函數。當您將 GET 請求傳送至 API Gateway 端點時，Lambda 函數會叫用、使用內嵌指標格式將記錄和指標傳送至 CloudWatch，並將追蹤傳送至AWS X-Ray。函數會傳回 hello world 訊息。

必要條件

若要完成本節中的步驟，您必須執行下列各項：

Python 3.9
AWS CLI 第 2 版
AWS CDK 第 2 版
AWS SAM CLI 1.75 版或更新版本如果您使用舊版 AWS SAM CLI，請參閱升級 AWS SAM CLI。

部署範例 AWS CDK 應用程式

為您的新應用程式建立專案目錄。
```
mkdir hello-world
cd hello-world
```
初始化應用程式。
```
cdk init app --language python
```
安裝 Python 相依項。
```
pip install -r requirements.txt
```
在根資料夾下建立 lambda_function 目錄。
```
mkdir lambda_function
cd lambda_function
```

建立檔案 app.py，並將下列程式碼新增至檔案。這是 Lambda 函數的程式碼。


from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools import Logger
from aws_lambda_powertools import Tracer
from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit

app = APIGatewayRestResolver()
tracer = Tracer()
logger = Logger()
metrics = Metrics(namespace="PowertoolsSample")

@app.get("/hello")
@tracer.capture_method
def hello():
    # adding custom metrics
    # See: https://docs.powertools.aws.dev/lambda-python/latest/core/metrics/
    metrics.add_metric(name="HelloWorldInvocations", unit=MetricUnit.Count, value=1)

    # structured log
    # See: https://docs.powertools.aws.dev/lambda-python/latest/core/logger/
    logger.info("Hello world API - HTTP 200")
    return {"message": "hello world"}

# Enrich logging with contextual information from Lambda
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
# Adding tracer
# See: https://docs.powertools.aws.dev/lambda-python/latest/core/tracer/
@tracer.capture_lambda_handler
# ensures metrics are flushed upon request completion/failure and capturing ColdStart metric
@metrics.log_metrics(capture_cold_start_metric=True)
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

開啟 hello_world 目錄。您應看到名稱為 hello_world_stack.py 的檔案。
```
cd ..
cd hello_world
```

開啟 hello_world_stack.py，並將下列程式碼新增至檔案。其中包含建立 Lambda 函數的 Lambda 建構函式、設定 Powertools 的環境變數，並將記錄保留設定為一週，以及建立 REST API 的 ApiGatewayv1 個建構函式。


from aws_cdk import (
    Stack,
    aws_apigateway as apigwv1,
    aws_lambda as lambda_,
    CfnOutput,
    Duration
)
from constructs import Construct

class HelloWorldStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Powertools Lambda Layer
        powertools_layer = lambda_.LayerVersion.from_layer_version_arn(
            self,
            id="lambda-powertools",
            # At the moment we wrote this example, the aws_lambda_python_alpha CDK constructor is in Alpha, o we use layer to make the example simpler
            # See https://docs.aws.amazon.com/cdk/api/v2/python/aws_cdk.aws_lambda_python_alpha/README.html
            # Check all Powertools layers versions here: https://docs.powertools.aws.dev/lambda-python/latest/#lambda-layer
            layer_version_arn=f"arn:aws:lambda:{self.region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:21"
        )

        function = lambda_.Function(self,
            'sample-app-lambda',
            runtime=lambda_.Runtime.PYTHON_3_9,
            layers=[powertools_layer],
            code = lambda_.Code.from_asset("./lambda_function/"),
            handler="app.lambda_handler",
            memory_size=128,
            timeout=Duration.seconds(3),
            architecture=lambda_.Architecture.X86_64,
            environment={
                "POWERTOOLS_SERVICE_NAME": "PowertoolsHelloWorld",
                "POWERTOOLS_METRICS_NAMESPACE": "PowertoolsSample",
                "LOG_LEVEL": "INFO"
            }
        )

        apigw = apigwv1.RestApi(self, "PowertoolsAPI", deploy_options=apigwv1.StageOptions(stage_name="dev"))

        hello_api = apigw.root.add_resource("hello")
        hello_api.add_method("GET", apigwv1.LambdaIntegration(function, proxy=True))

        CfnOutput(self, "apiUrl", value=f"{apigw.url}hello")

部署您的應用程式。
```
cd ..
cdk deploy
```

取得已部署應用程式的 URL：


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

調用 API 端點：
```
curl -X GET <URL_FROM_PREVIOUS_STEP>
```
成功的話，您將會看到以下回應：
```
{"message":"hello world"}
```

若要取得函數的追蹤，請執行 sam 追蹤。


sam traces

追蹤輸出如下：


New XRay Service Graph
  Start time: 2023-02-03 14:59:50+00:00
  End time: 2023-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 (2023-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

這是可透過網際網路存取的公有 API 端點。建議您在測試後刪除端點。
```
cdk destroy
```

使用 ADOT 來檢測您的 Python 函數

ADOT 提供全受管 Lambda 層，包含使用 OTel SDK 收集遙測資料所需的一切內容。透過取用此層，您可以檢測 Lambda 函數，而無需修改任何函數程式碼。您還可以將層設定為對 OTel 進行自訂初始化。如需詳細資訊，請參閱 ADOT 文件中的針對 Lambda 上的 ADOT 收集器進行自訂組態設定。

對於 Python 執行時間，您可以新增適用於 ADOT Python 的 AWS 受管 Lambda 層來自動檢測您的函數。此層同時適用於 arm64 和 x86_64 架構。有關如何添加此層的詳細說明，請參閱 AWSADOT 文檔中的 Python 的 OpenTelemetry Lambda Support 發行版。

使用 X-Ray SDK 來檢測 Python 功能

若要記錄 Lambda 函數對應用程式中其他資源所進行之呼叫的詳細資料，您也可以使用適用於 Python 的 AWS X-Ray SDK。若要取得開發套件，請將 aws-xray-sdk 套件新增至應用程式的相依性。

範例 requirements.txt


jsonpickle==1.3
aws-xray-sdk==2.4.3

在函數程式碼中，您可以使用 aws_xray_sdk.core 模組來修補 boto3 程式庫，藉此檢測 AWS SDK 用戶端。

範例函數 – 追蹤 AWS SDK 用戶端


import boto3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

logger = logging.getLogger()
logger.setLevel(logging.INFO)
patch_all()

client = boto3.client('lambda')
client.get_account_settings()

def lambda_handler(event, context):
    logger.info('## ENVIRONMENT VARIABLES\r' + jsonpickle.encode(dict(**os.environ)))
  ...

新增正確的依賴項並進行必要的程式碼變更後，請透過 Lambda 主控台或 API 在函數的組態中啟用追蹤。

透過 Lambda 主控台來啟用追蹤

若要使用控制台在 Lambda 函數上切換主動追蹤，請按照下列步驟操作：

開啟主動追蹤

開啟 Lambda 主控台中的函數頁面。
選擇一個函數。
選擇組態，然後選擇 監控和操作工具 。
選擇編輯。
在 X-Ray 下，打開 主動追蹤 。
選擇儲存。

透過 Lambda API 啟用追蹤

若要使用 AWS CLI 或 AWS SDK 在 Lambda 函數上設定追蹤，請使用下列 API 操作：

下列範例 AWS CLI 命令啟用對名稱為 my-function 之函數的主動追蹤。


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

追蹤模式是您發布函數版本時版本特定組態的一部分。您無法變更已發佈版本上的追蹤模式。

使用 AWS CloudFormation 啟用追蹤

若要在 AWS CloudFormation 範本中啟用對 AWS::Lambda::Function 資源的追蹤，請使用 TracingConfig 屬性。

範例 function-inline.yml - 追蹤組態


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

對於 AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function 資源，請使用 Tracing 屬性。

範例 template.yml - 追蹤組態


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

解讀 X-Ray 追蹤

您的函數需要將追蹤資料上傳至 X-Ray 的許可。當您在 Lambda 主控台中啟用追蹤時，Lambda 會將必要的許可新增至函數的執行角色。否則，請將AWSXRayDaemonWriteAccess原則新增至執行角色。

設定主動追蹤之後，您可以透過應用程式來觀察特定請求。X-Ray 服務圖顯示了有關應用程式及其所有元件的資訊。下列來自錯誤處理器範例應用程式的範例顯示了具有兩個函式的應用程式。主要函式會處理事件，有時會傳回錯誤。頂部的第二個函數處理出現在第一個日誌組中的錯誤，並使用 AWS SDK 調用 X-Ray，Amazon 簡單存儲服務（Amazon S3）和亞馬遜 CloudWatch 日誌。

注意

您無法針對函數設定 X-Ray 取樣率。

使用主動追蹤時，Lambda 會在每個追蹤上記錄 2 個區段，它在服務圖表上會建立兩個節點。下圖反白顯示了錯誤處理器範例應用程式中主要函數的兩個節點。

左側第一個節點代表接收調用請求的 Lambda 服務。第二個節點代表您特定的 Lambda 函數。下列範例顯示了具有這 2 個區段的追蹤。兩者都被命名為 my-function，但其中之一具有 AWS::Lambda 的來源，而另一個具有來源 AWS::Lambda::Function。

此範例會展開函數區段以顯示其子區段︰

初始化 - 表示載入函數和執行初始化程式碼所花費的時間。只有函數的每個執行個體所處理的第一個事件會顯示此子區段。
調用 – 表示執行處理常式程式碼所花費的時間。
額外負荷 - 表示 Lambda 執行期為做好準備以處理下一個事件所花費的時間。

您也可以檢測 HTTP 用戶端、記錄 SQL 查詢，以及建立具有註釋和中繼資料的自訂子區段。如需詳細資訊，請參閱《AWS X-Ray 開發人員指南》中的適用於 Python 的 AWS X-Ray SDK 許可。

定價

作為 AWS 免費方案的一部分，您可以每月免費使用 X-Ray 追蹤，但有一定限制。達到閾值後，X-Ray 會收取追蹤儲存及擷取的費用。如需詳細資訊，請參閱 AWS X-Ray 定價。

將執行時間相依項存放存在層中 (X-Ray SDK)

如果您使用 X-Ray 開發套件來測試 AWS 開發套件用戶端，您的函數程式碼、您的部署套件可能會變得相當大。為了避免每次更新函數程式碼時上傳執行時間相依性，請將 X-Ray SDK 封裝在一個 Lambda 層中。

以下範例會顯示存放適用於 Python 的 AWS X-Ray SDK 的 AWS::Serverless::LayerVersion 資源。

範例 template.yml - 相依性層


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

透過此組態，您只有在變更執行時間相依性時才會更新程式庫層。由於函數部署套件僅含有您的程式碼，因此有助於減少上傳時間。

為相依性建立圖層需要建置變更，才能在部署之前產生圖層封存。如需工作範例，請參閱 blank-python 範例應用程式。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

錯誤

使用 Ruby 建置

在 AWS Lambda 中檢測 Python 程式碼

重要

章節

使用 Powertools for AWS Lambda (Python) 和 AWS SAM 進行追蹤

必要條件

部署範例 AWS SAM 應用程式

注意

注意

使用 Powertools for AWS Lambda (Python) 和 AWS CDK 進行追蹤

必要條件

部署範例 AWS CDK 應用程式

使用 ADOT 來檢測您的 Python 函數

使用 X-Ray SDK 來檢測 Python 功能

範例 requirements.txt

範例 函數 – 追蹤 AWS SDK 用戶端

透過 Lambda 主控台來啟用追蹤

開啟主動追蹤

透過 Lambda API 啟用追蹤

使用 AWS CloudFormation 啟用追蹤

範例 function-inline.yml - 追蹤組態

範例 template.yml - 追蹤組態

解讀 X-Ray 追蹤

注意

定價

將執行時間相依項存放存在層中 (X-Ray SDK)

範例 template.yml - 相依性層

範例函數 – 追蹤 AWS SDK 用戶端