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

Application Signals 在 Amazon EKS、本机 Kubernetes、Amazon ECS 和 Amazon EC2 上受支持并经过测试。在 Amazon EC2 上启用 Application Signals 的指令应适用于任何支持 CloudWatch 代理和 Amazon 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 应用程序，也支持与适用于 OpenTelemetry 的 Amazon Distro 相同的 Java 库和框架。有关更多信息，请参阅 [Supported libraries, frameworks, application servers, and JVMs](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 与 Amazon Distro for OpenTelemetry 支持相同的 .NET 库和框架。有关更多信息，请参阅[支持的检测](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 的适用于 OpenTelemetry 的 Amazon Distro（ADOT）SDK，不支持适用于 .NET 的 Amazon SDK V4 版本。如需获得 Application Signals 的完整支持，请使用 Amazon SDK .NET V3 版本。

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

Application Signals 支持通过 OpenTelemetry 零代码插桩为 PHP 应用程序提供服务。目前没有适用于此目的的 Amazon Distro for Open Telemetry（ADOT）SDK。您应使用已启用[事务搜索](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html)功能的标准 OpenTelemetry 插桩 SDK。要开始在 PHP 中使用零代码插桩，请按照 OpenTelemetry PHP 插桩文档中“[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 应用程序提供服务。目前没有适用于此目的的 Amazon Distro for Open Telemetry（ADOT）SDK。您应使用已启用[事务搜索](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html)功能的标准 OpenTelemetry 插桩 SDK。要开始在 Ruby 中使用零代码插桩，请按照 OpenTelemetry Ruby 插桩文档“[Ruby 零代码插桩](https://opentelemetry.io/docs/languages/ruby/getting-started/#instrumentation)”部分的步骤操作。有关已发布的插桩库列表，请参阅 [Registry](https://opentelemetry.io/ecosystem/registry/?language=rubycomponent=instrumentation)。

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

Application Signals 支持与 Amazon Distro for OpenTelemetry 相同的库和框架。有关更多信息，请参阅 [opentelemetry-python-contrib](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/README.md) 上的 **Supported packages**。

在为 Python 应用程序启用 Application Signals 之前，请注意以下注意事项。
+ 在某些容器化应用程序中，缺少 `PYTHONPATH` 环境变量有时可能会导致应用程序无法启动。要解决此问题，请确保将 `PYTHONPATH` 环境变量设置为应用程序工作目录的位置。这是由于 OpenTelemetry 自动检测的已知问题造成的。有关此问题的更多信息，请参阅 [Python autoinstrumentation setting of PYTHONPATH is not compliant](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)（PYTHONPATH 的 Python 自动检测设置不兼容）。
+ 对于 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 支持与 Amazon Distro for OpenTelemetry 相同的 Node.js 库和框架。有关更多信息，请参阅[支持的检测](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main)。

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

Amazon Distro for Opentelemetry Node.js 支持两种模块系统：ECMAScript 模块（ESM）和 CommonJS（CJS）。要启用 Application Signals，我们建议您使用 CJS 模块格式，因为 OpenTelemetry JavaScript 对 ESM 的支持处于实验阶段且仍在进行中。有关更多详情，请参阅 GitHub 上的 [ ECMAScript Modules vs. CommonJS](https://github.com/open-telemetry/opentelemetry-js/blob/eb3ca4fb07ee31c62093f5fcec56575573c902ce/doc/esm-support.md)。

要确定您的应用程序是否使用 CJS 而不是 ESM，请确保您的应用程序不满足启用 ESM 的条件。有关这些条件的更多信息，请参阅 Node.js 文档中的 [Enabling](https://nodejs.org/api/esm.html#enabling)。

Amazon 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 与 Amazon 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 应用程序提供服务。目前没有适用于此目的的 Amazon Distro for Open Telemetry（ADOT）SDK。您应使用已启用[事务搜索](AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html)功能的标准 OpenTelemetry 插桩 SDK。要开始在 GoLang 中使用零代码插桩，请按照 OpenTelemetry GoLang 插桩文档中“[Getting Started with OpenTelemetry Go Automatic Instrumentation](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/getting-started.md)”部分的步骤操作。

### GoLang 插桩的实现注意事项
<a name="implementation-considerations-golang"></a>

了解使用 GoLang 插桩时应注意的具体实现细节。本文将介绍使用 GoLang 插桩的重要实现细节，包括说明如何在 Go 应用程序中实现显式上下文传播，以及如何配置 Application Signals。正确实现 GoLang 插桩，有助于有效跟踪和分析应用程序的性能。

#### 配置 Amazon SDK 插桩
<a name="instrumenting-aws-sdk"></a>

Golang 自动插桩库默认不支持开箱即用型 Amazon 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` 对象创建后续 Amazon 客户端：

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

以下示例将为 Amazon 调用生成追踪跨度，并与自动插桩功能集成。

```
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
}
```

有关配置自动插桩可执行文件的信息，请参阅 [Configuration methods](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 调用未从其上游处理程序接收上下文时，就会发生这种情况。默认情况下，标准 SQL 调用（例如 `Query` 和 `Exec`）使用 `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>




| 语言 | 运行时版本 | 
| --- | --- | 
|  Java  |  JVM 版本 8、11、17、21 和 23  | 
|  Python  |  支持 Python 版本 3.9 及更高版本  | 
|  .NET  |  版本 1.6.0 及更低版本支持 .NET 6、8 和 .NET Framework 4.6.2 以及更高版本 版本 1.7.0 及更高版本支持 .NET 8、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 可观测性 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` 中修复。

如果您受到影响，请升级 Java SDK 版本或通过向应用程序添加环境变量 `OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false` 来禁用运行时指标收集。