Habilitación de Application Signals en Amazon ECS, Amazon EKS o Lambda con el AWS CDK

Para habilitar Application Signals en Amazon ECS, Amazon EKS o Lambda, haga lo siguiente.

Amazon ECS

Si aún no ha activado Application Signals en esta cuenta, debe conceder a Application Signals los permisos que necesita para detectar los servicios.

Paso 1: habilite Application Signals para sus aplicaciones.

import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';

const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
  'ApplicationSignalsServiceRole', { }
);

El recurso Discovery de CloudFormation otorga a Application Signals los siguientes permisos:

• xray:GetServiceGraph

• logs:StartQuery

• logs:GetQueryResults

• cloudwatch:GetMetricData

• cloudwatch:ListMetrics

• tag:GetResources

Para obtener más información acerca de este rol, consulte Permisos de roles vinculados a un servicio para CloudWatch Application Signals.

Paso 2: cree roles de IAM.

Debe crear un rol de IAM. Si ya creó este rol, es posible que deba agregarle permisos.

ECS task role— (Función de tarea de ECS) Los contenedores utilizan esta función para ejecutarse. Los permisos deben ser los que necesiten las aplicaciones, además de CloudWatchAgentServerPolicy.

Para obtener más información acerca de cómo crear Roles de IAM, consulte Creating IAM Roles (Creación de Roles de IAM).

Paso 3: instrumente la aplicación con el agente de CloudWatch en el AWS CDK.

Para habilitar Application Signals para Amazon ECS mediante AWS CDK, siga los pasos que se detallan a continuación. Los fragmentos de código de este documento se proporcionan en TypeScript. Para ver alternativas específicas para otros lenguajes, consulte Lenguajes de programación admitidos para cloudwatch-agent en AWS CDK

Para instrumentar la aplicación con el agente de CloudWatch

