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

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

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

重要

仅支持 awsvpc 网络模式。EC2 和 Fargate 启动类型均受支持。

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

步骤 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。

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

步骤 3：准备 CloudWatch 代理配置

首先，在启用 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 代理检测您的应用程序

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

Java

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

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

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

将以下环境变量添加到您的应用程序容器中。您必须使用适用于 Java 的 Amazon Distro for OpenTelemetry 自动检测代理版本 1.32.2 或更高版本

环境变量	启用 Application Signals 的设置
`OTEL_RESOURCE_ATTRIBUTES`	将以下信息指定为键值对： `service.name` 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值，将使用默认值 `UnknownService`。 `deployment.environment` 设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。如果您未指定此项，则使用默认值 `generic:default`。此属性键仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。（可选）要启用跟踪日志关联，请将其他环境变量 `aws.log.group.names` 设置为应用程序日志的日志组名称。这样，应用程序的跟踪便可与该特定日志组的相关日志条目相关联。对于此变量，将 `$YOUR_APPLICATION_LOG_GROUP` 替换为应用程序的日志组名称。您还需要更改应用程序中的日志配置。有关更多信息，请参阅启用跟踪日志关联。
`OTEL_AWS_APPLICATION_SIGNALS_ENABLED`	设置为 `true` 可使您的容器开始向 Application Signals 发送 X-Ray 跟踪和 CloudWatch 指标。
`OTEL_METRICS_EXPORTER`	设置为 `none` 可禁用其他指标导出程序。
`OTEL_LOGS_EXPORTER`	设置为 `none` 以禁用其他日志导出程序。
`OTEL_EXPORTER_OTLP_PROTOCOL`	设置为 `http/protobuf` 以使用 HTTP 将指标和跟踪发送到 Application Signals。
`OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT`	设置为 `http://localhost:4316/v1/metrics` 可将指标发送到 CloudWatch sidecar。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	设置为 `http://localhost:4316/v1/traces` 可向 CloudWatch sidecar 发送跟踪。
`OTEL_TRACES_SAMPLER`	将此项设置为 `xray` 以将 X-Ray 设置为跟踪取样器。
`OTEL_PROPAGATORS`	将 `xray` 设置为传播器之一。
`JAVA_TOOL_OPTIONS`	设置为 `" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"`。将 `AWS_ADOT_JAVA_INSTRUMENTATION_PATH` 替换为存储 Amazon Distro for OpenTelemetry Java 自动检测代理的路径。例如，`/otel-auto-instrumentation/javaagent.jar`

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

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


{
  "name": "my-app",
   ...
  "environment": [
    {
      "name": "OTEL_RESOURCE_ATTRIBUTES",
      "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,aws.hostedin.environment=$HOST_ENV,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"
    }
  ],
  "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`	将以下信息指定为键值对： `service.name` 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值，将使用默认值 `UnknownService`。 `deployment.environment` 设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。如果您未指定此项，则使用默认值 `generic:default`。此属性键仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。（可选）要启用跟踪日志关联，请将其他环境变量 `aws.log.group.names` 设置为应用程序日志的日志组名称。这样，应用程序的跟踪便可与该特定日志组的相关日志条目相关联。对于此变量，将 `$YOUR_APPLICATION_LOG_GROUP` 替换为应用程序的日志组名称。您还需要更改应用程序中的日志配置。有关更多信息，请参阅启用跟踪日志关联。
`OTEL_AWS_APPLICATION_SIGNALS_ENABLED`	设置为 `true` 可使您的容器开始向 Application Signals 发送 X-Ray 跟踪和 CloudWatch 指标。
`OTEL_METRICS_EXPORTER`	设置为 `none` 可禁用其他指标导出程序。
`OTEL_EXPORTER_OTLP_PROTOCOL`	设置为 `http/protobuf` 以使用 HTTP 向 CloudWatch 发送指标和跟踪。
`OTEL_AWS_APPLICATION_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`	将此项设置为 `xray` 以将 X-Ray 设置为跟踪取样器。
`OTEL_PROPAGATORS`	将 `xray` 添加为传播器之一。
`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。在以下示例中，OTEL_RESOURCE_ATTRIBUTES 的值包括一个有助于启用跟踪日志关联的可选 aws.log.group.names。有关更多信息，请参阅上一步中的表。

对于 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,aws.hostedin.environment=$HOST_ENV,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
    }
  ]
}

步骤 5：部署应用程序

创建任务定义的新修订版并将其部署到您的应用程序集群。您应该在新创建的任务中看到三个容器：

init
ecs-cwagent
my-app

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

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

在 Amazon EC2、Amazon ECS 或 Kubernetes 上启用 Application Signals

在 Amazon EC2 上启用 Application Signals