Paso 1: habilitar Application Signals en la cuenta Paso 2: crear roles de IAM Paso 3: preparar la configuración del agente de CloudWatch Paso 4: instrumentar la aplicación con el agente de CloudWatch Paso 5: implementar la aplicación

Use una configuración personalizada para habilitar Application Signals en Amazon ECS

Utilice estas instrucciones de configuración personalizadas para incorporar aplicaciones de Amazon ECS a CloudWatch Application Signals. Usted instala y configura el agente y la distribución de CloudWatch para AWS OpenTelemetry.

importante

Solo se admite el modo de red awsvpc. Ambos tipos de lanzamiento, EC2 y Fargate, son compatibles.

En los clústeres de Amazon ECS, Application Signals no descubre automáticamente los nombres de sus servicios. Debe especificar los nombres de sus servicios durante la configuración personalizada; los nombres que especifique son los que aparecen en los paneles de Application Signals.

Paso 1: habilitar Application Signals en la cuenta

Si aún no ha activado Application Signals en esta cuenta, debe conceder a Application Signals los permisos que necesita para descubrir los servicios. Para ello, haga lo siguiente. Solo es necesario hacerlo una vez para la cuenta.

Para habilitar Application Signals para las aplicaciones

Abra la consola de CloudWatch en https://console.aws.amazon.com/cloudwatch/.
En el panel de navegación, elija Servicios.
Elija Comenzar a descubrir sus servicios.
Seleccione la casilla de verificación y elija Empezar a descubrir servicios.

Al completar este paso por primera vez en la cuenta, se crea el rol vinculado al servicio AWSServiceRoleForCloudWatchApplicationSignals. Este rol 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: crear 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: preparar la configuración del agente de CloudWatch

En primer lugar, prepare la configuración del agente con Application Signals habilitada. Para ello, cree un archivo local denominado /tmp/ecs-cwagent.json.


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

Luego, cargue esta configuración en el almacén de parámetros SSM. Para ello, ejecute el siguiente comando. En el archivo, sustituya $REGION por el nombre de la región actual.


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

Paso 4: instrumentar la aplicación con el agente de CloudWatch

El siguiente paso es configurar la aplicación para CloudWatch Application Signals.

Java

Para instrumentar la aplicación en Amazon ECS con el agente CloudWatch

En primer lugar, especifique un montaje de enlace. El volumen se utilizará para compartir archivos entre contenedores en los siguientes pasos. Usará este montaje de enlace más tarde en este procedimiento.
```
"volumes": [
  {
    "name": "opentelemetry-auto-instrumentation"
  }
]
```

Añada una definición de sidecar de agente de CloudWatch. Para ello, añada un nuevo contenedor llamado ecs-cwagent a la definición de tareas de la aplicación. Sustituya $REGION por el nombre de la región actual. 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.


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

Añada un nuevo contenedor init 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.


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

Añada las siguientes variables de entorno al contenedor de aplicaciones. Debe utilizar la versión 1.32.2 o posterior del agente de autoinstrumentación de AWS Distro para OpenTelemetry para Java

Variable de entorno	Configuración para habilitar Application Signals
`OTEL_RESOURCE_ATTRIBUTES`	Especifique la siguiente información como pares clave-valor: `service.name` establece el nombre del servicio. Se mostrará como el nombre del servicio de la aplicación en los paneles de Application Signals. Si no proporciona ningún valor para esta clave, se utiliza el valor predeterminado de `UnknownService`. `deployment.environment` establece el entorno en el que se ejecuta la aplicación. Se mostrará como el entorno alojado en de la aplicación en los paneles de Application Signals. Si no lo especifica, se utiliza el valor predeterminado de `generic:default`. Esta clave de atributo solo la usa Application Signals y se convierte en anotaciones de trazas de X-Ray y dimensiones métricas de CloudWatch. (Opcional) Para habilitar la correlación de registros de seguimientos, establezca una variable de entorno adicional `aws.log.group.names` como el nombre del grupo de registro para el registro de su aplicación. De este modo, los seguimientos de su aplicación se pueden correlacionar con las entradas de registro correspondientes de este grupo de registros específico. Para esta variable, sustituya `$YOUR_APPLICATION_LOG_GROUP` por el nombre del grupo de registros de su aplicación. También tendrá que cambiar la configuración de registro de la aplicación. Para obtener más información, consulte Habilite una correlación de los registros de seguimientos.
`OTEL_AWS_APPLICATION_SIGNALS_ENABLED`	Establézcalo en `true` para que su contenedor comience a enviar seguimientos de X-Ray y métricas de CloudWatch a Application Signals.
`OTEL_METRICS_EXPORTER`	Configúrelo en `none` para deshabilitar otros exportadores de métricas.
`OTEL_LOGS_EXPORTER`	Establézcalo en `none` para deshabilitar otros exportadores de registros.
`OTEL_EXPORTER_OTLP_PROTOCOL`	Establézcalo en `http/protobuf` para que envíe métricas y seguimientos a Application Signals con HTTP.
`OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT`	Configúrelo en `http://localhost:4316/v1/metrics` para enviar las métricas al sidecar de CloudWatch.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Configúrelo en `http://localhost:4316/v1/traces` para enviar seguimientos al sidecar de CloudWatch.
`OTEL_TRACES_SAMPLER`	Establézcalo en `xray` para configurar X-Ray como el muestreador de seguimientos.
`OTEL_PROPAGATORS`	Establézcalo en `xray` como uno de los propagadores.
`JAVA_TOOL_OPTIONS`	Establézcalo en `" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"` y reemplace `AWS_ADOT_JAVA_INSTRUMENTATION_PATH` con la ruta en la que se almacena el agente de autoinstrumentación de AWS Distro para OpenTelemetry para Java. Por ejemplo, `/otel-auto-instrumentation/javaagent.jar`

