使用自訂設定在 Amazon ECS 上啟用 Application Signals

使用這些自訂設定說明，將 Amazon ECS 上的應用程式上架到 CloudWatch 應用程式訊號。您可以 OpenTelemetry 自行安裝並設定 CloudWatch 代理程式和 AWS 發行版。

重要

僅支援 awsvpc 網路模式。EC2 和 Fargate 啟動類型都受到支援。

在 Amazon ECS 叢集上，應用程式信號不會自動探索您的服務名稱。您必須在自訂設定期間指定服務名稱，而且您指定的名稱會顯示在「應用程式訊號」控制面板上。

步驟 1：在您的帳戶中啟用 Application Signals

如果尚未在此帳戶中啟用 Application Signals，則必須授予 Application Signals 所需的許可，以探索您的服務。為此，請執行下列操作。您的帳戶只需執行一次此操作。

為您的應用程式啟用 Application Signals

1. 請在以下位置開啟 CloudWatch 主控台。 https://console.aws.amazon.com/cloudwatch/

2. 在導覽窗格中，選擇服務。

3. 選擇開始探索您的服務。

4. 選取核取方塊，然後選擇開始探索服務。

   第一次在您的帳戶中完成此步驟會建立AWSServiceRoleForCloudWatchApplicationSignals服務連結角色。此角色會授予 Application Signals 下列許可：

   • xray:GetServiceGraph

   • logs:StartQuery

   • logs:GetQueryResults

   • cloudwatch:GetMetricData

   • cloudwatch:ListMetrics

   • tag:GetResources

   如需有關此角色的詳細資訊，請參閱 CloudWatch 應用程式訊號的服務連結角色權限。

步驟 2：建立 IAM 角色

您必須建立 IAM 角色。如果您已建立此角色，則可能需要為其新增權限。

• ECS 任務角色 — 容器使用此角色來執行。權限應該是您的應用程序需要的任何內容，再加上CloudWatchAgentServerPolicy。

如需建立 IAM 角色的詳細資訊，請參閱建立 IAM 角色。

步驟 3：準備 CloudWatch 代理程式組態

首先，在啟用 Application Signals 的情況下準備代理程式組態。若要執行此操作，請建立名為 /tmp/ecs-cwagent.json 的本機檔案。

{
  "traces": {
    "traces_collected": {
      "application_signals": {}
    }
  },
  "logs": {
    "metrics_collected": {
      "application_signals": {}
    }
  }
}

將此組態上傳至 SSM 參數存放區。若要進行這項動作，請輸入下列指令。在檔案中，將 $REGION 取代為實際區域名稱。

aws ssm put-parameter \
--name "ecs-cwagent" \
--type "String" \
--value "`cat /tmp/ecs-cwagent.json`" \
--region "$REGION"

步驟 4：向 CloudWatch 代理商檢測您的申請

下一步是檢測您的應用信號 CloudWatch 應用程序。

Java

透過代理程式在 Amazon ECS 上測試您的應用程式 CloudWatch

1. 首先，指定綁定掛載。在接下來的步驟中，該磁碟區將用於跨容器共用檔案。將在此程序的後續步驟中使用此綁定掛載。

   "volumes": [
     {
       "name": "opentelemetry-auto-instrumentation"
     }
   ]

2. 新增 CloudWatch 代理程式並行定義。因此，請將名為 ecs-cwagent 的新容器附加到應用程式的任務定義。將 $REGION 取代為實際區域名稱。將 $IMAGE 替換為 Amazon 彈性容器註冊表上最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 cloudwatch-agent。

   {
     "name": "ecs-cwagent",
     "image": "$IMAGE",
     "essential": true,
     "secrets": [
       {
         "name": "CW_CONFIG_CONTENT",
         "valueFrom": "ecs-cwagent"
       }
     ],
     "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-create-group": "true",
         "awslogs-group": "/ecs/ecs-cwagent",
         "awslogs-region": "$REGION",
         "awslogs-stream-prefix": "ecs"
       }
     }
   }

3. 將新容器 init 附加到應用程式的任務定義。用 OpenTelemetry Amazon ECR 映像庫發行AWS 版中的最新映像替換 $ IMAGE。

   {
     "name": "init",
     "image": "$IMAGE",
     "essential": false,
     "command": [
       "cp",
       "/javaagent.jar",
       "/otel-auto-instrumentation/javaagent.jar"
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation",
         "containerPath": "/otel-auto-instrumentation",
         "readOnly": false
       }
     ]
   }

