使用動力工具進行 AWS Lambda （Python）和跟 AWS SAM 踪使用動力工具 AWS Lambda （Python）和跟 AWS CDK 踪用ADOT來檢測你的 Python 函數使用 X-Ray SDK 檢測您的 Python 函數透過 Lambda 主控台來啟用追蹤使用 Lambda 啟用追蹤 API 使用啟動追蹤 AWS CloudFormation 解讀 X-Ray 追蹤在圖層中存儲運行時依賴關係（X-RaySDK）

檢測 Python 代碼 AWS Lambda

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

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

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

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

重要

X-Ray 和 Powertools AWS Lambda SDKs 是由 AWS提供的緊密集成的儀器解決方案的一部分。ADOTLambda 層是業界範圍內追蹤儀器標準的一部分，一般會收集更多資料，但可能不適用於所有使用案例。您可以使用任一解決方案在 X-Ray 中實作 end-to-end 追蹤。要了解有關在它們之間進行選擇的更多信息，請參閱選擇開放遙測發行 AWS 版和 X-Ray SDKs。

使用動力工具進行 AWS Lambda （Python）和跟 AWS SAM 踪

請按照下面的步驟下載，構建和部署示例你好世界 Python 應用程序集成動力工具 AWS Lambda （Python）模塊使用 AWS SAM. 此應用程序實現了基本的API後端，並使用 Powertools 發出日誌，指標和跟踪。它由一個 Amazon API 網關端點和一個 Lambda 函數組成。當您將GET請求傳送至API閘道端點時，Lambda 函數會呼叫、使用內嵌指標格式將記錄和指標傳送至 CloudWatch，並將追蹤傳送至 AWS X-Ray。函數會傳回 hello world 訊息。

必要條件

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

Python 3.9
AWS CLI 第二版
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 採樣率。

使用動力工具 AWS Lambda （Python）和跟 AWS CDK 踪

請按照下面的步驟下載，構建和部署示例你好世界 Python 應用程序集成動力工具 AWS Lambda （Python）模塊使用 AWS CDK. 此應用程序實現了基本的API後端，並使用 Powertools 發出日誌，指標和跟踪。它由一個 Amazon API 網關端點和一個 Lambda 函數組成。當您將GET請求傳送至API閘道端點時，Lambda 函數會呼叫、使用內嵌指標格式將記錄和指標傳送至 CloudWatch，並將追蹤傳送至 AWS X-Ray。函數會傳回 hello world 訊息。

必要條件

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

Python 3.9
AWS CLI 第二版
AWS CDK 第二版
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 的環境變數，並將記錄保留設定為一週，以及建立. ApiGatewayv REST API


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 層，可封裝使用 OTelSDK. 透過取用此層，您可以檢測 Lambda 函數，而無需修改任何函數程式碼。您還可以配置圖層以執行的自定義初始化OTel。如需詳細資訊，請參閱ADOT文件中的 Lambda 上ADOT收集器的自訂組態。

對於 Python 執行階段，您可以為 ADOTPython 新增受AWS 管理的 Lambda 層，以自動檢測您的函數。此層同時適用於 arm64 和 x86_64 架構。如需如何新增此層的詳細指示，請參閱ADOT文件中的 Python OpenTelemetry Lambda Support 發行AWS 版。

使用 X-Ray SDK 檢測您的 Python 函數

若要記錄 Lambda 函數對應用程式中其他資源所進行之呼叫的詳細資料，您也可以使用適用於 Python 的 AWS X-Ray SDK。若要取得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 下，打開 主動追蹤 。
選擇 Save (儲存)。

使用 Lambda 啟用追蹤 API

使用 AWS CLI 或設定 Lambda 函數的追蹤 AWS SDK，請使用下列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 個區段的追蹤。兩者都被命名為我的函數，但一個具有的起源AWS::Lambda，另一個具有的AWS::Lambda::Function起源。如果AWS::Lambda區段顯示錯誤，表示 Lambda 服務發生問題。如果AWS::Lambda::Function區段顯示錯誤，表示您的函數發生問題。

此範例會展開區AWS::Lambda::Function段以顯示其三個子區段。

注意

AWS 目前正在對 Lambda 服務實作變更。由於這些變更，您可能會看到系統記錄訊息的結構和內容，以及. 中不同 Lambda 函數所發出的追蹤區段之間的 AWS 帳戶細微差異。

此處顯示的示例跟踪說明了舊式函數段。以下段落說明舊樣式和新樣式區段之間的差異。

這些變更將在未來幾週內實施，除了中國和 GovCloud 地區以 AWS 區域外的所有功能都將轉換為使用新格式的日誌訊息和追蹤區段。

舊式函數段包含以下子段：

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

新樣式函數段不包含Invocation子段。相反，客戶子段直接附加到功能段。如需舊式和新型式函數區段結構的詳細資訊，請參閱了解 X-Ray 追蹤。

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

定價

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

在圖層中存儲運行時依賴關係（X-RaySDK）

如果您使用 X-Ray 檢SDK測 AWS SDK客戶端的功能代碼，則您的部署包可能會變得相當大。若要避免每次更新函數程式碼時都上傳執行階段相依性，請將 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 建置

檢測 Python 代碼 AWS Lambda

重要

章節

使用動力工具進行 AWS Lambda （Python）和跟 AWS SAM 踪

必要條件

部署範例 AWS SAM 應用程式

注意

使用動力工具 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-RaySDK）

範例 template.yml - 相依性層

範例功能-跟踪 AWS SDK客戶端