AEM 애플리케이션에 대한 통찰력을 위한 OpenTelemetry 구성

마지막 업데이트: 2026년 10월 24일

적용 대상:
Experience Manager as a Cloud Service

작성 대상:

Intermediate
Admin
Developer

선택한 OpenTelemetry 호환 가시성 플랫폼에 AEM as a Cloud Service 환경을 연결하는 방법을 알아봅니다.

이전 문서에서는 AEM as a Cloud Service에서 OpenTelemetry를 사용할 때의 개념과 이점에 대해 알아보았습니다. 이 자습서에서는 AEM WKND 샘플 프로젝트를 예제 응용 프로그램으로 사용하고 Cloud Manager 구성 파이프라인을 사용하여 config/otel.yaml을(를) 배포하여 원격 분석을 내보내는 방법을 보여줍니다.

높은 수준의 단계는 다음과 같습니다.

관찰 가능성 플랫폼에 대한 OTLP/HTTPS 끝점 및 수집 자격 증명을 가져옵니다.
Cloud Manager에 자격 증명을 안전하게 저장하십시오.
config/otel.yaml 파일을 AEM 프로젝트 저장소에 추가합니다.
Cloud Manager 구성 파이프라인을 실행합니다.
AEM 애플리케이션에 대한 트래픽을 생성합니다.
가시성 플랫폼에서 원격 분석을 확인합니다.

AVAILABILITY

이 기능은 제한된 가용성에 있습니다. 사용하려면 aemcs-apm-beta@adobe.com(으)로 전자 메일을 보내 액세스를 요청하세요. Adobe은 요청에 응답한 직후 환경에 대한 OpenTelemetry를 사용하도록 설정합니다. 현재 환경에서 Adobe의 기본 제공 APM 통합을 사용하는 경우 OpenTelemetry가 활성화되면 두 통합이 동시에 실행될 수 없으므로 해당 통합은 데이터 전송을 중지합니다.

HIPAA 범위 환경, RDE(빠른 개발 환경) 및 샌드박스에서 사용할 수 없음입니다.

사전 요구 사항

시작하기 전에 다음을 확인하십시오.

WKND 사이트 또는 자체 애플리케이션이 배포된 AEM as a Cloud Service 개발, 단계 또는 프로덕션 환경입니다. OpenTelemetry는 HIPAA 범위 환경, 샌드박스 프로그램 및 RDE(신속한 개발 환경)에서 지원되지 않습니다.
환경 변수를 관리하고 구성 파이프라인을 만들고 실행할 수 있는 권한이 있는 Cloud Manager에 액세스하십시오.
끝점 및 수집 자격 증명이 있는 OTLP over HTTPS을(를) 허용하는 가시성 플랫폼입니다.
가시성 플랫폼에 액세스하여 들어오는 AEM 원격 분석을 확인하고 시각화할 수 있습니다.

1단계: 가시성 끝점 및 자격 증명 가져오기

관찰 가능성 플랫폼에서 해당 OTLP/HTTPS 수집 끝점을(를) 찾아 적절한 수집 자격 증명을 만들거나 검색합니다. 지침이 필요하면 플랫폼의 설명서를 참조하십시오.

어떤 플랫폼을 사용해야 할지 모르십니까? 관찰 가능한 플랫폼 선택을 참조하세요.

이 자습서에서는 HTTPS에서 OTLP를 지원하고 기본 인증 토큰이 필요한 자체 호스팅 가시성 플랫폼을 사용합니다.

2단계: Cloud Manager에 가시성 자격 증명 저장

수집 자격 증명을 Cloud Manager 암호 환경 변수(으)로 저장합니다.

Adobe Cloud Manager에서 AEM 프로그램을 선택합니다.
대상 환경을 선택하고 세부 정보 보기를 클릭합니다.

구성 탭에서 추가/업데이트를 클릭하고 다음 값으로 환경 변수를 추가합니다.
환경 변수 추가

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
설정	값
이름	`OTEL_CUSTOMER_AUTH`
값	공급자의 수집 자격 증명입니다. 형식은 플랫폼마다 다릅니다. 예제는 공급자별 설정을 참조하세요.
서비스 적용됨	모두
유형	암호

이 예제에서 자체 호스팅 플랫폼은 Basic <base64(user:password)> 형식의 기본 인증 토큰을 사용합니다.

추가를 클릭한 다음 저장을 클릭하여 환경 변수를 저장합니다.

