OpenTelemetry를 사용한 사용자 지정 계측 custom-instrumentation

환경에 대해 OpenTelemetry을(를) 사용하도록 설정하면 AEM as a Cloud Service에서 모든 요청을 추적하고 JVM, HTTP 및 AEM 지표를 자동으로 내보냅니다. 그 원격 분석이 AEM을 묘사하는군. 페이지에 렌더링하는 데 900밀리초가 걸렸고 해당 페이지에서 렌더링한 구성 요소가 표시됩니다. 저장소 쿼리가 어떤 목록 항목에 사용되었는지, 어떤 항목을 발견했는지 또는 작성자가 필드를 누락하여 비싼 검색으로 대체되는 페이지와 같이 자체 코드가 무엇을 하고 있는지 표시할 수 없습니다.

OpenTelemetry API를 사용하여 해당 지식을 직접 추가할 수 있습니다. 코드에서 자동 원격 분석을 사용하여 이동하는 범위 및 특성입니다(동일한 서비스 이름, 동일한 처리, 동일한 APM 공급자). 코드에서 엔드포인트, 자격 증명 또는 익스포터를 구성하지 않습니다.

AEM as a Cloud Service에서 OpenTelemetry를 처음 사용하는 경우 자습서 OpenTelemetry를 통한 가시성으로 시작하여 작동 방법을 알아보십시오. 그런 다음 AEM 애플리케이션에 대한 통찰력을 위한 OpenTelemetry 구성을(를) 수행하여 환경에 맞게 활성화하십시오.

이 페이지의 예제에서는 WKND 참조 사이트를 계측합니다. 각 예제는 달성하고자 하는 사항, 추가할 코드 및 APM 공급자에서 기대할 수 있는 결과를 설명합니다. span에서 어설션하는 단위 테스트를 포함한 전체 계측 코드는 WKND 저장소의 tutorial/otel-custom-instrumentation 분기에 있습니다.

사용자 지정 계기 작동 방식 how-it-works

프로젝트 설정 set-up-project

1단계: OpenTelemetry API 추가 add-api

provided 범위를 사용하여 OpenTelemetry API 및 계측 주석을 프로젝트 부모 pom.xml의 dependencyManagement 섹션에 추가합니다.

