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

# 使用附屬程式策略部署
<a name="CloudWatch-Application-Signals-ECS-Sidecar"></a>

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

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

## 步驟 2：建立 IAM 角色
<a name="CloudWatch-Application-Signals-Enable-ECS-IAM"></a>

必須建立 IAM 角色。如果已經建立此角色，可能需要為其新增許可。
+ **ECS 任務角色 —** 容器使用此角色來執行。應該根據應用程式的需要新增許可，外加 **CloudWatchAgentServerPolicy**。

如需建立 IAM 角色的詳細資訊，請參閱[建立 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。

## 步驟 3：準備 CloudWatch 代理程式組態
<a name="CloudWatch-Application-Signals-Enable-ECS-PrepareAgent"></a>

首先，在啟用 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 代理程式檢測您的應用程式
<a name="CloudWatch-Application-Signals-Enable-ECS-Instrument"></a>

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

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

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

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

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

1. 新增 CloudWatch 代理程式附屬定義。因此，請將名為 `ecs-cwagent` 的新容器附加到應用程式的任務定義。將 {{$REGION}} 取代為實際區域名稱。將 {{$IMAGE}} 替換為 Amazon Elastic Container Registry 上的最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果想要改用常駐程式策略啟用 CloudWatch 代理程式，請參閱 [使用常駐程式策略部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的指示。

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

1. 將新容器 `init` 附加到應用程式的任務定義。將 {{$IMAGE}} 取代為 [AWS Distro for OpenTelemetry Amazon ECR 映像儲存庫](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java)中的最新映像。

   ```
   {
     "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
       }
     ]
   }
   ```

1. 在 `init` 容器上新增相依項，確保此容器在應用程式容器啟動之前完成。

   ```
   "dependsOn": [
     {
       "containerName": "init",
       "condition": "SUCCESS"
     }
   ]
   ```

1. 將下列環境變數新增至應用程式容器。您必須使用適用於 Java 的 AWS Distro for OpenTelemetry 自動檢測代理程式 1.32.2 版或更新版本。 [https://opentelemetry.io/docs/zero-code/java/agent/](https://opentelemetry.io/docs/zero-code/java/agent/)    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 掛載您在此程序步驟 1 中定義的磁碟區 `opentelemetry-auto-instrumentation`。如果不需要啟用日誌與指標和追蹤的關聯，請針對 Java 應用程式使用以下範例。若要啟用日誌關聯功能，請參閱下一個步驟。

   ```
   {
     "name": "{{my-app}}",
      ...
     "environment": [
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "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"
       }
     ],
     "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation",
         "containerPath": "/otel-auto-instrumentation",
         "readOnly": false
       }
     ]
   }
   ```

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

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

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

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

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

1. 新增 CloudWatch 代理程式附屬定義。因此，請將名為 `ecs-cwagent` 的新容器附加到應用程式的任務定義。將 {{$REGION}} 取代為實際區域名稱。將 {{$IMAGE}} 替換為 Amazon Elastic Container Registry 上的最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果想要改用常駐程式策略啟用 CloudWatch 代理程式，請參閱 [使用常駐程式策略部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的指示。

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

1. 將新容器 `init` 附加到應用程式的任務定義。將 {{$IMAGE}} 取代為 [AWS Distro for OpenTelemetry Amazon ECR 映像儲存庫](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-python)中的最新映像。

   ```
   {
       "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
           }
       ]
   }
   ```

1. 在 `init` 容器上新增相依項，確保此容器在應用程式容器啟動之前完成。

   ```
   "dependsOn": [
     {
       "containerName": "init",
       "condition": "SUCCESS"
     }
   ]
   ```

1. 將下列環境變數新增至應用程式容器。    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 掛載您在此程序步驟 1 中定義的磁碟區 `opentelemetry-auto-instrumentation-python`。如果不需要啟用日誌與指標和追蹤的關聯，請針對 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": "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
       }
     ]
   }
   ```

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

   下列是 範例。若要啟用日誌關聯，請在掛載您在此程序的步驟 1 中定義之磁碟區 `opentelemetry-auto-instrumentation-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}},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
       }
     ]
   }
   ```

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

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

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

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

1. 新增 CloudWatch 代理程式附屬定義。因此，請將名為 `ecs-cwagent` 的新容器附加到應用程式的任務定義。將 {{$REGION}} 取代為實際區域名稱。將 {{$IMAGE}} 替換為 Amazon Elastic Container Registry 上的最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果想要改用常駐程式策略啟用 CloudWatch 代理程式，請參閱 [使用常駐程式策略部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的指示。

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

1. 將新容器 `init` 附加到應用程式的任務定義。將 {{$IMAGE}} 取代為 [AWS Distro for OpenTelemetry Amazon ECR 映像儲存庫](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-dotnet)中的最新映像。

   對於 Linux 容器執行個體，請使用下列格式。

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

   對於 Windows Server 容器執行個體，請使用下列格式。

   ```
   {
     "name": "init",
     "image": "{{$IMAGE}}",
     "essential": false,
     "command": [
         "CMD",
         "/c",
         "xcopy",
         "/e",
         "C:\\autoinstrumentation\\*",
         "C:\\otel-auto-instrumentation",
         "&&",
         "icacls",
         "C:\\otel-auto-instrumentation",
         "/grant",
         "*S-1-1-0:R",
         "/T"
     ],
     "mountPoints": [
         {
             "sourceVolume": "opentelemetry-auto-instrumentation",
             "containerPath": "C:\\otel-auto-instrumentation",
             "readOnly": false
         }
     ]
   }
   ```

1. 在 `init` 容器上新增相依項，確保此容器在應用程式容器啟動之前完成。

   ```
   "dependsOn": [
       {
           "containerName": "init",
           "condition": "SUCCESS"
       }
   ]
   ```

1. 將下列環境變數新增至應用程式容器。您必須使用適用於 .NET 的 AWS Distro for OpenTelemetry 自動檢測代理程式的 1.1.0 版或更新版本。[https://opentelemetry.io/docs/zero-code/net/](https://opentelemetry.io/docs/zero-code/net/)    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 掛載您在此程序步驟 1 中定義的磁碟區 `opentelemetry-auto-instrumentation`。對於 Linux，請使用下列格式。

   ```
   {
       "name": "my-app",
      ...
       "environment": [
           {
              "name": "OTEL_RESOURCE_ATTRIBUTES",
              "value": "service.name=$SVC_NAME"
          },
           {
               "name": "CORECLR_ENABLE_PROFILING",
               "value": "1"
           },
           {
               "name": "CORECLR_PROFILER",
               "value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
           },
           {
               "name": "CORECLR_PROFILER_PATH",
               "value": "/otel-auto-instrumentation/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so"
           },
           {
               "name": "DOTNET_ADDITIONAL_DEPS",
               "value": "/otel-auto-instrumentation/AdditionalDeps"
           },
           {
               "name": "DOTNET_SHARED_STORE",
               "value": "/otel-auto-instrumentation/store"
           },
           {
               "name": "DOTNET_STARTUP_HOOKS",
               "value": "/otel-auto-instrumentation/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
           },
           {
               "name": "OTEL_DOTNET_AUTO_HOME",
               "value": "/otel-auto-instrumentation"
           },
           {
               "name": "OTEL_DOTNET_AUTO_PLUGINS",
               "value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
           },
           {
               "name": "OTEL_RESOURCE_ATTRIBUTES",
               "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=aws-dotnet-service-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": "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_EXPORTER_OTLP_ENDPOINT",
               "value": "http://localhost:4316"
           },
           {
              "name": "OTEL_TRACES_SAMPLER",
              "value": "xray"
          },
          {
              "name": "OTEL_TRACES_SAMPLER_ARG",
              "value": "endpoint=http://localhost:2000"
          },
           {
               "name": "OTEL_PROPAGATORS",
               "value": "tracecontext,baggage,b3,xray"
           }
       ],
       "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ],
       "mountPoints": [
           {
               "sourceVolume": "opentelemetry-auto-instrumentation",
               "containerPath": "/otel-auto-instrumentation",
               "readOnly": false
           }
       ]
   }
   ```

   對於 Windows，請使用下列格式。

   ```
   {
       "name": "my-app",
      ...
       "environment": [
          {
              "name": "OTEL_RESOURCE_ATTRIBUTES",
              "value": "service.name=$SVC_NAME"
          },
           {
               "name": "CORECLR_ENABLE_PROFILING",
               "value": "1"
           },
           {
               "name": "CORECLR_PROFILER",
               "value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
           },
           {
               "name": "CORECLR_PROFILER_PATH",
               "value": "C:\\otel-auto-instrumentation\\win-x64\\OpenTelemetry.AutoInstrumentation.Native.dll"
           },
           {
               "name": "DOTNET_ADDITIONAL_DEPS",
               "value": "C:\\otel-auto-instrumentation\\AdditionalDeps"
           },
           {
               "name": "DOTNET_SHARED_STORE",
               "value": "C:\\otel-auto-instrumentation\\store"
           },
           {
               "name": "DOTNET_STARTUP_HOOKS",
               "value": "C:\\otel-auto-instrumentation\\net\\OpenTelemetry.AutoInstrumentation.StartupHook.dll"
           },
           {
               "name": "OTEL_DOTNET_AUTO_HOME",
               "value": "C:\\otel-auto-instrumentation"
           },
           {
               "name": "OTEL_DOTNET_AUTO_PLUGINS",
               "value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
           },
           {
               "name": "OTEL_RESOURCE_ATTRIBUTES",
               "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=dotnet-service-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": "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_EXPORTER_OTLP_ENDPOINT",
               "value": "http://localhost:4316"
           },
           {
              "name": "OTEL_TRACES_SAMPLER",
              "value": "xray"
          },
          {
              "name": "OTEL_TRACES_SAMPLER_ARG",
              "value": "endpoint=http://localhost:2000"
          },
           {
               "name": "OTEL_PROPAGATORS",
               "value": "tracecontext,baggage,b3,xray"
           }
       ],
       "mountPoints": [
           {
               "sourceVolume": "opentelemetry-auto-instrumentation",
               "containerPath": "C:\\otel-auto-instrumentation",
               "readOnly": false
           }
       ],
       "dependsOn": [
           {
               "containerName": "init",
               "condition": "SUCCESS"
           }
      ]
   }
   ```

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

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

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

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

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

1. 新增 CloudWatch 代理程式附屬定義。因此，請將名為 `ecs-cwagent` 的新容器附加到應用程式的任務定義。將 {{$REGION}} 取代為實際區域名稱。將 {{$IMAGE}} 替換為 Amazon Elastic Container Registry 上的最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果想要改用常駐程式策略啟用 CloudWatch 代理程式，請參閱 [使用常駐程式策略部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的指示。

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

1. 將新容器 `init` 附加到應用程式的任務定義。將 {{$IMAGE}} 取代為 [AWS Distro for OpenTelemetry Amazon ECR 映像儲存庫](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-node)中的最新映像。

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

1. 在 `init` 容器上新增相依項，確保此容器在應用程式容器啟動之前完成。

   ```
   "dependsOn": [
     {
       "containerName": "init",
       "condition": "SUCCESS"
     }
   ]
   ```

1. 將下列環境變數新增至應用程式容器。    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 掛載您在此程序步驟 1 中定義的磁碟區 `opentelemetry-auto-instrumentation`。如果不需要啟用日誌與指標和追蹤的關聯，請針對 Node.js 應用程式使用以下範例。若要啟用日誌關聯功能，請參閱下一個步驟。

   對於您的應用程式容器，請在 `init` 容器上新增相依項，以確保容器在應用程式容器啟動之前完成。

   ```
   {
     "name": "{{my-app}}",
      ...
     "environment": [
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "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": "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_TRACES_SAMPLER_ARG",
         "value": "endpoint=http://localhost:2000"
       },
       {
         "name": "NODE_OPTIONS",
         "value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
       }
       ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-node",
         "containerPath": "/otel-auto-instrumentation-node",
         "readOnly": false
       }
     ],
     "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ]
   }
   ```

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

   下列是 範例。當您掛載您在此程序的步驟 1 中定義之磁碟區 `opentelemetry-auto-instrumentation` 時，請參考此範例來啟用日誌關聯。

   ```
   {
     "name": "{{my-app}}",
      ...
     "environment": [
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "aws.log.group.names={{$YOUR_APPLICATION_LOG_GROUP}},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": "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_TRACES_SAMPLER_ARG",
         "value": "endpoint=http://localhost:2000"
       },
       {
         "name": "NODE_OPTIONS",
         "value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
       }
       ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-node",
         "containerPath": "/otel-auto-instrumentation-node",
         "readOnly": false
       }
     ],
     "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ]
   }
   ```<a name="ECS-NodeJs-ESM"></a>

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

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

對於 ESM 模組格式，無法使用 `init` 容器注入 Node.js 檢測 SDK。若要為採用 ESM 的 Node.js 啟用 Application Signals，請略過先前程序的步驟 1 和 3，改為執行以下動作：

**為採用 ESM 的 Node.js 應用程式啟用 Application Signals**

1. 將相關的相依項安裝到 Node.js 應用程式以進行自動檢測：

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

1. 在先前程序的步驟 5 和 6 中，移除磁碟區 `opentelemetry-auto-instrumentation-node` 的掛載：

   ```
    "mountPoints": [
       {
           "sourceVolume": "opentelemetry-auto-instrumentation-node",
           "containerPath": "/otel-auto-instrumentation-node",
           "readOnly": false
       }
    ]
   ```

   將節點選項替換為以下值。

   ```
   {
       "name": "NODE_OPTIONS",
       "value": "--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs"
   }
   ```

------

## 步驟 5：部署應用程式
<a name="CloudWatch-Application-Signals-Enable-ECS-Deploy"></a>

建立任務定義的新修訂版本，並將其部署到應用程式叢集。應該會在新建立的任務中看到三個容器：
+ `init`– 初始化 Application Signals 所需的容器。
+ `ecs-cwagent`– 執行 CloudWatch 代理程式的容器
+ `{{my-app}}`– 我們文件中的應用程式容器範例。在您的實際工作負載中，此特定容器可能不存在，或者可能被替換為您自己的服務容器。

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

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