步骤 1：在账户中启用 Application Signals 步骤 2：创建 IAM 角色步骤 3：准备 CloudWatch 代理配置步骤 4：使用 CloudWatch 代理检测您的应用程序步骤 5：部署应用程序

使用自定义设置在 Amazon ECS 上启用 Application Signals

Application Signals 目前为预览版。如果您对此功能有任何反馈，可以通过 app-signals-feedback@amazon.com 联系我们。

使用这些自定义设置说明，将您在 Amazon ECS 上的应用程序载入到 CloudWatch Application Signals。您可以自行安装并配置 CloudWatch 代理和 Amazon Distro for OpenTelemetry。

在 Amazon ECS 集群上，Application Signals 不会自动发现您的服务名称或运行这些服务的集群。您必须在自定义设置期间指定这些名称，而您指定的名称就是显示在 Application Signals 控制面板上的名称。

重要

仅支持 awsvpc 网络模式。

步骤 1：在账户中启用 Application Signals

如果您尚未在此账户中启用 Application Signals，则必须向 Application Signals 授予发现您的服务所需的权限。为此，请执行以下操作：您的账户只需执行一次该操作。

为您的应用程序启用 Application Signals

通过 https://console.aws.amazon.com/cloudwatch/ 打开 CloudWatch 控制台。
在导航窗格中，选择服务。
选择开始发现您的服务。
选中该复选框并选择开始发现服务。

首次在您的账户中完成此步骤会创建 AWSServiceRoleForCloudWatchApplicationSignals 服务相关角色。此角色授予 Application Signals 以下权限：
- xray:GetServiceGraph
- logs:StartQuery
- logs:GetQueryResults
- cloudwatch:GetMetricData
- cloudwatch:ListMetrics
- tag:GetResources
有关该角色的更多信息，请参阅 CloudWatch Application Signals 的服务相关角色权限。

步骤 2：创建 IAM 角色

您必须创建两个 IAM 角色。如果您已创建这些角色，则可能需要向其添加权限。

ECS 任务角色 – 容器使用此角色运行。权限应是您的应用程序所需的任何权限，以及 CloudWatchAgentServerPolicy 和 AWSXRayWriteOnlyAccess。
ECS 任务执行角色— Amazon ECS 使用此角色启动和执行您的容器。如果您已创建此角色，请将 AmazonSSMReadOnlyAccess、AmazonECSTaskExecutionRolePolicy 和 CloudWatchAgentServerPolicy 策略附加到此角色。

如果您需要存储更敏感的数据以供 Amazon ECS 使用，请参阅指定敏感数据以了解更多信息。

有关创建 IAM 角色的更多信息，请参阅创建 IAM 角色。

步骤 3：准备 CloudWatch 代理配置

首先，在启用 Application Signals 的情况下准备代理配置。为此，请创建一个名为 /tmp/ecs-cwagent.json 的本地文件。


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

然后，将此配置上传到 SSM 参数仓库中。要执行此操作，请输入以下命令。在该文件中，将 $REGION 替换为您的实际区域名称。


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

步骤 4：使用 CloudWatch 代理检测您的应用程序

下一步是为 CloudWatch Application Signals 检测您的应用程序。

Java

使用 CloudWatch 代理检测您在 Amazon ECS 上的应用程序

首先，指定绑定挂载。在接下来的步骤中，该卷将用于跨容器共享文件。您将在此过程的稍后部分使用此绑定挂载。
```
"volumes": [
  {
    "name": "opentelemetry-auto-instrumentation"
  }
]
```

添加 CloudWatch 代理 sidecar 定义。为此，请在应用程序的任务定义中追加一个名为 ecs-cwagent 的新容器。将 $REGION 替换为您的实际区域名称。替换为 Amazon Elastic Container Registry 上最新 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"
    }
  }
}

在应用程序的任务定义中添加一个新容器 init。将 $IMAGE 替换为 Amazon Distro for OpenTelemetry Amazon ECR 映像存储库中的最新映像。


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

将以下环境变量添加到您的应用程序容器中。有关更多信息，请参阅

环境变量	启用 Application Signals 的设置
`OTEL_RESOURCE_ATTRIBUTES`	将 `$SVC_NAME` 替换为您的应用程序的名称。这将作为应用程序的名称显示在 Application Signals 控制面板中。将 `$HOST_ENV` 替换为运行应用程序的主机环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。
`OTEL_AWS_APP_SIGNALS_ENABLED`	设置为 `true` 可启用 Application Signals SpanMetricsProcessor。
`OTEL_METRICS_EXPORTER`	设置为 `none` 可禁用其他指标导出程序。
`OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT`	设置为 `http://127.0.0.1:4315` 可将指标发送到 CloudWatch sidecar。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	设置为 `http://127.0.0.1:4315` 可向 CloudWatch sidecar 发送跟踪。
`OTEL_TRACES_SAMPLER`	将 X-Ray 定义为跟踪取样器。
`OTEL_PROPAGATORS`	将 X-Ray 添加为传播器之一。
`JAVA_TOOL_OPTIONS`	注入 Amazon Distro for OpenTelemetry Java 代理。

