在 Amazon EKS 集群上启用应用程序

为现有 Amazon EKS 集群上的应用程序启用 Application Signals

1. 通过 https://console.aws.amazon.com/cloudwatch/ 打开 CloudWatch 控制台。

2. 选择 Application Signals。

3. 在指定平台中，选择 EKS。

4. 在选择 EKS 集群中，选择要在其中启用 Application Signals 的集群。

5. 如果此集群尚未启用 Amazon CloudWatch Observability EKS 附加组件，则系统会提示您将其启用。在这种情况下，请执行以下操作：

   1. 选择添加 CloudWatch Observability EKS 附加组件。Amazon EKS 控制台出现。

   2. 选中 Amazon CloudWatch Observability 对应的复选框，然后选择下一步。

      CloudWatch Observability EKS 附加组件启用 Application Signals 和 CloudWatch Container Insights，从而增强 Amazon EKS 的可观测性。有关安装 Container Insights 的更多信息，请参阅 Container Insights。

   3. 选择要安装的最新版本的附加组件。

   4. 选择要用于附加组件的 IAM 角色。如果您选择从节点继承，请将正确的权限附加到您的 Worker 节点使用的 IAM 角色。将 my-worker-node-role 替换为您的 Kubernetes Worker 节点使用的 IAM 角色。

      aws iam attach-role-policy \
      --role-name my-worker-node-role \
      --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
      --policy-arn arn:aws:iam::aws:policy/AWSXRayWriteOnlyAccess

   5. 如果您想要创建服务角色以使用附加组件，请参阅 使用 Amazon CloudWatch Observability EKS 附加组件或 Helm 图表安装 CloudWatch 代理。

   6. 选择下一步，确认屏幕上的信息，然后选择创建。

   7. 在下一个屏幕中，选择启用 CloudWatch Application Signals 以返回 CloudWatch 控制台并完成该过程。

