本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 Amazon EC2 上啟用您的應用程式
<a name="CloudWatch-Application-Signals-Enable-EC2Main"></a>

依本節所述的自訂設定步驟，在 Amazon EC2 上啟用 CloudWatch Application Signals。

對於在 Amazon EC2 上執行的應用程式，您可以自行安裝和設定 CloudWatch 代理程式和 AWS Distro for OpenTelemetry。在使用自訂 Application Signals 設定啟用的這些架構上，Application Signals 不會自動探索您的服務或其執行所在的叢集或主機的名稱。您必須在自訂設定期間指定這些名稱，而您指定的名稱是顯示在 Application Signals 儀表板中的名稱。

本節中的說明適用於 Java、Python 和 .NET 應用程式。這些步驟已在 Amazon EC2 執行個體上經過測試，但也預期適用於支援 AWS Distro for OpenTelemetry 的其他架構。

**需求**
+ 若要取得 Application Signals 的支援，您必須同時使用最新版本的 CloudWatch 代理程式和 AWS Distro for OpenTelemetry 代理程式。
+ 您必須在執行個體 AWS CLI 上安裝 。我們建議 AWS CLI 使用第 2 版，但第 1 版也應該有效。如需安裝 的詳細資訊 AWS CLI，請參閱[安裝或更新最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。

**重要**  
如果您已經在搭配使用 OpenTelemetry 與您想要為 Application Signals 啟用的應用程式，請在啟用 Application Signals 之前參閱 [支援的系統](CloudWatch-Application-Signals-supportmatrix.md)。

## 步驟 1：在您的帳戶中啟用 Application Signals
<a name="CloudWatch-Application-Signals-EC2-Grant"></a>

必須先在帳戶中啟用 Application Signals。如果尚未這麼做，請參閱 [在您的帳戶中啟用 Application Signals](CloudWatch-Application-Signals-Enable.md)。

## 步驟 2：下載並啟動 CloudWatch 代理程式
<a name="CloudWatch-Application-Signals-Enable-Other-agent"></a>

**安裝 CloudWatch 代理程式，以在 Amazon EC2 執行個體或內部部署主機上啟用 Application Signals**

1. 將最新版的 CloudWatch 代理程式下載至執行個體。如果執行個體已安裝 CloudWatch 代理程式，則您可能需要更新它。只有 2023 年 11 月 30 日或更晚時間發行的代理程式版本支援 CloudWatch Application Signals。

1. 在啟動 CloudWatch 代理程式之前，請將其設定為啟用 Application Signals。下列範例是可針對 EC2 主機上的指標和追蹤來啟用 Application Signals 的 CloudWatch 代理程式組態。

   建議您將此檔案放置在 Linux 系統上的 `/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json`。

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

1. 將 **CloudWatchAgentServerPolicy** IAM 政策附加至 Amazon EC2 執行個體的 IAM 角色。如需內部部署主機的許可，請參閱 [內部部署伺服器的許可](#Enable-OnPremise-Permissions)。

   1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。

   1. 選擇**角色**並查找 Amazon EC2 執行個體使用的角色。然後選擇該角色的名稱。

   1. 在**許可**索引標籤中，依序選擇**新增許可**、**附接政策**。

   1. Find **CloudWatchAgentServerPolicy**. 如有需要，請使用搜尋方塊。然後，選取該政策的核取方塊，並選擇**新增許可**。

1. 輸入下列命令，啟動 CloudWatch 代理程式。將 *agent-config-file-path* 取代為 CloudWatch 代理程式組態檔案的路徑，例如 `./amazon-cloudwatch-agent.json`。必須包含如下所示的 `file:` 字首。

   ```
   export CONFIG_FILE_PATH=./amazon-cloudwatch-agent.json
   ```

   ```
   sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
   -a fetch-config \
   -m ec2 -s -c file:agent-config-file-path
   ```

### 內部部署伺服器的許可
<a name="Enable-OnPremise-Permissions"></a>

對於現場部署主機，您需要為裝置提供 AWS 授權。

**設定內部部署主機的許可**

1. 建立 IAM 使用者，用於為您的內部部署主機提供許可：

   1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

   1. 選擇**使用者**、**建立使用者**。

   1. 在**使用者詳細資訊**的**使用者名稱**中，輸入新 IAM 使用者的名稱。這是 的登入名稱 AWS ，將用於驗證您的主機。然後選擇**下一步**

   1. 在**設定許可**頁面，為**許可選項**選取**直接連結政策**。

   1. 在**許可政策**清單中，選取要新增至使用者的 **CloudWatchAgentServerPolicy** 政策。然後選擇**下一步**。

   1. 在**檢閱和建立**頁面上，確定您對使用者名稱感到滿意，並且 **CloudWatchAgentServerPolicy** 政策位於**許可摘要**中。

   1. 選擇**建立使用者**

1. 建立和擷取您的 AWS 存取金鑰和私密金鑰：

   1. 在 IAM 主控台的導覽窗格中，選取**使用者**，然後選取在先前步驟中建立的使用者名稱。

   1.  在使用者頁面上，選擇**安全憑證**索引標籤。在**存取金鑰**區段中，選擇**建立存取金鑰**。

   1. 針對**建立存取金鑰步驟 1**，請選擇**命令列界面 (CLI)**。

   1. 在**建立存取金鑰步驟 2** 中，輸入選用標籤，然後選擇**下一步**。

   1. 在**建立存取金鑰步驟 3** 中，選取**下載 .csv 檔案**，以儲存包含 IAM 使用者存取金鑰和私密存取金鑰的 .csv 檔案。您需要這些資訊才能進行後續步驟。

   1. 選擇**完成**。

1. 輸入下列命令，在現場部署主機中設定您的 AWS 登入資料。將 *ACCESS\$1KEY\$1ID* 和 *SECRET\$1ACCESS\$1ID* 替換為您在上一個步驟中下載的 .csv 檔案中新產生的存取金鑰和私密存取金鑰。

   ```
   $ aws configure
   AWS Access Key ID [None]: ACCESS_KEY_ID
   AWS Secret Access Key [None]: SECRET_ACCESS_ID
   Default region name [None]: MY_REGION
   Default output format [None]: json
   ```

## 步驟 3：檢測您的應用程式並啟動它
<a name="CloudWatch-Application-Signals-Enable-Other-instrument"></a>

下一個步驟是針對 CloudWatch Application Signals 檢測您的應用程式。

------
#### [ Java ]

**檢測您的 Java 應用程式，以在 Amazon EC2 執行個體或內部部署主機上啟用 Application Signals**

1. 下載最新版本的 AWS Distro for OpenTelemetry Java 自動檢測代理程式。可以使用[此連結](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar)來下載最新版本。可以透過 [aws-otel-java-instrumentation 發行版本](https://github.com/aws-observability/aws-otel-java-instrumentation/releases)檢視所有已發行的版本資訊。

1. 若要最佳化 Application Signals 優勢，請在啟動應用程式之前，使用環境變數提供其他資訊。此資訊將顯示在 Application Signals 儀表板中。

   1. 對於 `OTEL_RESOURCE_ATTRIBUTES` 變數，請將下列資訊指定為索引鍵/值對：
     + (選用) `service.name` 設定服務名稱。這將顯示為應用程式在 Application Signals 儀表板中的服務名稱。如果您不提供此索引鍵的值，則會使用預設值 `UnknownService`。
     + (選用) `deployment.environment` 設定執行應用程式的環境。這將顯示為 Application Signals 儀表板中應用程式的 **Hosted In** 環境。如果未指定此值，系統會使用下列其中一個預設值：
       + 如果是 Auto Scaling 群組中的執行個體，設定為 `ec2:name-of-Auto-Scaling-group`
       + 如果不是 Auto Scaling 群組中的 Amazon EC2 執行個體，設定為 `ec2:default` 
       + 如果是內部部署主機，則設定為 `generic:default` 

       此環境變數僅供 Application Signals 使用，會轉換為 X-Ray 追蹤注釋和 CloudWatch 指標維度。
     + 對於 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 變數，請指定要接收追蹤匯出的基礎端點 URL。CloudWatch 代理程式將 4316 公開為其 OTLP 連接埠。在 Amazon EC2 上，由於應用程式會與本機 CloudWatch 代理程式通訊，因此應將此值設為 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`。
     + 對於 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 變數，請指定要接收指標匯出的基礎端點 URL。CloudWatch 代理程式將 4316 公開為其 OTLP 連接埠。在 Amazon EC2 上，由於應用程式會與本機 CloudWatch 代理程式通訊，因此應將此值設為 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`。
     + 針對 `JAVA_TOOL_OPTIONS`變數，指定存放 AWS Distro for OpenTelemetry Java 自動檢測代理程式的路徑。

       ```
       export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"
       ```

       例如：

       ```
       export AWS_ADOT_JAVA_INSTRUMENTATION_PATH=./aws-opentelemetry-agent.jar
       ```
     + 對於 `OTEL_METRICS_EXPORTER` 變數，建議將值設定為 `none`。這會停用其他指標匯出工具，以便只使用 Application Signals 匯出器。
     + 將 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 設定為 `true`。這會從追蹤中產生 Application Signals 指標。

1. 使用上一個步驟中列出的環境變數來啟動應用程式。以下是啟動指令碼的範例。
**注意**  
下列組態僅支援適用於 Java 的 AWS Distro for OpenTelemetry 自動檢測代理程式的 1.32.2 版和更新版本。

   ```
   JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
   java -jar $MY_JAVA_APP.jar
   ```

1. (選用) 若要啟用日誌關聯，請在 `aws.log.group.names` 中為應用程式的日誌群組設定額外的環境變數 `OTEL_RESOURCE_ATTRIBUTES`。如此一來，您應用程式的追蹤與指標，便能與這些日誌群組中的相關日誌條目關聯對應。對於此變數，請將 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP* 替換為應用程式的日誌群組名稱。如有多個日誌群組，可以使用 `&` 進行分隔，如本範例所示：`aws.log.group.names=log-group-1&log-group-2`。若要啟用指標與日誌的關聯，只需設定此環境變數即可。如需詳細資訊，請參閱[啟用指標以記錄關聯](Application-Signals-MetricLogCorrelation.md)。若要啟用追蹤與日誌的關聯，還需要在應用程式中變更日誌記錄組態。如需詳細資訊，請參閱[啟用追蹤與日誌的關聯](Application-Signals-TraceLogCorrelation.md)。

   以下是有助於啟用日誌關聯的啟動指令碼範例。

   ```
   JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORT=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
   java -jar $MY_JAVA_APP.jar
   ```

------
#### [ Python ]

**注意**  
如果為 Python 應用程式使用 WSGI 伺服器，除了本節中的下列步驟之外，請參閱 [使用 WSGI 伺服器的 Python 應用程式沒有 Application Signals 資料](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI) 以取得有關使 Application Signals 正常運作的資訊。

**檢測您的 Python 應用程式，以在 Amazon EC2 執行個體上啟用 Application Signals**

1. 下載最新版本的 AWS Distro for OpenTelemetry Python 自動檢測代理程式。請執行下列 命令進行安裝。

   ```
   pip install aws-opentelemetry-distro
   ```

   可以在 [AWS Distro for OpenTelemetry Python 檢測](https://github.com/aws-observability/aws-otel-python-instrumentation/releases)中檢視所有發行版本的相關資訊。

1. 若要最佳化 Application Signals 優勢，請在啟動應用程式之前，使用環境變數提供其他資訊。此資訊將顯示在 Application Signals 儀表板中。

   1. 對於 `OTEL_RESOURCE_ATTRIBUTES` 變數，請將下列資訊指定為索引鍵/值對：
      + `service.name` 會設定服務名稱。這將顯示為 Application Signals 儀表板中應用程式的服務名稱。如果您不提供此索引鍵的值，則會使用預設值 `UnknownService`。
      + `deployment.environment` 會設定執行應用程式的環境。這將顯示為 Application Signals 儀表板中應用程式的 **Hosted In** 環境。如果未指定此值，系統會使用下列其中一個預設值：
        + 如果是 Auto Scaling 群組中的執行個體，設定為 `ec2:name-of-Auto-Scaling-group`。
        + 如果不是 Auto Scaling 群組中的 Amazon EC2 執行個體，設定為 `ec2:default` 
        + 如果是內部部署主機，則設定為 `generic:default` 

         此屬性金鑰僅供 Application Signals 使用，並會轉換為 X-Ray 追蹤注釋和 CloudWatch 指標維度。

   1. 對於 `OTEL_EXPORTER_OTLP_PROTOCOL` 變數，請指定 `http/protobuf`，以透過 HTTP 將遙測資料匯出至以下步驟中列出的 CloudWatch 代理程式端點。

   1. 對於 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 變數，請指定要接收追蹤匯出的基礎端點 URL。CloudWatch 代理程式透過 HTTP 將 4316 公開為其 OTLP 連接埠。在 Amazon EC2 上，由於應用程式會與本機 CloudWatch 代理程式通訊，因此應將此值設為 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`。

   1. 對於 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 變數，請指定要接收指標匯出的基礎端點 URL。CloudWatch 代理程式透過 HTTP 將 4316 公開為其 OTLP 連接埠。在 Amazon EC2 上，由於應用程式會與本機 CloudWatch 代理程式通訊，因此應將此值設為 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`。

   1. 對於 `OTEL_METRICS_EXPORTER` 變數，建議將值設定為 `none`。這會停用其他指標匯出工具，以便只使用 Application Signals 匯出器。

   1. 將 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 變數設定為 `true`，讓您的容器開始將 X-Ray 追蹤和 CloudWatch 指標傳送至 Application Signals。

1. 使用上一個步驟中討論的環境變數來啟動應用程式。以下是啟動指令碼的範例。
   + 將 `$SVC_NAME` 取代為應用程式名稱。這將顯示為 Application Signals 儀表板中的應用程式名稱。
   + 將 `$PYTHON_APP` 替換為您應用程式的位置和名稱。

   ```
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_PYTHON_DISTRO=aws_distro \
   OTEL_PYTHON_CONFIGURATOR=aws_configurator \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_TRACES_SAMPLER=xray \
   OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
   opentelemetry-instrument python $MY_PYTHON_APP.py
   ```

   在為 Python 應用程式啟用 Application Signals 之前，請注意下列考量。
   + 在某些容器化應用程式中，缺少 `PYTHONPATH` 環境變數有時會導致應用程式無法啟動。若要解決此問題，請確定將 `PYTHONPATH` 環境變數設定為應用程式的工作目錄位置。這是由於 OpenTelemetry 自動檢測功能存在已知問題所致。如需此問題的詳細資訊，請參閱 [Python autoinstrumentation setting of PYTHONPATH is not compliant](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)。
   + 對於 Django 應用程式，還需要進行額外的必要設定，相關說明詳見 [OpenTelemetry Python 文件](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html)。
     + `--noreload` 旗標可用於防止自動重新載入。
     + 將 `DJANGO_SETTINGS_MODULE` 環境變數設定為 Django 應用程式 `settings.py` 檔案的所在位置。如此可確保 OpenTelemetry 能夠正確存取並整合您的 Django 設定。

1. (選用) 若要啟用日誌關聯，請在 `aws.log.group.names` 中為應用程式的日誌群組設定額外的環境變數 `OTEL_RESOURCE_ATTRIBUTES`。如此一來，您應用程式的追蹤與指標，便能與這些日誌群組中的相關日誌條目關聯對應。對於此變數，請將 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP* 替換為應用程式的日誌群組名稱。如有多個日誌群組，可以使用 `&` 進行分隔，如本範例所示：`aws.log.group.names=log-group-1&log-group-2`。若要啟用指標與日誌的關聯，只需設定此環境變數即可。如需詳細資訊，請參閱[啟用指標以記錄關聯](Application-Signals-MetricLogCorrelation.md)。若要啟用追蹤與日誌的關聯，還需要在應用程式中變更日誌記錄組態。如需詳細資訊，請參閱[啟用追蹤與日誌的關聯](Application-Signals-TraceLogCorrelation.md)。

   以下是有助於啟用日誌關聯的啟動指令碼範例。

   ```
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_PYTHON_DISTRO=aws_distro \
   OTEL_PYTHON_CONFIGURATOR=aws_configurator \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_TRACES_SAMPLER=xray \
   OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
   java -jar $MY_PYTHON_APP.jar
   ```

------
#### [ .NET ]

**檢測您的 .NET 應用程式，以在 Amazon EC2 執行個體或內部部署主機上啟用 Application Signals**

1. 下載最新版本的 AWS Distro for OpenTelemetry .NET 自動檢測套件。可於 [aws-otel-dotnet-instrumentation Releases](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases) 下載最新版本。

1. 若要啟用 Application Signals，請在啟動應用程式之前，使用以下環境變數提供其他資訊。在您啟動 .NET 應用程式之前，需要這些變數才能設定 .NET 檢測的啟動勾點。將 `OTEL_RESOURCE_ATTRIBUTES` 環境變數中的 `dotnet-service-name` 替換為您選擇的服務名稱。
   + 以下是 Linux 範例。

     ```
     export INSTALL_DIR=OpenTelemetryDistribution
     export CORECLR_ENABLE_PROFILING=1
     export CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
     export CORECLR_PROFILER_PATH=${INSTALL_DIR}/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
     export DOTNET_ADDITIONAL_DEPS=${INSTALL_DIR}/AdditionalDeps
     export DOTNET_SHARED_STORE=${INSTALL_DIR}/store
     export DOTNET_STARTUP_HOOKS=${INSTALL_DIR}/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
     export OTEL_DOTNET_AUTO_HOME=${INSTALL_DIR}
     
     export OTEL_DOTNET_AUTO_PLUGINS="AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
     
     export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
     export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
     export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4316
     export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://127.0.0.1:4316/v1/metrics
     export OTEL_METRICS_EXPORTER=none
     export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
     export OTEL_TRACES_SAMPLER=xray
     export OTEL_TRACES_SAMPLER_ARG=http://127.0.0.1:2000
     ```
   + 以下是適用於 Windows Server 的範例。

     ```
     $env:INSTALL_DIR = "OpenTelemetryDistribution"
     $env:CORECLR_ENABLE_PROFILING = 1
     $env:CORECLR_PROFILER = "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
     $env:CORECLR_PROFILER_PATH = Join-Path $env:INSTALL_DIR "win-x64/OpenTelemetry.AutoInstrumentation.Native.dll"
     $env:DOTNET_ADDITIONAL_DEPS = Join-Path $env:INSTALL_DIR "AdditionalDeps"
     $env:DOTNET_SHARED_STORE = Join-Path $env:INSTALL_DIR "store"
     $env:DOTNET_STARTUP_HOOKS = Join-Path $env:INSTALL_DIR "net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
     $env:OTEL_DOTNET_AUTO_HOME = $env:INSTALL_DIR
     
     $env:OTEL_DOTNET_AUTO_PLUGINS = "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
     
     $env:OTEL_RESOURCE_ATTRIBUTES = "service.name=dotnet-service-name"
     $env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
     $env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4316"
     $env:OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT = "http://127.0.0.1:4316/v1/metrics"
     $env:OTEL_METRICS_EXPORTER = "none"
     $env:OTEL_AWS_APPLICATION_SIGNALS_ENABLED = "true"
     $env:OTEL_TRACES_SAMPLER = "xray"
     $env:OTEL_TRACES_SAMPLER_ARG = "http://127.0.0.1:2000"
     ```

1. 使用上一個步驟中列出的環境變數來啟動應用程式。

   （選用） 或者，您可以使用提供的安裝指令碼來協助安裝和設定 AWS Distro for OpenTelemetry .NET 自動檢測套件。

   對於 Linux，請從 GitHub 發行頁面下載並安裝 Bash 安裝指令碼：

   ```
   # Download and Install
   curl -L -O https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/aws-otel-dotnet-install.sh
   chmod +x ./aws-otel-dotnet-install.sh
   ./aws-otel-dotnet-install.sh
   
   # Instrument
   . $HOME/.otel-dotnet-auto/instrument.sh
   export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
   ```

   對於 Windows Server，請從 GitHub 發行頁面下載並安裝 PowerShell 安裝指令碼：

   ```
   # Download and Install
   $module_url = "https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/AWS.Otel.DotNet.Auto.psm1"
   $download_path = Join-Path $env:temp "AWS.Otel.DotNet.Auto.psm1"
   Invoke-WebRequest -Uri $module_url -OutFile $download_path
   Import-Module $download_path
   Install-OpenTelemetryCore
   
   # Instrument
   Import-Module $download_path
   Register-OpenTelemetryForCurrentSession -OTelServiceName "dotnet-service-name"
   Register-OpenTelemetryForIIS
   ```

   您可以在官方 NuGet 儲存庫中找到 AWS Distro for OpenTelemetry .NET 自動檢測套件的 NuGet 套件。 [ NuGet ](https://www.nuget.org/packages/AWS.Distro.OpenTelemetry.AutoInstrumentation) 請務必檢查 [README 檔案](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/blob/main/src/AWS.Distro.OpenTelemetry.AutoInstrumentation/nuget-readme.md)以取得相關說明。

------
#### [ Node.js ]

**注意**  
如果使用 ESM 為 Node.js 應用程式啟用 Application Signals，請在開始這些步驟之前參閱 [Setting up a Node.js application with the ESM module format](#EC2-NodeJs-ESM)。

**檢測您的 Node.js 應用程式，以在 Amazon EC2 執行個體上啟用 Application Signals**

1. 下載適用於 Node.js 的 AWS Distro for OpenTelemetry JavaScript 自動檢測代理程式的最新版本。請執行下列 命令進行安裝。

   ```
   npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
   ```

   可以在 [AWS Distro for OpenTelemetry JavaScript 檢測](https://github.com/aws-observability/aws-otel-js-instrumentation/releases)中檢視所有發行版本的相關資訊。

1. 若要最佳化 Application Signals 優勢，請在啟動應用程式之前，使用環境變數提供其他資訊。此資訊將顯示在 Application Signals 儀表板中。

   1. 對於 `OTEL_RESOURCE_ATTRIBUTES` 變數，請將下列資訊指定為索引鍵/值對：
      + `service.name` 會設定服務名稱。這將顯示為 Application Signals 儀表板中應用程式的服務名稱。如果您不提供此索引鍵的值，則會使用預設值 `UnknownService`。
      + `deployment.environment` 會設定執行應用程式的環境。這將顯示為 Application Signals 儀表板中應用程式的 **Hosted In** 環境。如果未指定此值，系統會使用下列其中一個預設值：
        + 如果是 Auto Scaling 群組中的執行個體，設定為 `ec2:name-of-Auto-Scaling-group`。
        + 如果不是 Auto Scaling 群組中的 Amazon EC2 執行個體，設定為 `ec2:default` 
        + 如果是內部部署主機，則設定為 `generic:default` 

         此屬性金鑰僅供 Application Signals 使用，並會轉換為 X-Ray 追蹤注釋和 CloudWatch 指標維度。

   1. 對於 `OTEL_EXPORTER_OTLP_PROTOCOL` 變數，請指定 `http/protobuf`，以透過 HTTP 將遙測資料匯出至以下步驟中列出的 CloudWatch 代理程式端點。

   1. 對於 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 變數，請指定要接收追蹤匯出的基礎端點 URL。CloudWatch 代理程式透過 HTTP 將 4316 公開為其 OTLP 連接埠。在 Amazon EC2 上，由於應用程式會與本機 CloudWatch 代理程式通訊，因此應將此值設為 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`。

   1. 對於 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 變數，請指定要接收指標匯出的基礎端點 URL。CloudWatch 代理程式透過 HTTP 將 4316 公開為其 OTLP 連接埠。在 Amazon EC2 上，由於應用程式會與本機 CloudWatch 代理程式通訊，因此應將此值設為 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`。

   1. 對於 `OTEL_METRICS_EXPORTER` 變數，建議將值設定為 `none`。這會停用其他指標匯出工具，以便只使用 Application Signals 匯出器。

   1. 將 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 變數設定為 `true`，讓您的容器開始將 X-Ray 追蹤和 CloudWatch 指標傳送至 Application Signals。

1. 使用上一個步驟中討論的環境變數來啟動應用程式。以下是啟動指令碼的範例。
   + 將 `$SVC_NAME` 取代為應用程式名稱。這將顯示為 Application Signals 儀表板中的應用程式名稱。

   ```
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_TRACES_SAMPLER=xray \
   OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
   node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
   ```

1. (選用) 若要啟用日誌關聯，請在 `aws.log.group.names` 中為應用程式的日誌群組設定額外的環境變數 `OTEL_RESOURCE_ATTRIBUTES`。如此一來，您應用程式的追蹤與指標，便能與這些日誌群組中的相關日誌條目關聯對應。對於此變數，請將 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP* 替換為應用程式的日誌群組名稱。如有多個日誌群組，可以使用 `&` 進行分隔，如本範例所示：`aws.log.group.names=log-group-1&log-group-2`。若要啟用指標與日誌的關聯，只需設定此環境變數即可。如需詳細資訊，請參閱[啟用指標以記錄關聯](Application-Signals-MetricLogCorrelation.md)。若要啟用追蹤與日誌的關聯，還需要在應用程式中變更日誌記錄組態。如需詳細資訊，請參閱[啟用追蹤與日誌的關聯](Application-Signals-TraceLogCorrelation.md)。

   以下是有助於啟用日誌關聯的啟動指令碼範例。

   ```
   export OTEL_METRICS_EXPORTER=none \
   export OTEL_LOGS_EXPORTER=none \
   export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   export OTEL_TRACES_SAMPLER=xray \
   export OTEL_TRACES_SAMPLER_ARG=endpoint=http://localhost:2000 \
   export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   export OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$SVC_NAME" \
   node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
   ```<a name="EC2-NodeJs-ESM"></a>

**設定採用 ESM 模組格式的 Node.js 應用程式**

對於採用 ESM 模組格式的 Node.js 應用程式，我們提供有限支援。如需詳細資訊，請參閱[Node.js 搭配使用 ESM 的已知限制](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)。

若要為採用 ESM 的 Node.js 應用程式啟用 Application Signals，需要修改先前程序中的步驟。

首先，為您的 Node.js 應用程式安裝 `@opentelemetry/instrumentation`：

```
npm install @opentelemetry/instrumentation@0.54.0
```

然後，在上一個程序中的步驟 3 和 4 中，變更節點選項，從：

```
--require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register'
```

變更為：

```
--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs
```

------

## 使用模型內容通訊協定 (MCP) 在 Amazon EC2 上啟用應用程式訊號
<a name="CloudWatch-Application-Signals-EC2-MCP"></a>

您可以使用 CloudWatch Application Signals Model Context Protocol (MCP) 伺服器，透過對話式 AI 互動在 Amazon EC2 執行個體上啟用 Application Signals。這提供用於設定 Application Signals 監控的自然語言界面。

MCP 伺服器會了解您的需求並產生適當的組態，以自動化啟用程序。您可以直接描述要啟用的內容，而不是手動遵循設定步驟。

### 先決條件
<a name="CloudWatch-Application-Signals-EC2-MCP-Prerequisites"></a>

使用 MCP 伺服器啟用 Application Signals 之前，請確定您已：
+ 支援 MCP 的開發環境 （例如 Kiro、Claude Desktop、VSCode 搭配 MCP 延伸模組或其他 MCP 相容工具）
+ 在您的 IDE 中設定的 CloudWatch Application Signals MCP 伺服器。如需詳細設定說明，請參閱 [CloudWatch Application Signals MCP Server 文件](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。

### 使用 MCP 伺服器
<a name="CloudWatch-Application-Signals-EC2-MCP-Usage"></a>

在 IDE 中設定 CloudWatch Application Signals MCP 伺服器後，您可以使用自然語言提示請求啟用指引。雖然編碼助理可以從專案結構推斷內容，但在提示中提供特定詳細資訊有助於確保更準確和相關的指導。包含您的應用程式語言、執行個體詳細資訊，以及基礎設施和應用程式程式碼的絕對路徑等資訊。

**最佳實務提示 （特定且完整）：**

```
"Enable Application Signals for my Python service running on EC2.
My app code is in /home/ec2-user/flask-api and IaC is in /home/ec2-user/flask-api/terraform"

"I want to add observability to my Java application on EC2.
The application code is at /opt/apps/checkout-service and
the infrastructure code is at /opt/apps/checkout-service/cloudformation"

"Help me instrument my Node.js application on EC2 with Application Signals.
Application directory: /home/ubuntu/payment-api
Terraform code: /home/ubuntu/payment-api/terraform"
```

**效率較低的提示：**

```
"Enable monitoring for my app"
→ Missing: platform, language, paths

"Enable Application Signals. My code is in ./src and IaC is in ./infrastructure"
→ Problem: Relative paths instead of absolute paths

"Enable Application Signals for my EC2 service at /home/user/myapp"
→ Missing: programming language
```

**快速範本：**

```
"Enable Application Signals for my [LANGUAGE] service on EC2.
App code: [ABSOLUTE_PATH_TO_APP]
IaC code: [ABSOLUTE_PATH_TO_IAC]"
```

### 使用 MCP 伺服器的優點
<a name="CloudWatch-Application-Signals-EC2-MCP-Benefits"></a>

使用 CloudWatch Application Signals MCP 伺服器有幾個優點：
+ **自然語言界面：**描述您想要啟用的內容，而不記住命令或組態語法
+ **內容感知指引：**MCP 伺服器了解您的特定環境，並提供量身打造的建議
+ **減少錯誤：**自動化組態產生可將手動輸入錯誤降至最低
+ **更快速的設定：**更快速地從意圖到實作
+ **學習工具：**查看產生的組態並了解 Application Signals 的運作方式

### 其他資源
<a name="CloudWatch-Application-Signals-EC2-MCP-MoreInfo"></a>

如需有關設定和使用 CloudWatch Application Signals MCP 伺服器的詳細資訊，請參閱 [MCP 伺服器文件](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。

## (選用) 監控應用程式運作狀態
<a name="CloudWatch-Application-Signals-Monitor-EC2"></a>

在 Amazon EC2 上啟用應用程式後，即可監控應用程式的運作狀態。如需詳細資訊，請參閱[使用 Application Signals 監控應用程式的運作狀態](Services.md)。