1단계: 계정에서 Application Signals 활성화 2단계 - IAM 역할 생성 3단계: CloudWatch 에이전트 구성 준비 4단계: CloudWatch 에이전트를 사용하여 애플리케이션 계측 5단계: 애플리케이션 배포

사용자 지정 설정을 사용하여 Amazon ECS에서 Application Signals를 활성화합니다.

이 사용자 지정 설정 지침을 사용하여 Amazon ECS의 애플리케이션을 CloudWatch Application Signals에 온보딩합니다. CloudWatch 에이전트와 AWS 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 Parameter Store에 업로드합니다. 이를 위해 다음 명령을 입력합니다. 파일에서 $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 에이전트 사이드카 정의를 추가합니다. 이렇게 하려면 애플리케이션의 작업 정의에 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를 AWS 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용 AWS 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`	컨테이너가 X-Ray 트레이스와 CloudWatch 지표를 Application Signals로 전송하기 시작하게 하려면 `true`로 설정합니다.
`OTEL_METRICS_EXPORTER`	다른 지표 내보내기를 비활성화하려면 `none`으로 설정합니다.
`OTEL_LOGS_EXPORTER`	다른 로그 내보내기를 비활성화하려면 `none`으로 설정합니다.
`OTEL_EXPORTER_OTLP_PROTOCOL`	HTTP를 사용하여 지표와 트레이스를 Application Signals로 전송하려면 `http/protobuf`로 설정합니다.
`OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT`	CloudWatch 사이드카로 지표를 전송하려면 `http://localhost:4316/v1/metrics`로 설정합니다.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	CloudWatch 사이드카로 트레이스를 전송하려면 `http://localhost:4316/v1/traces`로 설정합니다.
`OTEL_TRACES_SAMPLER`	X-Ray를 트레이스 샘플러로 설정하려면 이를 `xray`로 설정합니다.
`OTEL_PROPAGATORS`	전파자 중 하나로 `xray`를 설정합니다.
`JAVA_TOOL_OPTIONS`	`" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"`로 설정합니다. `AWS_ADOT_JAVA_INSTRUMENTATION_PATH`를 AWS 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를 참조하세요.
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를 AWS 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`	컨테이너가 X-Ray 트레이스와 CloudWatch 지표를 Application Signals로 전송하기 시작하게 하려면 `true`로 설정합니다.
`OTEL_METRICS_EXPORTER`	다른 지표 내보내기를 비활성화하려면 `none`으로 설정합니다.
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`로 설정하여 HTTP를 사용하여 지표 및 추적을 CloudWatch에 전송합니다.
`OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT`	CloudWatch 사이드카로 지표를 전송하려면 `http://127.0.0.1:4316/v1/metrics`로 설정합니다.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	CloudWatch 사이드카로 트레이스를 전송하려면 `http://127.0.0.1:4316/v1/traces`로 설정합니다.
`OTEL_TRACES_SAMPLER`	X-Ray를 트레이스 샘플러로 설정하려면 이를 `xray`로 설정합니다.
`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가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

Amazon EC2, Amazon ECS 또는 Kubernetes에서 Application Signals 활성화

Amazon EC2에서 Application Signals 활성화