1. En la definición de tarea de la aplicación, especifique un montaje de unión. Sustituya MOUNT_VOLUME según el lenguaje que utilice la aplicación. Por ejemplo, utilice opentelemetry-auto-instrumentation en Java. El volumen se utilizará para compartir archivos entre contenedores en los siguientes pasos. Empleará este montaje de unión más adelante en este procedimiento:

   const taskDefinition = new ecs.FargateTaskDefinition(this, 'MyTaskDefinition', {
     ...
     volumes: [{
       name: MOUNT_VOLUME,
     }]
    );
   
   

2. A continuación, agregue el agente de CloudWatch. Existen dos métodos posibles para agregar el agente de CloudWatch: la estrategia de sidecar y la estrategia de daemon. Para obtener información sobre las ventajas y desventajas de cada método, consulte Use una configuración personalizada para habilitar Application Signals en Amazon ECS y seleccione el mejor método para su entorno.

   • Estrategia de sidecar: agregue un nuevo contenedor denominado ecs-cwagent a la definición de tarea de la aplicación. Sustituya $IMAGE por la ruta a la imagen más reciente del contenedor de CloudWatch en Amazon Elastic Container Registry. Para obtener más información, consulte cloudwatch-agent en Amazon ECR.

     const cwAgentContainer = taskDefinition.addContainer('ecs-cwagent', {
       image: ecs.ContainerImage.fromRegistry("$IMAGE"),
       environment: {
         CW_CONFIG_CONTENT: '{"agent": {"debug": true}, "traces": {"traces_collected": {"application_signals": {"enabled": true}}}, "logs": {"metrics_collected": {"application_signals": {"enabled": true}}}}',
       },
       logging: new ecs.AwsLogDriver({
         streamPrefix: 'ecs',
         logGroup: new logs.LogGroup(this, 'CwAgentLogGroup', {
           logGroupName: '/ecs/ecs-cwagent',
         }),
       }),
     });

   • Estrategia de daemon: cree un nuevo servicio denominado ecs-cwagent en su pila. Sustituya $TASK_ROLE_ARN y $EXECUTION_ROLE_ARN por los roles de IAM que creó. Sustituya $IMAGE por la ruta a la imagen más reciente del contenedor de CloudWatch en Amazon Elastic Container Registry. Para obtener más información, consulte cloudwatch-agent en Amazon ECR.

     nota

     El servicio de daemon expone dos puertos del host: el 4316 se utiliza como punto de conexión para recibir métricas y seguimientos, mientras que el 2000 es el punto de conexión del muestreador de seguimientos de CloudWatch. Esta configuración permite al agente recopilar y transmitir datos de telemetría de todas las tareas de aplicación que se ejecuten en el host. Asegúrese de que otros servicios del host no utilicen estos puertos para evitar conflictos.

     const cwAgentTaskDefinition = new ecs.Ec2TaskDefinition(this, 'CwAgentDaemonTaskDef', {
         taskRole: "$TASK_ROLE_ARN",
         executionRole: "$EXECUTION_ROLE_ARN",
     });
     
     // Add the CloudWatch agent container
     const cwAgentContainer = cwAgentTaskDefinition.addContainer('ecs-cwagent', {
         image: ecs.ContainerImage.fromRegistry("$IMAGE"),
         cpu: 128,
         memoryLimitMiB: 64,
         portMappings: [
             {
                 containerPort: 4316,
                 hostPort: 4316,
             },
             {
                 containerPort: 2000,
                 hostPort: 2000,
             },
         ],
         logging: new ecs.AwsLogDriver({
             streamPrefix: 'ecs',
             logGroup: new logs.LogGroup(this, 'CwAgentLogGroup', {
                 logGroupName: '/ecs/ecs-cwagent-daemon',
             }),
         }),
         environment: {
             CW_CONFIG_CONTENT: '{"agent": {"debug": true}, "traces": {"traces_collected": {"application_signals": {"enabled": true}}}, "logs": {"metrics_collected": {"application_signals": {"enabled": true}}}}',
         },
     });
     
     // Add the CloudWatch agent service running as a daemon
     const cwAgentService = new ecs.Ec2Service(this, 'CwAgentDaemonService', {
         cluster,
         taskDefinition: cwAgentTaskDefinition,
         daemon: true,
     });

3. Agregue un nuevo inicio de contenedor a la definición de tareas de la aplicación. Sustituya $IMAGE por la imagen más reciente del repositorio de imágenes AWS Distro para OpenTelemetry de Amazon ECR. Sustituya MOUNT_CONTAINER_PATH e INIT_CONTAINER_COMMAND según el lenguaje que utilice la aplicación.

   Por ejemplo, utilice INIT_CONTAINER_COMMAND=["cp", "/javaagent.jar", "/otel-auto-instrumentation/javaagent.jar"], MOUNT_CONTAINER_PATH='/otel-auto-instrumentation' en Java.

   const initContainer = taskDefinition.addContainer('init', {
       image: ecs.ContainerImage.fromRegistry("$IMAGE"),
       essential: false,
       command: INIT_CONTAINER_COMMAND
   });
   
   initContainer.addMountPoints({
       sourceVolume: MOUNT_VOLUME,
       containerPath: MOUNT_CONTAINER_PATH,
       readOnly: false
   });

4. Agregue las variables de entorno ENVIRONMENT_VARIABLES al contenedor de la aplicación según el lenguaje que utilice la aplicación. Y monte el volumen MOUNT_VOLUME en el contenedor de la aplicación.

   nota

   Para obtener instrucciones de configuración específicas para varios lenguajes con los valores de MOUNT_VOLUME>, MOUNT_CONTAINER_PATH>, INIT_CONTAINER_COMMAND> y ENVIRONMENT_VARIABLES, consulte Paso 4: instrumentar la aplicación con el agente de CloudWatch.

   A continuación, se muestra un ejemplo:

   const appContainer = taskDefinition.addContainer('my-app', {
       ...
       environment: {
           ...
           ENVIRONMENT_VARIABLES
       },
   });
   
   appContainer.addMountPoints({
       sourceVolume: MOUNT_VOLUME,
       containerPath: MOUNT_CONTAINER_PATH,
       readOnly: false
   });
   
   appContainer.addContainerDependencies({
       container: initContainer,
       condition: ecs.ContainerDependencyCondition.SUCCESS
   });

Paso 4: configure una aplicación Node.js con el formato de módulo ESM.

La compatibilidad ofrecida para las aplicaciones Node.js con el formato de módulo ESM es limitada. Para obtener más información, consulte Limitaciones conocidas de Node.js con ESM.

La habilitación de Application Signals mediante el uso del contenedor init para inyectar el SDK de instrumentación de Node.js no aplica para el formato de módulo ESM. Omita los pasos 1 y 3 del procedimiento anterior y siga estos pasos:

Para habilitar Application Signals para una aplicación Node.js con ESM

1. Instale en su aplicación Node.js las dependencias pertinentes para la autoinstrumentación:

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

2. En el paso 4 del procedimiento anterior, retire el montaje del volumen.

   appContainer.addMountPoints({
       sourceVolume: MOUNT_VOLUME,
       containerPath: MOUNT_CONTAINER_PATH,
       readOnly: false
   });

   Y ajuste la variable de entorno NODE_OPTIONS a --import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs

Paso 5: implemente la pila actualizada.

Ejecute el comando cdk synth en el directorio principal de la aplicación. Para implementar el servicio en su cuenta de AWS, ejecute el comando cdk deploy en el directorio principal de la aplicación.

Si ha utilizado la estrategia de sidecar, verá que se ha creado un servicio:

• APPLICATION_SERVICE es el servicio de la aplicación. Incluye los tres contenedores siguientes:

  • init: contenedor necesario para inicializar Application Signals.

  • ecs-cwagent: contenedor que ejecuta el agente de CloudWatch.

  • my-app: este es el ejemplo de contenedor de aplicaciones de nuestra documentación. En las cargas de trabajo reales, es posible que no exista este contenedor específico, o que se sustituya por sus propios contenedores de servicio.

Si ha utilizado la estrategia de daemon, verá que se han creado dos servicios:

• CWAGentDaemonService es el servicio de daemon del agente de CloudWatch.

• APPLICATION_SERVICE es el servicio de la aplicación. Incluye los dos contenedores siguientes:

  • init: contenedor necesario para inicializar Application Signals.

  • my-app: este es el ejemplo de contenedor de aplicaciones de nuestra documentación. En las cargas de trabajo reales, es posible que no exista este contenedor específico, o que se sustituya por sus propios contenedores de servicio.

Amazon EKS

Si aún no ha activado Application Signals en esta cuenta, debe conceder a Application Signals los permisos que necesita para detectar los servicios.

Paso 1: habilite Application Signals para sus aplicaciones.

import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';

const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
  'ApplicationSignalsServiceRole', { }
);

