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

# 支援的系統
<a name="CloudWatch-Application-Signals-supportmatrix"></a>

Application Signals 在 Amazon EKS、原生 Kubernetes、Amazon ECS 及 Amazon EC2 平台上受到支援，並且經過測試。在 Amazon EC2 上啟用 Application Signals 的指示應適用於支援 CloudWatch 代理程式和 AWS Distro for OpenTelemetry 的任何平台。

**Topics**
+ [Java 相容性](#CloudWatch-Application-Signals-supportmatrix-java)
+ [.NET 相容性](#CloudWatch-Application-Signals-supportmatrix-dotnet)
+ [PHP 相容性](#php-compatibility)
+ [Ruby 相容性](#ruby-compatibility)
+ [Python 相容性](#CloudWatch-Application-Signals-supportmatrix-python)
+ [Node.js 相容性](#CloudWatch-Application-Signals-supportmatrix-node)
+ [GoLang 相容性](#golang-compatibility)
+ [執行時期版本支援矩陣](#rumtime-version-matix)
+ [已知問題](#AppSignals-Issues)

## Java 相容性
<a name="CloudWatch-Application-Signals-supportmatrix-java"></a>

Application Signals 支援 Java 應用程式，並支援與 AWS Distro for OpenTelemetry 相同的 Java 程式庫和架構。如需詳細資訊，請參閱[支援的程式庫、架構、應用程式伺服器和 JVM](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md)。

## .NET 相容性
<a name="CloudWatch-Application-Signals-supportmatrix-dotnet"></a>

Application Signals 支援與 AWS Distro for OpenTelemetry 相同的 .NET 程式庫和架構。如需更多詳細資訊，請參閱 [Supported instrumentations](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/internal/instrumentation-libraries.md)。

Application Signals 支援在 x86-64 或 ARM64 CPU 上執行的 .NET 應用程式，並支援 Linux x64、Linux ARM64 和 Microsoft Windows Server 2022 x64。

**注意**  
適用於 .NET 的 AWS Distro for Open Telemetry (ADOT) 開發套件不支援適用於 .NET V4 的 AWS 開發套件。使用 AWS SDK .NET V3 取得完整的 Application Signals 支援。

## PHP 相容性
<a name="php-compatibility"></a>

Application Signals 支援具備 OpenTelemetry 零代碼檢測功能的 PHP 應用程式。沒有可用於此目的的 AWS Distro for Open Telemetry (ADOT) SDK。應該使用啟用 [Transaction Search](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html) 的標準 OpenTelemetry 檢測 SDK。若要在 PHP 中開始使用零代碼檢測功能，請依循 OpenTelemetry PHP Instrumentation 文件 [PHP 零程式碼檢測](https://opentelemetry.io/docs/zero-code/php/)中的步驟。自動檢測適用於眾多常用的 PHP 程式庫。如需詳細資訊，請參閱 [OpenTelemetry 登錄檔](https://packagist.org/search/?query=open-telemetry%3Dinstrumentation)。

## Ruby 相容性
<a name="ruby-compatibility"></a>

Application Signals 支援具備 OpenTelemetry 零代碼檢測功能的 Ruby 應用程式。沒有可用於此目的的 AWS Distro for Open Telemetry (ADOT) SDK。應該使用啟用 [Transaction Search](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html) 的標準 OpenTelemetry 檢測 SDK。若要在 Ruby 中開始使用零代碼檢測功能，請依循 OpenTelemetry Ruby Instrumentation 文件 [Ruby 零程式碼檢測](https://opentelemetry.io/docs/languages/ruby/getting-started/#instrumentation)中的步驟。如需已發行檢測程式庫的清單，請參閱[登錄檔](https://opentelemetry.io/ecosystem/registry/?language=rubycomponent=instrumentation)。

## Python 相容性
<a name="CloudWatch-Application-Signals-supportmatrix-python"></a>

Application Signals 支援與 AWS Distro for OpenTelemetry 相同的程式庫和架構。如需詳細資訊，請參閱 [opentelemetry-python-contrib](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/README.md) 中的**支援的套件**。

在為 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 設定。

## Node.js 相容性
<a name="CloudWatch-Application-Signals-supportmatrix-node"></a>

Application Signals 支援與 AWS Distro for OpenTelemetry 相同的 Node.js 程式庫和架構。如需更多詳細資訊，請參閱 [Supported instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main)。

### Node.js 搭配使用 ESM 的已知限制
<a name="ESM-limitations"></a>

 AWS Distro for Opentelemetry Node.js 支援兩個模組系統：ECMAScript Modules (ESM) 和 CommonJS (CJS)。若要啟用 Application Signals，我們建議您使用 CJS 模組格式，因為 OpenTelemetry JavaScript 對 ESM 的支援目前仍處於實驗階段且持續開發中。如需詳細資訊，請參閱 GitHub 上的 [ECMAScript 模組與 CommonJS](https://github.com/open-telemetry/opentelemetry-js/blob/eb3ca4fb07ee31c62093f5fcec56575573c902ce/doc/esm-support.md)。

若要確定您的應用程式使用的是 CJS 而非 ESM，請確保您的應用程式不符合啟用 ESM 的條件。如需這些條件的詳細資訊，請參閱 Node.js 文件中的[啟用](https://nodejs.org/api/esm.html#enabling)。

 AWS Distro for Opentelemetry Node.js 根據 OpenTelemetry JavaScript 的 ESM 實驗性支援，提供有限的 ESM 支援。這表示：
+ Node.js 版本必須為 18.19.0 或更高版本。
+ 要檢測的 Node.js 應用程式必須包含 `@aws/aws-distro-opentelemetry-node-autoinstrumentation` 和 `@opentelemetry/instrumentation` 作為相依項。
+ 要檢測的 Node.js 應用程式必須以下列節點選項開頭：

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

為使用 Node.js ESM 模組格式啟用 Application Signals，我們為不同平台提供不同設定：
+ **Amazon EKS** – [設定採用 ESM 模組格式的 Node.js 應用程式](CloudWatch-Application-Signals-Enable-EKS.md#EKS-NodeJs-ESM)
+ **Amazon ECS 搭配附屬程式策略** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-ECS-Sidecar.md#ECS-NodeJs-ESM)
+ **Amazon ECS 搭配常駐程式策略** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-ECS-Daemon.md#ECSDaemon-NodeJs-ESM)
+ **使用 的 Amazon ECS AWS CDK**
+ **Amazon EC2** – [Setting up a Node.js application with the ESM module format](CloudWatch-Application-Signals-Enable-EC2Main.md#EC2-NodeJs-ESM)
+ **Kubernetes** – [設定採用 ESM 模組格式的 Node.js 應用程式](CloudWatch-Application-Signals-Enable-KubernetesMain.md#Kubernetes-NodeJs-ESM)

## GoLang 相容性
<a name="golang-compatibility"></a>

Application Signals 支援具備 OpenTelemetry 零代碼檢測功能的 GoLang 應用程式。沒有可用於此目的的 AWS Distro for Open Telemetry (ADOT) SDK。應該使用啟用 [Transaction Search](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html) 的標準 OpenTelemetry 檢測 SDK。若要在 GoLang 中開始使用零程式碼檢測功能，請依循 OpenTelemetry GoLang 檢測文件《[開始使用 OpenTelemetry Go 自動檢測功能](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/getting-started.md)》中的下列步驟。

### GoLang 檢測實作考量
<a name="implementation-considerations-golang"></a>

了解使用 GoLang 檢測的重要實作詳細資訊。本指南說明如何在 GoLang 應用程式中實作明確的內容傳播機制，並設定 Application Signals。正確實作 GoLang 檢測有助於有效追蹤和分析應用程式的效能。

#### 檢測 AWS SDK
<a name="instrumenting-aws-sdk"></a>

Golang 自動檢測程式庫不支援開箱即用的 AWS SDK 檢測。必須搭配自動檢測代理程式使用 `otelaws` 程式庫檢測：

1. 安裝所需的相依項：

   ```
   go get go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws
   ```

1. 在應用程式中加入以下行：

   ```
   otelaws.AppendMiddlewares(&cfg.APIOptions)
   ```

1. 使用上一個`aws.Config`物件建立後續 AWS 用戶端：

   ```
   s3Client := s3.NewFromConfig(cfg)
   ```

下列範例將產生 AWS 呼叫的範圍，並與自動檢測整合。

```
func handleRequest(ctx context.Context) error {
    cfg, err := config.LoadDefaultConfig(ctx)
    if err != nil {
        return err
    }
    
    // Add OpenTelemetry instrumentation middleware to the AWS config
    otelaws.AppendMiddlewares(&cfg.APIOptions)
    
    // Create S3 client with the instrumented config
    s3Client := s3.NewFromConfig(cfg)
    
    // Now any operations with this client will be traced
    // with the context from the upstream call
    _, err = s3Client.ListBuckets(ctx, &s3.ListBucketsInput{})
    return err
}
```

如需設定自動檢測可執行檔的資訊，請參閱[組態方法](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/configuration.md)。

#### 檢測 HTTP 呼叫
<a name="instrumenting-http-calls"></a>

當請求之間未傳遞內容時，HTTP 呼叫可以分割追蹤：HTTP 用戶端必須使用 `NewRequestWithContext()`，而不是 `NewRequest()`，以確保下游服務使用相同的內容。當這兩個服務都有檢測代理程式時，範圍將透過同個追蹤 ID 連線，從而實現端對端的可視性。

```
func makeDownstreamCall(ctx context.Context, url string) ([]byte, error) {
    client := &http.Client{}
    
    // Create request with context from the upstream call
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }
    
    // Execute the request
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
}
```

#### 檢測 SQL 呼叫
<a name="instrumenting-sql-calls"></a>

SQL 範圍可能會與其父級範圍中斷連線，導致將用戶端呼叫被推斷為伺服器範圍。當 SQL 呼叫未從上游處理常式接收內容時，就會出現這種情況。依預設，`Query`、`Exec` 等標準 SQL 呼叫會使用 `context.Background()`，而不是上游呼叫者的內容。將標準 SQL 呼叫替換為其內容感知對等項目：
+ 使用 `QueryContext` 而非 `Query`
+ 使用 `ExecContext` 而非 `Exec`

這些方法會將上游請求內容傳遞至資料庫呼叫，以維持適當的追蹤持續性。

```
func queryDatabase(ctx context.Context, db *sql.DB, userID string) (*sql.Rows, error) {
    // This breaks the trace context
    // row := db.Query("SELECT name FROM users WHERE id = $1", userID)
    
    // This passes the context from the upstream call for trace continuity
    rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE id = $1", userID)
    
    return rows, error
}
```

**注意**  
SQL 呼叫目前不支援 `db.system` 屬性。此限制會影響 CloudWatch 準確識別資料庫用戶端的能力。因此，相依項會顯示 **UnknownRemoteService**，而非執行查詢的資料庫用戶端名稱。

#### 資源偵測器
<a name="resource-detectors"></a>

Go 自動檢測功能目前不支援在執行時期設定資源偵測器。OpenTelemetry 社群正在開發使用環境變數設定資源偵測器的功能。我們將在未來的更新中提供此功能。同時，可以使用 CloudWatch 代理程式搭配自動檢測功能來自動產生主機資源屬性。

## 執行時期版本支援矩陣
<a name="rumtime-version-matix"></a>




| Language | 執行時間版本 | 
| --- | --- | 
| Java | JVM 版本 8、11、17、21 和 23 | 
| Python | 支援 3.9 及以上版本的 Python | 
| .NET | 1.6.0 及以下版本支援 .NET 6、.NET 8 以及 .NET Framework 4.6.2 和更高版本<br />1.7.0 及以上版本支援 .NET 8、.NET 9 以及 .NET Framework 4.6.2 和更高版本 | 
| Node.js | Node.js 版本 14、16、18、20 和 22 | 
| PHP | PHP 版本 8.0 及更高版本 | 
| Ruby | CRuby >= 3.1、JRuby >= 9.3.2.0 或 TruffleRuby >= 22.1 | 
| GoLang | Golang 版本 1.18 及更高版本 | 

## 已知問題
<a name="AppSignals-Issues"></a>

已知 Java SDK v1.32.5 版本中的執行時期指標收集功能，無法與使用 JBoss Wildfly 的應用程式配合運作。此問題延伸到 Amazon CloudWatch Observability EKS 附加元件，影響版本 `2.3.0-eksbuild.1` 至 `2.6.0-eksbuild.1`。Java SDK 版本 `v1.32.6` 和 Amazon CloudWatch Observability EKS 附加元件版本 `v3.0.0-eksbuild.1` 中已修正此問題。

如果您受到影響，請將環境變數 `OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false` 新增至您的應用程式，以升級 Java SDK 版本或停用執行時期指標收集。