6. 有两个选项可以为您的应用程序启用 Application Signals。为保持一致性，建议您为每个集群选择一个选项。

   • 控制台选项更简单。使用此方法会导致您的容器组（pod）立即重启。

   • 注释清单文件方法可以让您更好地控制容器组（pod）何时重启；如果您不想集中监控，还可以帮助您以更分散的方式管理监控。

   注意

   要为使用 ESM 的 Node.js 应用程序启用 Application Signals，改为跳转到设置采用 ESM 模块格式的 Node.js 应用程序。

   Console

   控制台选项使用 Amazon CloudWatch Observability EKS 附加组件的高级配置，为您的服务设置 Application Signals。有关附加组件的更多信息，请参阅 （可选）其他配置。

   如果没有看到工作负载和命名空间列表，则请确保您拥有查看该集群工作负载和命名空间的适当权限。有关更多信息，请参阅所需权限。

   您可以通过选中自动监控复选框来监控所有服务工作负载，也可以有选择地选取要监控的特定工作负载和命名空间。

   要使用“自动监控”功能来监控所有服务工作负载，请执行以下操作：

   1. 选中自动监控复选框，自动选择集群中的所有服务工作负载。

   2. 选择自动重启功能重启所有工作负载容器组（pod），将 Amazon Distro for OpenTelemetry 自动检测（ADOT）SDK 注入容器组（pod）中，即可立即启用 Application Signals。

   3. 选择完成。选择自动重启后，CloudWatch 可观测性 EKS 附加组件将立即启用 Application Signals。否则，将在每个工作负载的下次部署期间启用 Application Signals。

   您可以监控单个工作负载或整个命名空间。

   要监控单个工作负载，请执行以下操作：

   1. 选中要监控的工作负载旁的复选框。

   2. 使用选择语言下拉列表选择工作负载的语言。选择要为其启用 Application Signals 的语言，然后选择复选标记图标（✓）以保存此选择。

      对于 Python 应用程序，请确保您的应用程序符合所需的先决条件，然后再继续。有关更多信息，请参阅 启用 Application Signals 后，Python 应用程序无法启动。

   3. 选择完成。Amazon CloudWatch Observability EKS 附加组件会立即将 Amazon Distro for OpenTelemetry 自动检测（ADOT）SDK 注入到您的容器组（pod）中，并触发容器组（pod）重启以允许收集应用程序指标和跟踪。

   要监控整个命名空间，请执行以下操作：

   1. 选中要监控的命名空间旁的复选框。

   2. 使用选择语言下拉列表选择命名空间的语言。选择要为其启用 Application Signals 的语言，然后选择复选标记图标（✓）以保存此选择。此操作将该语言应用到此命名空间中的所有工作负载，无论其当前已部署还是将在未来部署。

      对于 Python 应用程序，请确保您的应用程序符合所需的先决条件，然后再继续。有关更多信息，请参阅 启用 Application Signals 后，Python 应用程序无法启动。

   3. 选择完成。Amazon CloudWatch Observability EKS 附加组件会立即将 Amazon Distro for OpenTelemetry 自动检测（ADOT）SDK 注入到您的容器组（pod）中，并触发容器组（pod）重启以允许收集应用程序指标和跟踪。

   要在另一个 Amazon EKS 集群中启用 Application Signals，请从服务屏幕中选择启用 Application Signals。

   Annotate manifest file

   在 CloudWatch 控制台中，监控服务部分说明了您必须向集群中的清单 YAML 添加注释。添加此注释会自动检测应用程序以向 Application Signals 发送指标、跟踪和日志。

   您有两种注释选项：

   • 注释工作负载会自动检测集群中的单个工作负载。

   • 注释命名空间会自动检测所选命名空间中部署的所有工作负载。

   选择其中一个选项，然后按照相应的步骤操作：

   • 要为单个工作负载添加注释，请执行以下操作：

     1. 选择注释工作负载。

     2. 将以下行之一粘贴到工作负载清单文件的 PodTemplate 部分。

        • 对于 Java 工作负载：annotations: instrumentation.opentelemetry.io/inject-java: "true"

        • 对于 Python 工作负载：annotations: instrumentation.opentelemetry.io/inject-python: "true"

          对于 Python 应用程序，还需要额外的配置。有关更多信息，请参阅 启用 Application Signals 后，Python 应用程序无法启动。

        • 对于 .NET 工作负载 annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"

          注意

          要在基于 Alpine Linux (linux-musl-x64) 的映像上为 .NET 工作负载启用 Application Signals，请添加以下注释。

          instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64"

        • 对于 Node.js 工作负载：annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"

     3. 在您的终端中，输入 kubectl apply -f your_deployment_yaml 以应用更改。

   • 要为命名空间中的所有工作负载添加注释，请执行以下操作：

     1. 选择注释命名空间。

     2. 将以下行之一粘贴到命名空间清单文件的元数据部分。如果命名空间包含 Java、Python 和 NET 工作负载，请将以下所有行都粘贴到命名空间清单文件中。

        • 如果命名空间中有 Java 工作负载：annotations: instrumentation.opentelemetry.io/inject-java: "true"

        • 如果命名空间中有 Python 工作负载：annotations: instrumentation.opentelemetry.io/inject-python: "true"

          对于 Python 应用程序，还需要额外的配置。有关更多信息，请参阅 启用 Application Signals 后，Python 应用程序无法启动。

        • 如果命名空间中有 .NET 工作负载：annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"

        • 如果命名空间中有 Node.JS 工作负载：annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"

     3. 在您的终端中，输入 kubectl apply -f your_namespace_yaml 以应用更改。

     4. 在您的终端中，输入命令以重启命名空间中的所有容器组（pod）。重启部署工作负载的命令示例是 kubectl rollout restart deployment -n namespace_name

7. 选择完成后查看服务。这将带您进入 Application Signals 服务视图，您可以在其中查看 Application Signals 正在收集的数据。可能需要几分钟才会显示数据。

   要在另一个 Amazon EKS 集群中启用 Application Signals，请从服务屏幕中选择启用 Application Signals。

   有关服务视图的更多信息，请参阅 使用 Application Signals 监控应用程序的运行状况。

为使用 ESM 的 Node.js 应用程序启用 Application Signals

1. 将相关依赖项安装到您的 Node.js 应用程序中以进行自动检测：

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