4. 將下列環境變數新增至應用程式容器。您必須使用版本 1.32.2 或更高版本的 AWS 發行版來進行 Java 的 OpenTelemetry 自動檢測代理程式

   環境變數	啟用 Application Signals 的設定
   OTEL_RESOURCE_ATTRIBUTES	將下列資訊指定為鍵值配對： service.name 會設定服務名稱。這將顯示為 Application Signals 儀表板中應用程式的服務名稱。如果您不提供此索引鍵的值，則會使用預設值 UnknownService。 deployment.environment 會設定執行應用程式的環境。這將顯示為 Application Signals 儀表板中應用程式的 Hosted In 環境。如果未指定此值，則會使用的generic:default預設值。 此屬性金鑰僅供應用程式訊號使用，並會轉換為 X-Ray 追蹤註解和度 CloudWatch 量維度。 (選擇性) 若要啟用追蹤記錄關聯，請將其他環境變數aws.log.group.names設定為應用程式記錄檔的記錄群組名稱。如此一來，應用程式的追蹤就可以與此特定記錄群組中的相關記錄項目相關聯。對於這個變數，請以應用程式的記錄群組名稱取代 $YOUR_APPLGROUP。您還需要更改應用程序中的日誌配置。如需詳細資訊，請參閱 啟用追蹤記錄關聯。
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED	設定為true讓您的容器開始將 X-Ray 追蹤和 CloudWatch 度量傳送至應用程式訊號。
   OTEL_METRICS_EXPORTER	設定為 none 以停用其他指標匯出工具。
   OTEL_LOGS_EXPORTER	設定為可none關閉其他記錄匯出器。
   OTEL_EXPORTER_OTLP_PROTOCOL	設定為http/protobuf以使用 HTTP 將度量和追蹤傳送至應用程式訊號。
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT	設定為http://localhost:4316/v1/metrics可將量度傳送至並 CloudWatch 行。
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	設定為http://localhost:4316/v1/traces將軌跡傳送至 CloudWatch 邊車。
   OTEL_TRACES_SAMPLER	將此項設定為xray可將 X-Ray 設定為追蹤取樣器。
   OTEL_PROPAGATORS	設定xray為其中一個傳輸者。
   JAVA_TOOL_OPTIONS	設定為以儲存 Java 自動檢測" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"代理程式的發行版的路徑取代 AWS_ADOT_JAVA_指示 _ 路徑。 AWS OpenTelemetry 例如：/otel-auto-instrumentation/javaagent.jar

5. 掛載您在此程序步驟 1 中定義的磁碟區 opentelemetry-auto-instrumentation。

   對於 Java 應用程序，請使用以下內容。

   {
     "name": "my-app",
      ...
     "environment": [
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAME"
       },
       {
         "name": "OTEL_LOGS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_METRICS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
         "value": "http/protobuf"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
         "value": "true"
       },
       {
         "name": "JAVA_TOOL_OPTIONS",
         "value": " -javaagent:/otel-auto-instrumentation/javaagent.jar"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
         "value": "http://localhost:4316/v1/metrics"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
         "value": "http://localhost:4316/v1/traces"
       },
       {
         "name": "OTEL_TRACES_SAMPLER",
         "value": "xray"
       },
       {
         "name": "OTEL_PROPAGATORS",
         "value": "tracecontext,baggage,b3,xray"
       }
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation",
         "containerPath": "/otel-auto-instrumentation",
         "readOnly": false
       }
     ]
   }

Python

在您啟用 Python 應用程式的應用程式訊號之前，請注意下列考量事項。

• 在某些容器化應用程式中，遺失的PYTHONPATH環境變數有時可能會導致應用程式無法啟動。若要解決此問題，請務必將PYTHONPATH環境變數設定為應用程式工作目錄的位置。這是由於 OpenTelemetry 自動檢測的已知問題所致。有關此問題的更多信息，請參閱 PYTHONPATH 的 Python 自動檢測設置不兼容。

• 對於 Django 應用程序，還有其他必需的配置，這些配置在 OpenTelemetry Python 文檔中概述。

  • 使用--noreload旗標可防止自動重新載入。

  • 將DJANGO_SETTINGS_MODULE環境變量設置為 Django 應用程序settings.py文件的位置。這確保了可 OpenTelemetry 以正確訪問並與您的 Django 設置集成。

使用代理程式在 Amazon ECS 上檢測您的 Python 應用程式 CloudWatch

1. 首先，指定綁定掛載。在接下來的步驟中，該磁碟區將用於跨容器共用檔案。將在此程序的後續步驟中使用此綁定掛載。

   "volumes": [
     {
       "name": "opentelemetry-auto-instrumentation-python"
     }
   ]

2. 新增 CloudWatch 代理程式並行定義。因此，請將名為 ecs-cwagent 的新容器附加到應用程式的任務定義。將 $REGION 取代為實際區域名稱。將 $IMAGE 替換為 Amazon 彈性容器註冊表上最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 cloudwatch-agent。

   {
     "name": "ecs-cwagent",
     "image": "$IMAGE",
     "essential": true,
     "secrets": [
       {
         "name": "CW_CONFIG_CONTENT",
         "valueFrom": "ecs-cwagent"
       }
     ],
     "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-create-group": "true",
         "awslogs-group": "/ecs/ecs-cwagent",
         "awslogs-region": "$REGION",
         "awslogs-stream-prefix": "ecs"
       }
     }
   }