<properties>
    <opentelemetry.version>1.61.0</opentelemetry.version>
    <opentelemetry-instrumentation.version>2.27.0</opentelemetry-instrumentation.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-api</artifactId>
            <version>${opentelemetry.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-instrumentation-annotations</artifactId>
            <version>${opentelemetry-instrumentation.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

그런 다음 두 종속성을 버전 없이 사용하는 각 번들의 pom.xml에 추가합니다(예: core/pom.xml).

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-instrumentation-annotations</artifactId>
</dependency>

opentelemetry-api 1.61.0 및 opentelemetry-instrumentation-annotations 2.27.0 또는 이전 버전을 사용하십시오. 이 에이전트는 AEM as a Cloud Service이 실행하는 OpenTelemetry Java 에이전트와 일치하며 이후 버전의 에이전트는 계속 지원합니다. 에이전트가 지원하는 버전 이후에 추가된 API 기능은 효과가 없습니다.

2단계: 번들에 API 포함 embed-api

AEM as a Cloud Service은 OpenTelemetry API 패키지를 내보내지 않으므로 API를 사용하는 각 번들에는 자체 복사본이 포함되어야 합니다. 번들의 경계 구성에 다음 지침을 추가합니다. AEM Project Archetype을(를) 사용하는 것은 core/pom.xml의 bnd-maven-plugin 구성입니다. Import-Package 지침에 이미 있는 모든 항목을 유지합니다.

Import-Package: !io.opentelemetry.*,javax.annotation;version=0.0.0,*
-includepackage: io.opentelemetry.*

API를 사용하는 각 번들은 자체 복사본을 임베드하고 에이전트는 각 복사본을 별도로 연결합니다.

3단계: 추적기 만들기 create-tracer

코드 기반용 Tracer을(를) 한 개 만들어 모든 곳에서 다시 사용합니다. WKND에서는 소규모 학급이 보유하고 있습니다.

package com.adobe.aem.guides.wknd.core.telemetry;

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Tracer;

public final class WkndTelemetry {

    /** Instrumentation scope: identifies telemetry produced by WKND code in your APM provider. */
    public static final String SCOPE = "com.adobe.aem.guides.wknd";

    public static final Tracer TRACER = GlobalOpenTelemetry.getTracer(SCOPE);

    private WkndTelemetry() {
    }
}

범위 이름은 이 추적기를 통해 만든 모든 범위에 계측 범위(또는 라이브러리 이름)로 표시됩니다. 프로젝트의 기본 Java 패키지와 같이 코드를 식별하는 이름을 사용합니다.

범위가 표시되는 위치 where-spans-appear

AEM as a Cloud Service에서 페이지 요청은 이미 AEM 자체에서 범위를 생성합니다. 코드에서 만드는 범위가 범위 내에 추가됩니다. 예를 들어 WKND Magazine 페이지 추적에 있는 이미지 목록 구성 요소에 대한 경로입니다.

GET /*                                                     the request (AEM)
└─ SlingMainServlet.service                                Sling request processing (AEM)
   └─ AEM component: cq:Page                               (AEM)
      └─ AEM component: wknd/components/page               the page component (AEM)
         └─ HTL: libs.core.wcm.components.page.v3.page.page__002e__html
            └─ ...                                         containers and layout grids (AEM)
               └─ AEM component: wknd/components/image-list
                  └─ HTL: apps.wknd.components.image__002d__list.image__002d__list__002e__html
                     └─ ...                                spans that the Image List's Sling Model creates

구성 요소가 렌더링되는 동안 해당 HTL 스크립트의 범위는 현재 범위입니다. 스크립트가 data-sly-use과(와) 함께 로드되는 슬링 모델이 해당 범위 내에서 실행되므로 모델이 만드는 범위가 해당 모델의 하위 모델이 됩니다.

모든 요청 범위의 이름은 GET /*(또는 POST /* 등)입니다. 특정 페이지에 대한 추적을 찾으려면 예 3과 같이 요청 범위의 url.path 특성을 검색하거나 고유한 특성을 추가하십시오.

예 examples

예제 1: 값비싼 작업 추적 trace-operation

달성하고자 하는 목표 trace-operation-goal

WKND 이미지 목록 구성 요소(wknd/components/image-list)는 각각 첫 번째 이미지가 있는 페이지 목록을 표시합니다. 해당 Sling 모델 ImageListImpl은(는) 해당 이미지를 찾기 위해 목록의 모든 항목에 대해 하나의 QueryBuilder 쿼리를 실행합니다. AEM의 자체 범위는 이미 이러한 쿼리를 보여 줍니다. 5개의 문서를 나열하는 WKND Magazine 페이지에서 추적은 이미지 목록의 HTL 범위 아래에 5개의 JCR query을(를) 포함합니다. 각 쿼리의 목록 항목, 이미지를 발견했는지 또는 결과를 처리하는 데 걸린 시간은 표시되지 않습니다. 원래 코드는 쿼리를 System.currentTimeMillis()(으)로 시간 조정하고 결과를 프로덕션에서 사용할 수 없는 DEBUG 로그 항목에 기록했습니다. 각 쿼리가 해당 컨텍스트와 함께 명명된 작업으로 추적에 나타나도록 할 수 있습니다.

코드 trace-operation-code

ImageListImpl.findPageComponentResources()에서 쿼리 범위 만들기:

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.context.Scope;

// ... build the QueryBuilder parameters, as before

final Span span = WkndTelemetry.TRACER.spanBuilder("ImageList.findPageComponentResources")
        .setAttribute("wknd.query.path", page.getContentResource().getPath())
        .setAttribute("wknd.query.resource_type", slingResourceType)
        .setAttribute("wknd.query.limit", limit)
        .startSpan();

try (Scope ignored = span.makeCurrent()) {
    // ... run the query and collect the resources, as before

    span.setAttribute("wknd.query.result_count", componentResources.size());
} catch (RuntimeException e) {
    span.recordException(e);
    span.setStatus(StatusCode.ERROR, "Image List query failed");
    throw e;
} finally {
    span.end();
}

return componentResources;

결과 trace-operation-outcome

5개의 문서를 나열하는 WKND Magazine 페이지의 추적에는 이제 이미지 목록 내에 각 목록 항목마다 하나씩 5개의 ImageList.findPageComponentResources이(가) 포함됩니다. 각 값은 AEM이 쿼리에 대해 만드는 JCR query 범위의 부모입니다.

AEM component: wknd/components/image-list
└─ HTL: apps.wknd.components.image__002d__list.image__002d__list__002e__html
   ├─ ImageList.findPageComponentResources        your span
   │  └─ JCR query                                AEM
   ├─ ImageList.findPageComponentResources
   │  └─ JCR query
   └─ ...                                         three more

각 스팬에는 계측 범위 com.adobe.aem.guides.wknd과(와) 다음 특성이 있습니다.

이제 각 목록 항목에 대해, 쿼리가 검색한 페이지, 이미지를 발견했는지(찾지 못했을 때 wknd.query.result_count이(가) 0인지), 결과 처리를 포함하여 전체 조회에 걸린 시간을 볼 수 있습니다. WKND Magazine 페이지에서 각 조회에 소요되는 시간은 약 6.5밀리초이며, 이 중 저장소 쿼리 자체가 약 3.5: 절반의 시간이 결과 처리에 소요되며, AEM 자체 범위는 표시되지 않습니다. 쿼리 카운트는 목록 길이에 따라 증가하므로 조회 시 구성 요소의 렌더링 시간 중 어느 정도를 차지하는지 확인할 수도 있습니다.

예제 2: 주석을 사용하여 메서드 추적 with-span

달성하고자 하는 목표 with-span-goal

WKND의 SocialImageImpl 모델이 모든 페이지에서 실행되어 og:image 메타 태그를 채웁니다. 작성자가 추천 이미지를 설정하지 않은 경우 모델은 페이지의 콘텐츠 트리를 이동하여 최대 500개의 리소스를 방문하여 첫 번째 이미지를 찾습니다. 당신은 방법을 재구성하지 않고 얼마나 자주 산책로를 걷고 얼마나 많은 나무를 방문하는지 알고 싶을 것이다.

코드 with-span-code

@WithSpan(으)로 메서드에 주석을 답니다.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.instrumentation.annotations.WithSpan;

@WithSpan("SocialImage.resolveFromFirstImageOnPage")
protected boolean resolveFromFirstImageOnPage() {
    Resource contentResource = currentPage.getContentResource();
    if (contentResource == null) {
        return false;
    }

    int[] visitedCount = new int[]{0};
    Resource firstImage = findFirstImage(contentResource, 0, visitedCount);

    // Span.current() is the span that @WithSpan started for this method.
    Span.current().setAttribute("wknd.social_image.nodes_visited", visitedCount[0]);
    Span.current().setAttribute("wknd.social_image.walk_truncated", visitedCount[0] > MAX_NODES_TO_VISIT);

    // ... use firstImage, as before
}

결과 with-span-outcome

SocialImage.resolveFromFirstImageOnPage 범위는 추천 이미지가 없는 페이지의 추적에만 나타납니다.

추천 이미지가 필요한 페이지를 나열하려면 이 범위 이름을 검색하십시오. wknd.social_image.walk_truncated이(가) true이면 500개의 리소스에서 작업이 중지되고 페이지에 소셜 이미지가 전혀 없을 수 있습니다.

@WithSpan이(가) 만든 범위는 사용자의 범위가 아니라 에이전트의 계측 범위(io.opentelemetry.opentelemetry-instrumentation-annotations-1.16)를 전달합니다.

예제 3: 현재 범위에 비즈니스 컨텍스트 추가 current-span

달성하고자 하는 목표 current-span-goal

다른 범위를 만들지 않고 코드에서 페이지의 소셜 이미지가 어디에서 왔는지 알고 있는 사실로 추적을 필터링하려고 합니다.

코드 current-span-code

SocialImageImpl에서 이미 활성화된 범위에 특성을 추가합니다.

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.trace.Span;

private static final AttributeKey<String> IMAGE_SOURCE = AttributeKey.stringKey("wknd.social_image.source");

@PostConstruct
protected void init() {
    if (currentPage == null) {
        return;
    }

    final String source;
    if (resolveFromFeaturedImage()) {
        source = "featured_image";
    } else if (resolveFromFirstImageOnPage()) {
        source = "first_image_on_page";
    } else {
        source = "none";
    }

    Span.current().setAttribute(IMAGE_SOURCE, source);
}

결과 current-span-outcome

WKND가 이 모델을 로드하는 페이지의 customheaderlibs.html 스크립트 범위는 featured_image, first_image_on_page 또는 none 값으로 wknd.social_image.source을(를) 전달합니다. wknd.social_image.source이(가) none인 추적을 검색하여 소셜 이미지 없이 게시된 페이지를 찾으십시오.

WKND 사이트에서 모든 페이지는 first_image_on_page 또는 none을(를) 보고합니다. 페이지가 추천 이미지를 설정하지 않으므로 모든 페이지는 예 2에서 콘텐츠 트리 워크에 대한 비용을 지불합니다. 가장 많이 방문한 페이지에서 추천 이미지를 설정하면 해당 작업이 제거됩니다.

예제 4: 오류 기록 record-errors

달성하고자 하는 목표 record-errors-goal

WKND의 ContentAIAvailabilityImpl 모델이 OSGi 구성을 읽어서 콘텐츠 AI 검색이 구성되어 있는지 확인합니다. 조회가 실패하면 모델은 콘텐츠 AI를 구성되지 않은 것으로 취급하고 경고를 기록합니다. 페이지가 계속 렌더링되고 요청이 성공하므로 실패가 발생하기 쉽습니다. 실패가 실패한 작업에 첨부된 APM 공급자의 오류 보기에 나타나도록 합니다.

코드 record-errors-code

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.context.Scope;

private boolean resolveConfigured() {
    if (configurationAdmin == null) {
        return false;
    }
    final Span span = WkndTelemetry.TRACER.spanBuilder("ContentAIAvailability.resolveConfigured").startSpan();
    // Close the scope in finally, not with try-with-resources: try-with-resources closes it before
    // the catch block runs, and the warning logged there must carry this span's trace and span IDs.
    final Scope scope = span.makeCurrent();
    try {
        Configuration configuration = lookupConfiguration();
        // ... read the API key, as before
        span.setAttribute("wknd.content_ai.configured", isConfigured);
        return isConfigured;
    } catch (IOException e) {
        span.recordException(e);
        span.setStatus(StatusCode.ERROR, "Content AI configuration lookup failed");
        LOGGER.warn("Unable to determine whether Content AI is configured (PID {})", CONTENT_AI_CLIENT_PID, e);
        return false;
    } finally {
        scope.close();
        span.end();
    }
}

결과 record-errors-outcome

추적에 ContentAIAvailability.resolveConfigured 범위가 포함되어 있으며 상태는 오류​이고 설명은 Content AI configuration lookup failed입니다. 범위에 exception 이벤트가 있습니다.

이 범위는 APM 공급자에서 오류로 계산되므로 공급자가 실패한 작업을 표시할 때마다 표시됩니다. 요청이 HTTP 200을 반환했으므로 요청 범위가 해당 상태를 유지합니다.

예제 5: 로그를 추적과 상호 연결 correlate-logs

달성하고자 하는 목표 correlate-logs-goal

예 4의 콘텐츠 AI 조회가 실패하면 로그의 경고에서 이를 생성한 요청의 추적으로 이동한 다음 되돌아가려고 합니다.

코드 correlate-logs-code

OpenTelemetry 코드가 필요하지 않습니다. 평소대로 SLF4J를 사용하여 로그인하고 OpenTelemetry 구성에서 로그(logs: true)를 사용하도록 설정합니다.

LOGGER.warn("Unable to determine whether Content AI is configured (PID {})", CONTENT_AI_CLIENT_PID, e);

에이전트는 모든 로그 항목에 현재 범위의 추적 및 범위 ID를 추가합니다. 예 4의 범위가 최신인 동안 ContentAIAvailabilityImpl개의 로그가 기록되므로 경고가 해당 범위에 연결됩니다.

결과 correlate-logs-outcome

APM 공급자는 다음과 같은 로그 항목을 수신하고 해당 추적과 함께 표시할 수 있습니다.

모범 사례 best-practices

계측 테스트 test

문제 해결 troubleshooting

관련 문서 related-articles