使用OpenTelemetry的自訂檢測 custom-instrumentation

為您的環境啟用OpenTelemetry時，AEM as a Cloud Service會追蹤每個要求並自動匯出JVM、HTTP和AEM量度。 該遙測描述了AEM。 它會顯示頁面花費900毫秒來呈現，以及呈現的元件。 它無法顯示您自己的程式碼正在做什麼，例如存放庫查詢是用於哪個清單專案，以及它是否找到任何內容，或是哪些頁面會因作者遺漏欄位而回覆為昂貴的搜尋。

您可以使用OpenTelemetry API自行新增該知識。 程式碼建立的範圍和屬性會透過自動遙測傳輸：相同的服務名稱、相同的處理、相同的APM提供者。 您不需要在程式碼中設定端點、認證或匯出工具。

如果您剛開始使用AEM as a Cloud Service上的OpenTelemetry，請從教學課程透過OpenTelemetry的可觀察性開始，瞭解其運作方式。 然後依照設定OpenTelemetry以深入分析AEM應用程式為您的環境啟用它。

此頁面上的範例檢測WKND參考網站。 每個範例都說明您想要達成的目的、要新增的程式碼，以及您可以在APM提供者中預期的結果。 完整的檢測程式碼（包括宣告於跨區上的單元測試）位於WKND存放庫的tutorial/otel-custom-instrumentation分支上。

自訂檢測如何運作 how-it-works

設定您的專案 set-up-project

步驟1：新增OpenTelemetry API add-api

將OpenTelemetry API和檢測註解新增至專案上層pom.xml的dependencyManagement區段（範圍為provided）：

<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的每個套件組合都必須包含自己的復本。 將下列指示新增至套件組合的bnd設定。 使用AEM專案原型，這就是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的Sling模型在該範圍內執行，因此跨度以致模型建立的範圍會成為其子系。

每個要求範圍都命名為GET /* （或POST /*，以此類推）。 若要尋找特定頁面的追蹤，請搜尋請求範圍的url.path屬性，或新增您自己的屬性，如範例3所示。

範例 examples

範例1：追蹤昂貴的作業 trace-operation

您想要達成的目標 trace-operation-goal

WKND影像清單元件(wknd/components/image-list)會顯示頁面清單，每個頁面都有其第一個影像。 若要尋找該影像，其Sling模型ImageListImpl會針對清單中的每個專案執行一個QueryBuilder查詢。 AEM自己的範圍已顯示這些查詢：在列出五篇文章的WKND Magazine頁面上，追蹤在影像清單的HTL範圍下包含五個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

在列出五篇文章的WKND Magazine頁面上，追蹤現在在影像清單中包含五個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

頁面的customheaderlibs.html指令碼範圍（WKND在此指令碼中載入此模型）攜帶wknd.social_image.source，其值為featured_image、first_image_on_page或none。 搜尋wknd.social_image.source為none的追蹤以尋找沒有社交影像的已發佈頁面。

在WKND網站上，每個頁面都會報告first_image_on_page或none：沒有任何頁面會設定精選影像，因此每個頁面都會支付從範例2開始的內容樹狀結構瀏覽的費用。 在造訪次數最多的頁面上設定精選影像，會移除正常運作的專案。

範例4：記錄錯誤 record-errors

您想要達成的目標 record-errors-goal

WKND的ContentAIAvailabilityImpl模型會透過讀取OSGi設定來檢查內容AI 搜尋是否已設定。 如果查詢失敗，模型會將Content 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

追蹤包含狀態為​ 錯誤 ​且描述為Content AI configuration lookup failed的ContentAIAvailability.resolveConfigured範圍。 範圍有exception個事件：

範圍在您的APM提供者中計為錯誤，因此無論您的提供者顯示失敗作業，它都會顯示。 請求範圍會保持其狀態，因為請求傳回HTTP 200。

範例5：將記錄檔與追蹤建立關聯 correlate-logs

您想要達成的目標 correlate-logs-goal

當範例4中的Content 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新增至每個記錄專案。 因為ContentAIAvailabilityImpl會記錄其從範例4跨越的時程，而且是最新的，所以警告會連結到該範圍。

結果 correlate-logs-outcome

您的APM提供者會收到如以下的記錄專案，並可顯示其追蹤：

最佳實務 best-practices

測試您的檢測工具 test

疑難排解 troubleshooting

相關的文章 related-articles