El recurso Discovery de CloudFormation otorga a Application Signals los siguientes permisos:

• xray:GetServiceGraph

• logs:StartQuery

• logs:GetQueryResults

• cloudwatch:GetMetricData

• cloudwatch:ListMetrics

• tag:GetResources

Para obtener más información acerca de este rol, consulte Permisos de roles vinculados a un servicio para CloudWatch Application Signals.

Paso 2: instale el complemento de observabilidad de Amazon CloudWatch.

1. Cree un rol de IAM con la CloudWatchAgentServerPolicy y el OIDC asociado al clúster.

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

2. Instale el complemento con el rol de IAM creado anteriormente.

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

3. Añada una de las siguientes opciones en la sección PodTemplate del archivo de manifiesto de carga de trabajo.

   Idioma	Archivos
   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)

Lambda

Si aún no ha activado Application Signals en esta cuenta, debe conceder a Application Signals los permisos que necesita para detectar los servicios.

Paso 1: habilite Application Signals para sus aplicaciones.

import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';

const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
  'ApplicationSignalsServiceRole', { }
);

El recurso Discovery de CloudFormation otorga a Application Signals los siguientes permisos:

• xray:GetServiceGraph

• logs:StartQuery

• logs:GetQueryResults

• cloudwatch:GetMetricData

• cloudwatch:ListMetrics

• tag:GetResources

Para obtener más información acerca de este rol, consulte Permisos de roles vinculados a un servicio para CloudWatch Application Signals.

Paso 2: asocie la política de IAM.

Agregue la CloudWatchLambdaApplicationSignalsExecutionRolePolicy a su función de Lambda.

const fn = new Function(this, 'DemoFunction', {
    code: Code.fromAsset('$YOUR_LAMBDA.zip'),
    runtime: Runtime.PYTHON_3_12,
    handler: '$YOUR_HANDLER'
})

fn.role?.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName('CloudWatchLambdaApplicationSignalsExecutionRolePolicy'));

Paso 3: añada la capa de Application Signals.

Sustituya $APPLICATION_SIGNALS_LAMBDA_LAYER_ARN por el ARN real de la capa lambda de Application Signals en la región correspondiente.

fn.addLayers(LayerVersion.fromLayerVersionArn(
    this, 'ApplicationSignalsLayer',
    '$APPLICATION_SIGNALS_LAMBDA_LAYER_ARN'
))
fn.addEnvironment("AWS_LAMBDA_EXEC_WRAPPER", "/opt/otel-instrument");