挂载您在此过程的步骤 1 中定义的卷 opentelemetry-auto-instrumentation。

对于 Java 应用程序，请使用以下命令。


{
  "name": "app",
   ...
  "environment": [
    {
      "name": "OTEL_RESOURCE_ATTRIBUTES",
      "value": "aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAME"
    },
    {
      "name": "OTEL_AWS_APP_SIGNALS_ENABLED",
      "value": "true"
    },
    {
      "name": "OTEL_METRICS_EXPORTER",
      "value": "none"
    },
    {
      "name": "JAVA_TOOL_OPTIONS",
      "value": " -javaagent:/otel-auto-instrumentation/javaagent.jar"
    },
    {
      "name": "OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT",
      "value": "http://127.0.0.1:4315"
    },
    {
      "name": "OTEL_TRACES_SAMPLER",
      "value": "xray"
    },
    {
      "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
      "value": "http://127.0.0.1:4315"
    },
    {
      "name": "OTEL_PROPAGATORS",
      "value": "tracecontext,baggage,b3,xray"
    }
  ],
  "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（PYTHONPATH 的 Python 自动检测设置不兼容）。
对于 Django 应用程序，还有其他必需的配置，这些配置在 OpenTelemetry Python 文档中进行了概述。
- 使用 --noreload 标志可防止自动重新加载。
- 将 DJANGO_SETTINGS_MODULE 环境变量设置为 Django 应用程序 settings.py 文件的位置。这样可确保 OpenTelemetry 能够正确访问您的 Django 设置，并与之集成。

使用 CloudWatch 代理检测您在 Amazon ECS 上的 Python 应用程序

首先，指定绑定挂载。在接下来的步骤中，该卷将用于跨容器共享文件。您将在此过程的稍后部分使用此绑定挂载。
```
"volumes": [
  {
    "name": "opentelemetry-auto-instrumentation-python"
  }
]
```


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

在应用程序的任务定义中添加一个新容器 init。将 $IMAGE 替换为 Amazon Distro for OpenTelemetry Amazon ECR 映像存储库中的最新映像。


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

将以下环境变量添加到您的应用程序容器中。有关更多信息，请参阅

环境变量	启用 Application Signals 的设置
`OTEL_RESOURCE_ATTRIBUTES`	将 `$SVC_NAME` 替换为您的应用程序的名称。这将作为应用程序的名称显示在 Application Signals 控制面板中。将 `$HOST_ENV` 替换为运行应用程序的主机环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。
`OTEL_AWS_APP_SIGNALS_ENABLED`	设置为 `true` 可启用 Application Signals SpanMetricsProcessor。
`OTEL_METRICS_EXPORTER`	设置为 `none` 可禁用其他指标导出程序。
`OTEL_EXPORTER_OTLP_PROTOCOL`	设置为 `http/protobuf` 以使用 HTTP 向 CloudWatch 发送指标和跟踪。
`OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT`	设置为 `http://127.0.0.1:4316/v1/metrics` 可将指标发送到 CloudWatch sidecar。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	设置为 `http://127.0.0.1:4316/v1/traces` 可向 CloudWatch sidecar 发送跟踪。
`OTEL_TRACES_SAMPLER`	将 X-Ray 定义为跟踪取样器。
`OTEL_PROPAGATORS`	将 X-Ray 添加为传播器之一。
`OTEL_PYTHON_DISTRO`	设置为 `aws_distro` 以使用 ADOT Python 工具。
`OTEL_PYTHON_CONFIGURATOR`	设置为 `aws_configuration` 以使用 ADOT Python 配置。
`PYTHONPATH`	将 `$APP_PATH` 替换为容器中应用程序工作目录的位置。Python 解释器查找您的应用程序模块需要执行此操作。
`DJANGO_SETTINGS_MODULE`	仅 Django 应用程序需要。将其设置为 Django 应用程序 `settings.py` 文件的位置。替换 `$PATH_TO_SETTINGS`。

挂载您在此过程的步骤 1 中定义的卷 opentelemetry-auto-instrumentation-python。

对于 Python 应用程序，请使用以下命令。


{
    "name": "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_APP_SIGNALS_EXPORTER_ENDPOINT",
            "value": "http://localhost:4316/v1/metrics"
        },
        {
            "name": "OTEL_METRICS_EXPORTER",
            "value": "none"
        },
        {
            "name": "OTEL_AWS_APP_SIGNALS_ENABLED",
            "value": "true"
        },
        {
            "name": "OTEL_RESOURCE_ATTRIBUTES",
            "value": "aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAM"
        },
        {
            "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
app

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

使用自定义设置在其他平台上启用 Application Signals

使用自定义设置在 Amazon EC2 和其他平台上启用 Application Signals