config/otel.yaml 파일이 이 암호를 ${{secrets.OTEL_CUSTOMER_AUTH}}(으)로 참조합니다. 자격 증명은 AEM 저장소 또는 파이프라인 로그에 표시되지 않아야 합니다.

3단계: OpenTelemetry 구성 추가

AEM 프로젝트 리포지토리에서 config/otel.yaml 파일을 만듭니다. 이 자습서의 자체 호스팅 플랫폼은 다음 구성을 사용합니다.

kind: "Otel"
version: "v1"
metadata:
  envTypes:
    - "dev"
    - "stage"
    - "prod"
data:
  enabled: true
  type: "generic"
  endpoint: "https://my-self-hosted-observability.adobe.net"
  authHeaderName: "Authorization"
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"
  metrics: true
  logs: true

주요 설정은 다음과 같습니다.

설정

목적

metadata.envTypes

구성이 적용되는 환경 유형입니다. 대상 환경 유형을 포함합니다.

enabled

true(으)로 설정된 경우 고객 원격 분석 내보내기를 사용하도록 설정합니다.

type

대상 구성(예: 자체 호스팅 플랫폼의 경우 generic)을 선택합니다.

endpoint

대상의 기본 OTLP/HTTPS URL입니다.

authHeaderName

자격 증명을 전달하는 HTTP 헤더입니다(예: Authorization).

authHeaderValue

자격 증명 자체가 아니라 Cloud Manager 암호에 대한 참조.

metrics

true일 때 지표 내보내기를 활성화합니다.

logs

true일 때 응용 프로그램 로그 내보내기를 사용하도록 설정합니다.

통합이 활성화될 때마다 내보내기를 추적합니다. 지표 및 로그는 선택 사항입니다. true(으)로 설정된 경우에만 내보냅니다.

예를 들어 다음 WKND 샘플 구성을 참조하십시오.

WKND 샘플 구성

4단계: OpenTelemetry 구성 배포

config/otel.yaml 파일을 커밋하고 구성 파이프라인이 소스로 사용하는 저장소 및 분기에 푸시합니다.
Cloud Manager에서 환경에 대한 구성 파이프라인을 만들거나 편집하고 세부 정보를 확인합니다.
파이프라인 이름을 선택하고 실행을 클릭합니다.
파이프라인 실행이 성공적으로 완료될 때까지 모니터링합니다.

파이프라인이 대상 설정을 적용하기 전에 구성을 확인합니다.

5단계: AEM 트래픽 생성

파이프라인이 완료된 후 일부 애플리케이션 활동을 생성합니다.

AEM Publish 서비스에서 WKND 사이트 또는 애플리케이션을 열고 몇 페이지 사이를 이동합니다.
필요한 경우 작성자 원격 분석을 생성하려면 작성자 서비스에서 WKND 사이트를 엽니다.

원격 분석이 관찰 가능한 플랫폼에 도달할 때까지 잠시 기다립니다.

6단계: 관찰 가능성 플랫폼에서 원격 분석 확인

가시성 플랫폼을 열고 원격 분석을 찾습니다. 추적, 지표 및 로그를 찾는 단계는 플랫폼마다 다릅니다. 다음 스크린샷은 Grafana 기반 가시성 플랫폼 대시보드에서 찍은 것입니다.

AEM 서비스 찾기

다음과 유사한 AEM 서비스 이름을 검색합니다.

cm-p<program>-e<environment>-aem-publish-<environment-type>

이 자습서에 사용된 자체 호스팅 플랫폼에서 게시 서비스 원격 측정이 다음과 같이 표시됩니다.

관찰 가능성 플랫폼에서 WKND 게시 서비스 원격 분석

추적 검사

WKND 페이지 요청과 일치하는 인바운드 HTTP 요청 범위를 찾습니다. 추적을 열고 요청 이름, 기간 및 관련 범위를 검토합니다.

Observability Platform의 WKND 요청 추적

지표 검사

구성이 metrics: true을(를) 설정하므로 메모리 사용량, 가비지 수집 기간, 스레드 수 및 HTTP 요청 기간과 같은 JVM 및 HTTP 지표를 찾습니다.

Observability 플랫폼의 WKND 서비스 지표

로그 검사