3. 將新容器 init 附加到應用程式的任務定義。用 OpenTelemetry Amazon ECR 映像庫發行AWS 版中的最新映像替換 $ IMAGE。

   {
       "name": "init",
       "image": "$IMAGE",
       "essential": false,
       "command": [
           "cp",
           "-a",
           "/autoinstrumentation/.",
           "/otel-auto-instrumentation-python"
       ],
       "mountPoints": [
           {
               "sourceVolume": "opentelemetry-auto-instrumentation-python",
               "containerPath": "/otel-auto-instrumentation-python",
               "readOnly": false
           }
       ]
   }

4. 將下列環境變數新增至應用程式容器。

   環境變數	啟用 Application Signals 的設定
   OTEL_RESOURCE_ATTRIBUTES	將下列資訊指定為鍵值配對： service.name 會設定服務名稱。這將顯示為 Application Signals 儀表板中應用程式的服務名稱。如果您不提供此索引鍵的值，則會使用預設值 UnknownService。 deployment.environment 會設定執行應用程式的環境。這將顯示為 Application Signals 儀表板中應用程式的 Hosted In 環境。如果未指定此值，則會使用的generic:default預設值。 此屬性金鑰僅供應用程式訊號使用，並會轉換為 X-Ray 追蹤註解和度 CloudWatch 量維度。 (選擇性) 若要啟用追蹤記錄關聯，請將其他環境變數aws.log.group.names設定為應用程式記錄檔的記錄群組名稱。如此一來，應用程式的追蹤就可以與此特定記錄群組中的相關記錄項目相關聯。對於這個變數，請以應用程式的記錄群組名稱取代 $YOUR_APPLGROUP。您還需要更改應用程序中的日誌配置。如需詳細資訊，請參閱 啟用追蹤記錄關聯。
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED	設定為true讓您的容器開始將 X-Ray 追蹤和 CloudWatch 度量傳送至應用程式訊號。
   OTEL_METRICS_EXPORTER	設定為 none 以停用其他指標匯出工具。
   OTEL_EXPORTER_OTLP_PROTOCOL	設定為http/protobuf可使 CloudWatch 用 HTTP 將度量和追蹤傳送至。
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT	設定為http://127.0.0.1:4316/v1/metrics可將量度傳送至並 CloudWatch 行。
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	設定為http://127.0.0.1:4316/v1/traces將軌跡傳送至 CloudWatch 邊車。
   OTEL_TRACES_SAMPLER	將此項設定為xray可將 X-Ray 設定為追蹤取樣器。
   OTEL_PROPAGATORS	新增xray為其中一個傳輸者。
   OTEL_PYTHON_DISTRO	設定為aws_distro以使用亞多 Python 分析儀器。
   OTEL_PYTHON_CONFIGURATOR	設定aws_configuration為使用亞多 Python 組態。
   PYTHONPATH	取代$APP_PATH為容器內應用程式工作目錄的位置。Python 解釋器需要這樣才能找到您的應用程序模塊。
   DJANGO_SETTINGS_MODULE	僅適用於 Django 應用程式。將其設置為 Django 應用程序settings.py文件的位置。取代$PATH_TO_SETTINGS。

5. 掛載您在此程序步驟 1 中定義的磁碟區 opentelemetry-auto-instrumentation-python。在下列範例中，的值OTEL_RESOURCE_ATTRIBUTES包含可協助啟用追蹤記錄關聯的選aws.log.group.names用項目。如需詳細資訊，請參閱上一步中的表格。

   對於 Python 應用程序，請使用以下內容。

   {
     "name": "my-app",
     ...
     "environment": [
       {
         "name": "PYTHONPATH",
         "value": "/otel-auto-instrumentation-python/opentelemetry/instrumentation/auto_instrumentation:$APP_PATH:/otel-auto-instrumentation-python"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
         "value": "http/protobuf"
       },
       {
         "name": "OTEL_TRACES_SAMPLER",
         "value": "xray"
       },
       {
         "name": "OTEL_TRACES_SAMPLER_ARG",
         "value": "endpoint=http://localhost:2000"
       },
       {
         "name": "OTEL_LOGS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_PYTHON_DISTRO",
         "value": "aws_distro"
       },
       {
         "name": "OTEL_PYTHON_CONFIGURATOR",
         "value": "aws_configurator"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
         "value": "http://localhost:4316/v1/traces"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
         "value": "http://localhost:4316/v1/metrics"
       },
       {
         "name": "OTEL_METRICS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
         "value": "true"
       },
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAME"
       },
       {
         "name": "DJANGO_SETTINGS_MODULE",
         "value": "$PATH_TO_SETTINGS.settings"
       }
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-python",
         "containerPath": "/otel-auto-instrumentation-python",
         "readOnly": false
       }
     ]
   }

步驟 5：部署應用程式

建立任務定義的新修訂版本，並將其部署到應用程式叢集。應該會在新建立的任務中看到三個容器：

• init

• ecs-cwagent

• my-app