2. 将以下环境变量添加到应用程序的 Dockerfile 中并构建映像。

   ...
   ENV OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
   ENV OTEL_TRACES_SAMPLER_ARG='endpoint=http://cloudwatch-agent.amazon-cloudwatch:2000'
   ENV OTEL_TRACES_SAMPLER='xray'
   ENV OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
   ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/traces'
   ENV OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/metrics'
   ENV OTEL_METRICS_EXPORTER='none'
   ENV OTEL_LOGS_EXPORTER='none'
   ENV NODE_OPTIONS='--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs'
   ENV OTEL_SERVICE_NAME='YOUR_SERVICE_NAME' #replace with a proper service name
   ENV OTEL_PROPAGATORS='tracecontext,baggage,b3,xray'
   ...
   
   # command to start the application
   # for example
   # CMD ["node", "index.mjs"]

3. 将环境变量 OTEL_RESOURCE_ATTRIBUTES_POD_NAME、OTEL_RESOURCE_ATTRIBUTES_NODE_NAME、OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME、POD_NAMESPACE 和 OTEL_RESOURCE_ATTRIBUTES 添加到应用程序的部署 yaml 文件中。例如：

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nodejs-app
     labels:
       app: nodejs-app
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: nodejs-app
     template:
       metadata:
         labels:
           app: nodejs-app
         # annotations:
         # make sure this annotation doesn't exit
         #   instrumentation.opentelemetry.io/inject-nodejs: 'true'
       spec:
         containers:
         - name: nodejs-app
           image:your-nodejs-application-image #replace with a proper image uri
           imagePullPolicy: Always
           ports:
           - containerPort: 8000
           env:
             - name: OTEL_RESOURCE_ATTRIBUTES_POD_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.name
             - name: OTEL_RESOURCE_ATTRIBUTES_NODE_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: spec.nodeName
             - name: OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.labels['app'] # Assuming 'app' label is set to the deployment name
             - name: POD_NAMESPACE
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.namespace
             - name: OTEL_RESOURCE_ATTRIBUTES
               value: "k8s.deployment.name=$(OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME)"

4. 将 Node.js 应用程序部署到集群。

1. 为您的应用程序启用 Application Signals。

   import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';
   
   const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
     'ApplicationSignalsServiceRole', { }
   );

   Discovery CloudFormation 资源授予 Application Signals 下列权限：

   • xray:GetServiceGraph

   • logs:StartQuery

   • logs:GetQueryResults

   • cloudwatch:GetMetricData

   • cloudwatch:ListMetrics

   • tag:GetResources

   有关该角色的更多信息，请参阅CloudWatch Application Signals 的服务相关角色权限。

2. 安装 amazon-cloudwatch-observability 插件。

   1. 使用 CloudWatchAgentServerPolicy 以及与集群关联的 OIDC 创建 IAM 角色。

      const cloudwatchRole = new Role(this, 'CloudWatchAgentAddOnRole', {
          assumedBy: new OpenIdConnectPrincipal(cluster.openIdConnectProvider),
          managedPolicies: [ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')],
      });

3. 使用上面创建的 IAM 角色安装附加组件。

   new CfnAddon(this, 'CloudWatchAddon', {
       addonName: 'amazon-cloudwatch-observability',
       clusterName: cluster.clusterName,
       serviceAccountRoleArn: cloudwatchRole.roleArn
   });

4. 将其中一行添加到工作负载清单文件的 PodTemplate 部分。

   语言	文件
   Java	instrumentation.opentelemetry.io/inject-java: "true"
   Python	instrumentation.opentelemetry.io/inject-python: "true"
   .Net	instrumentation.opentelemetry.io/inject-dotnet: "true"
   Node.js	instrumentation.opentelemetry.io/inject-nodejs: "true"

   const deployment = {
     apiVersion: "apps/v1",
     kind: "Deployment",
     metadata: { name: "sample-app" },
     spec: {
       replicas: 3,
       selector: {
         matchLabels: {
           "app": "sample-app"
         }
       },
       template: {
         metadata: {
           labels: {
             "app": "sample-app"
           },
           annotations: {
             "instrumentation.opentelemetry.io/inject-$LANG": "true"
           }
         },
         spec: {...},
       },
     },
   };
   
   cluster.addManifest('sample-app', deployment)