Monte el volumen opentelemetry-auto-instrumentation que definió en el paso 1 de este procedimiento.

Para una aplicación Java, utilice lo siguiente.


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

Antes de activar las señales de aplicación para sus aplicaciones Python, debe tener en cuenta las consideraciones siguientes.

En algunas aplicaciones en contenedores, la falta de una variable de entorno PYTHONPATH a veces puede provocar que la aplicación no se inicie. Para solucionar este problema, asegúrese de configurar la variable de entorno PYTHONPATH en la ubicación del directorio de trabajo de la aplicación. Esto se debe a un problema conocido con la instrumentación automática de OpenTelemetry. Para obtener más información sobre este problema, consulte Python autoinstrumentation setting of PYTHONPATH is not compliant.
Para las aplicaciones de Django, se requieren configuraciones adicionales, que se describen en la documentación de Python de OpenTelemetry.
- Use el indicador --noreload para evitar la recarga automática.
- Establezca la variable de entorno DJANGO_SETTINGS_MODULE en la ubicación del archivo settings.py de su aplicación Django. Esto garantiza que OpenTelemetry pueda acceder correctamente a la configuración de Django e integrarse correctamente con ella.

Instrumentación de la aplicación Python en Amazon ECS con el agente de CloudWatch

En primer lugar, especifique un montaje de enlace. El volumen se utilizará para compartir archivos entre contenedores en los siguientes pasos. Usará este montaje de enlace más tarde en este procedimiento.
```
"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"
    }
  }
}


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

Añada las siguientes variables de entorno al contenedor de aplicaciones.

Variable de entorno	Configuración para habilitar Application Signals
`OTEL_RESOURCE_ATTRIBUTES`	Especifique la siguiente información como pares clave-valor: `service.name` establece el nombre del servicio. Se mostrará como el nombre del servicio de la aplicación en los paneles de Application Signals. Si no proporciona ningún valor para esta clave, se utiliza el valor predeterminado de `UnknownService`. `deployment.environment` establece el entorno en el que se ejecuta la aplicación. Se mostrará como el entorno alojado en de la aplicación en los paneles de Application Signals. Si no lo especifica, se utiliza el valor predeterminado de `generic:default`. Esta clave de atributo solo la usa Application Signals y se convierte en anotaciones de trazas de X-Ray y dimensiones métricas de CloudWatch. (Opcional) Para habilitar la correlación de registros de seguimientos, establezca una variable de entorno adicional `aws.log.group.names` como el nombre del grupo de registro para el registro de su aplicación. De este modo, los seguimientos de su aplicación se pueden correlacionar con las entradas de registro correspondientes de este grupo de registros específico. Para esta variable, sustituya `$YOUR_APPLICATION_LOG_GROUP` por el nombre del grupo de registros de su aplicación. También tendrá que cambiar la configuración de registro de la aplicación. Para obtener más información, consulte Habilite una correlación de los registros de seguimientos.
`OTEL_AWS_APPLICATION_SIGNALS_ENABLED`	Establézcalo en `true` para que su contenedor comience a enviar seguimientos de X-Ray y métricas de CloudWatch a Application Signals.
`OTEL_METRICS_EXPORTER`	Configúrelo en `none` para deshabilitar otros exportadores de métricas.
`OTEL_EXPORTER_OTLP_PROTOCOL`	Establézcalo en `http/protobuf` para enviar métricas y seguimientos a CloudWatch mediante HTTP.
`OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT`	Configúrelo en `http://127.0.0.1:4316/v1/metrics` para enviar las métricas al sidecar de CloudWatch.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Configúrelo en `http://127.0.0.1:4316/v1/traces` para enviar seguimientos al sidecar de CloudWatch.
`OTEL_TRACES_SAMPLER`	Establézcalo en `xray` para configurar X-Ray como el muestreador de seguimientos.
`OTEL_PROPAGATORS`	Agregue `xray` como uno de los propagadores.
`OTEL_PYTHON_DISTRO`	Establézcalo en `aws_distro` para usar la instrumentación de Python de ADOT.
`OTEL_PYTHON_CONFIGURATOR`	Establézcalo en `aws_configuration` para usar la configuración de Python de ADOT.
`PYTHONPATH`	Sustituya `$APP_PATH` por la ubicación del directorio de trabajo de la aplicación dentro del contenedor. Esto es necesario para que el intérprete Python encuentre los módulos de la aplicación.
`DJANGO_SETTINGS_MODULE`	Necesario solo para las aplicaciones Django. Configúrelo en la ubicación del archivo `settings.py` de su aplicación Django. Sustituya `$PATH_TO_SETTINGS`.

Monte el volumen opentelemetry-auto-instrumentation-python que definió en el paso 1 de este procedimiento. En el siguiente ejemplo, el valor de OTEL_RESOURCE_ATTRIBUTES incluye un aws.log.group.names opcional que ayuda a habilitar la correlación del registro de seguimientos. Para más información, consulte la tabla en el paso anterior.

Para una aplicación Python, use lo siguiente.


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

Paso 5: implementar la aplicación

Cree una nueva revisión de la definición de la tarea e impleméntela en el clúster de aplicaciones. Debería ver tres contenedores en la tarea recién creada:

init
ecs-cwagent
my-app

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Habilite Application Signals en Amazon EC2, Amazon ECS o Kubernetes

Habilite Application Signals en Amazon EC2