구성이 logs: true을(를) 설정하므로 AEM 응용 프로그램 로그의 대상을 확인하십시오. 통합은 지원되는 심각도(WARN 이상) 임계값에서 로그를 내보내므로 일반 페이지 방문이 해당 수준에서 로그 항목을 생성하지 않을 수 있습니다.

가시성 플랫폼의 WKND 서비스 로그

문제 해결

구성 파이프라인 이 실패하거나 원격 분석이 관찰 가능성 플랫폼에 표시되지 않는 경우 파이프라인 로그를 검토하고 다음을 확인하십시오.

증상

확인할 사항

OpenTelemetry가 환경에 대해 활성화되지 않았습니다.

AEM 프로그램이 OpenTelemetry에 적합하고 이 기능이 대상 환경에 대해 활성화되어 있는지 확인합니다. 액세스 또는 플랫폼 활성화가 필요한 경우 Adobe 지원 센터에 문의하십시오.

구성이 무시된 것 같습니다.

metadata.envTypes에 대상 환경 유형(dev, stage 또는 prod)이 포함되어 있는지 확인하십시오. 불일치로 인해 오류 없이 구성을 건너뜁니다.

암호 참조 오류

OTEL_CUSTOMER_AUTH이(가) Cloud Manager 비밀 환경 변수(으)로 있는지 확인합니다. 적용된 서비스는 모두(으)로 설정됩니다. 파이프라인 변수가 아니어야 합니다.

인증 실패(401 또는 403)

공급자에 필요한 자격 증명 및 인증 헤더를 확인합니다. 예를 들어 New Relic에는 사용자 API 키가 아닌 수집 라이선스 키가 필요합니다.

끝점에 연결할 수 없거나 자격 증명 유효성 검사가 실패했습니다.

끝점 URL, 지역 및 HTTPS 연결을 확인합니다. 안정적인 아웃바운드 IP 주소가 필요한 개인 엔드포인트 또는 대상에 고급 네트워킹을 프로비저닝하고 활성화해야 할 수 있습니다.

Dynatrace Onagent 충돌

Dynatrace OneAgent가 환경에서 활성 상태인 동안에는 OpenTelemetry를 활성화할 수 없습니다. OpenTelemetry를 구성하기 전에 기존 통합을 제거해야 합니다.

파이프라인이 완료되지만 원격 분석이 표시되지 않음

몇 분 동안 데이터가 도착할 수 있도록 허용하고, WKND 또는 기타 관련 트래픽을 생성하고, 공급자의 수집 상태 및 service.name 필터를 확인합니다.

로그가 표시되지 않음

logs: true이(가) 구성되어 있고 AEM 응용 프로그램에서 WARN 수준 이상의 로그 항목을 생성했는지 확인하십시오.

중복 로그 항목

OpenTelemetry 로그 내보내기 및 AEM 로그 전달이 동일한 대상으로 로그를 전송하는지 확인합니다.

내부 시스템 오류

구성 파이프라인을 다시 시도하십시오. 오류가 지속되면 Adobe 지원 센터에 파이프라인 실행에 대한 세부 정보를 문의하십시오.

문제가 지속되면 Adobe 지원 센터에 문의하여 AEM 프로그램 ID, 환경 ID, 구성 파이프라인 실행 ID, 정확한 오류 메시지 및 관찰 가능한 공급자 세부 정보를 제공하십시오. 인증 자격 증명 또는 암호 값을 포함하지 마십시오.

추가 구성 예 및 문제 해결 정보는 OpenTelemetry 제품 설명서를 참조하십시오.

다음 단계

AEM as a Cloud Service용 OpenTelemetry를 구성하고 WKND 샘플 응용 프로그램의 원격 분석을 관찰 가능성 플랫폼에서 사용할 수 있는지 확인했습니다.

이제 이 원격 분석을 사용하여 느리거나 실패한 요청을 조사하고, JVM 및 HTTP 성능을 모니터링하고, 애플리케이션 로그를 추적과 상호 연관시켜 AEM 애플리케이션 동작을 더 잘 이해할 수 있습니다.

응용 프로그램별 논리에 대한 원격 분석을 확장하려면 OpenTelemetry를 사용한 사용자 지정 계측을 참조하십시오.

추가 구성 옵션, 지원되는 관찰 가능성 공급자 및 네트워킹 요구 사항을 살펴보려면 OpenTelemetry 제품 설명서를 참조하세요.

추가 리소스

recommendation-more-help

experience-manager-learn-help-cloud-service