在 AEM 中使用 New Relic RUM 的第一方代理

style

border-bottom-glow

有些問題會以非常明顯的方式顯現出來。還有一些人則隱藏在「在我的機器上運作正常」和「對每個人都正常」之間的空白地帶。它牢牢地棲身於那個空隙之中。

症狀似乎很簡單：有些用戶無法載入我們基於 HubSpot 的表單。原因也合情合理：瀏覽器隱私設定和追蹤攔截器介入，拒絕讓任何類似追蹤器的東西通過。但當我們試圖衡量這個問題時，卻遇到了難題，原本看似可以快速解決的問題變得有趣得多。

我們通常會用來發現這些故障的工具——真實使用者監控——卻被破壞表單的相同保護措施所阻止。我們的 New Relic RUM 看起來像一個追蹤器，因為，嗯，它 本來就是 一個追蹤器。我們當時實際上是想在一個房間裡安裝煙霧偵測器，但房間裡的煙霧觸發了一個會使煙霧偵測器失效的裝置。

本文詳細介紹了我們如何解決這個悖論：透過我們自己的第一方域名代理 New Relic，使其不再看起來像第三方跟踪，處理子域名帶來的複雜情況，保持遙測數據的清潔，並最終構建可靠的 HubSpot 故障檢測機制；即使是完全無法加載的靜默故障也能檢測到。在此過程中，我們將介紹 CDN 和調度程序的配置、在快速開發環境中進行測試、透過 Cloud Manager 進行部署，以及將巧妙的變通方法轉換為可靠指標的磨合期。

New Relic 提供的重要提示：

當您使用代理方法時，請務必確保您有權根據您對最終使用者和/或網站訪客可能承擔的任何合約、監管或其他法律義務這樣做。

讓 New Relic 成為第一方

解決方案不是直接從 New Relic 的標準端點載入所有內容，而是透過我們自己的網域代理所有內容。這會將請求從第三方轉移到第一方，從而繞過大多數追蹤保護措施。

引入了兩個終點：

/nr/agent/ → 為 New Relic 瀏覽器代理提供服務
/nr/data/ → 接收信標（遙測）請求

硬編碼代理值

在 New Relic 中配置第一方代理程式最簡單的方法是將代理路徑直接在NREUM.init中設定為靜態字串。您將assets指向提供 New Relic 代理程式腳本區塊的 URL，並將beacon指向接收遙測資料的 URL；兩者都透過您自己的網域而不是 New Relic 的 CDN 進行路由。

proxy: {
  assets: 'www.arborydigital.com/nr/agent',
  beacon: 'www.arborydigital.com/nr/data'
}

這很容易理解。路徑一目了然，無需運行時邏輯，並且在代理初始化之前就已設定；因此無需擔心配置是否能及時生效。只要你的伺服器配置了這兩個路由，並且正確地轉送到 New Relic，它就能正常運作。對於僅使用單一網域名稱且沒有子網域流量的網站來說，這通常就足夠了。

跨子域代理

當您的網站使用子網域（例如blog.arborydigital.com時，單一硬編碼的代理路徑是不夠的。每個子網域都從自己的來源運行，瀏覽器安全性規則意味著從blog.arborydigital.com到託管在www.arborydigital.com上的代理程式路徑的請求在技術上是跨網域請求。雖然這可能有效，但這違背了第一方代理的部分意義，即透過瀏覽器已經信任的相同來源發送遙測資料。

為了解決這個問題，可以在運行時動態設定代理配置。該腳本不會指向固定的域名，而是檢查window.location.hostname來確定頁面目前運行的來源。如果該主機名稱與您的根域或其任何子域匹配，則代理端點將使用window.location.origin建構－這表示blog.arborydigital.com將透過blog.arborydigital.com/nr-assets/和blog.arborydigital.com/nr-beacon路由其 New Relic 流量，而www.arborydigital.com使用其自己的等效路徑。

這種方法要求每個子網域都在伺服器或 CDN 層級配置相應的代理路由。New Relic 代理程式配置（包括NREUM.info中的beacon和errorBeacon欄位）也需要更新，以反映目前的主機名，以便代理程式知道在哪裡報告資料。

ajax.deny_list

New Relic 瀏覽器代理程式配置為將所有遙測資料透過第一方代理程式blog.arborydigital.com/nr/data而非 New Relic 自己的伺服器bam.nr-data.net進行路由。這樣可以避免針對已知 NR 結構域的阻斷劑。

這樣做的一個副作用是：NR 代理程式會監視頁面上所有傳出的 XHR/fetch 請求，並將它們捕獲為 AJAX 事件；包括它自己發送到blog.arborydigital.com/nr/data信標呼叫。如果沒有拒絕列表，NR 會將自己的遙測 POST 請求記錄為 AJAX 事件，然後這些事件又會作為更多的遙測數據發送出去，從而用 NR 內部流量污染 AJAX 數據。

為了解決這個問題，避免你的數據速率像電影《阿基拉》裡那樣高得離譜，我們可以使用內建通配符來阻止這些信標呼叫。最終結果會是blog.arborydigital.com/nr/data/* 。實現此功能後，它會告訴 New Relic 在成功捕獲瀏覽器資料時不要建立ajax條目。POST內的所有資訊都將被保留，並且不再有冗餘的 ajax 條目。

使用查詢參數作為功能標誌

將代理伺服器置於?proxy=yes之後，可以在生產環境中測試行為，而不會影響其他訪客。URL 中缺少該參數的使用者將完全繞過此限制，在這種情況下，New Relic 將不會觸發。開啟一個帶有附加參數的標籤頁，在 DevTools 中確認請求正在透過您自己的網域進行路由，一切檢查完畢後，從腳本中刪除該條件。之後，主機名稱檢查將接管，代理將自動啟動以處理所有流量。

實作 New Relic Agent

您可以透過以下方式找到 JavaScript 程式碼片段：

登入 New Relic One (one.newrelic.com)
導覽至瀏覽器→新增資料→瀏覽器監控
選擇應用程式（應用程式 ID）或建立一個新應用
選擇使用 SPA 載入器的 複製/貼上 部署方法。
複製產生的完整<script>程式碼片段

當您將 RUM 腳本新增至儲存庫時，請確保它位於其自身的newrelic.js檔案中，以便我們可以在內部呼叫它。 head.html

注意： <script src="/scripts/newrelic.js"></script>必須是您初始化的第一個腳本，緊跟在任何meta標籤之後。

完成此操作後，您需要將特定的代理設定新增至此字串。在產生的程式碼片段的NREUM.init區塊中，新增代理配置：

proxy: {
  assets: 'www.arborydigital.com/nr/agent',
  beacon: 'www.arborydigital.com/nr/data'
}

代理伺服器佈線（EDS/CDN 層）

代理本身位於 CDN 層。目標很簡單：將傳入的/nr/*請求轉送到真正的 New Relic 端點。

來源選擇器必須排除/nr/agent/*和/nr/data/* ，這樣這些請求就不會被路由到邊緣交付服務來源。相反，它們會流向預設的 AEM 發布來源，Apache ProxyPass 規則會在那裡執行。在你的cdn.yaml中，它看起來會像這樣：

originSelectors:
  rules:
    - name: arbory-da
      when:
        allOf:
          - reqProperty: path
            like: /*
          # ...existing exclusions...
          - reqProperty: path
            doesNotMatch: /nr/agent/*
          - reqProperty: path
            doesNotMatch: /nr/data/*
      action:
        type: selectOrigin
        originName: arbory-da

您還需要編輯 VirtualHost ( .vhost ) 檔案：

# New Relic Browser Agent Proxy
SSLProxyEngine on

# Proxy New Relic agent JS chunks (lazy-loaded scripts)
<Location "/nr/agent/">
    ProxyPass "https://js-agent.newrelic.com/"
    ProxyPassReverse "https://js-agent.newrelic.com/"
    RewriteEngine Off
</Location>

# Proxy New Relic beacon/telemetry data
<Location "/nr/data/">
    ProxyPass "https://bam.nr-data.net/"
    ProxyPassReverse "https://bam.nr-data.net/"
    RewriteEngine Off
</Location>

關鍵細節：

SSLProxyEngine on 由於上游目標是 HTTPS，因此需要這樣做。
RewriteEngine Off 防止 AEM 的預設重寫規則幹擾代理路徑

偵測 HubSpot 故障（即使頁面完全載入不出來）

一旦 New Relic 被解除阻塞，下一個問題是 HubSpot 故障並不總是會拋出明顯的錯誤；尤其是在腳本從未加載的情況下。

為了解決這個問題，增加了兩條偵測路徑：

1. 腳本載入失敗

偵測 HubSpot 腳本何時完全無法載入：

script.onerror = () => {
  reportError('HubSpot script failed to load');
};

2. 運轉時故障

捕獲腳本載入後的錯誤：

window.addEventListener('error', (e) => {
  if (e.filename && e.filename.includes('hsforms')) {
    reportError('HubSpot runtime error');
  }
});

兩者都會匯總到同一個報表功能：

function reportError(errorMsg) {
  console.error(errorMsg);
  if (window.newrelic) {
    window.newrelic.noticeError(new Error(errorMsg));
  }
}

驗證是否真的有效

所有線路連接完畢後，驗證過程非常簡單，但仍然很重要。測試應重點關注啟用了嚴格追蹤保護/擴充功能的瀏覽器，在這些瀏覽器中，您應該會看到 HubSpot 表單無法加載，控制台中出現錯誤，並且這些相同的錯誤也會出現在 New Relic 中。在 DevTools 中，確認代理從/nr/agent/加載，並且信標發送到/nr/data/ ，沒有向bam.nr-data.net等第三方網域發送請求。在 New Relic 中，請驗證儀表板中是否顯示錯誤，事件是否與觸發的故障匹配，以及會話是否正在記錄。如果仍然缺少會話，則代理可能配置不正確。

使用快速開發環境 (RDE) 進行測試

如果您是我們的老讀者，您可能還記得我寫過一篇關於使用快速開發環境 (RDE) 測試 CDN 配置變更的文章。測試這款新朗姆酒時，我就是這麼做的！

遵循最佳實務時，開發工作將在分支上進行。為了確保您的變更套用至分支而不是主分支，您需要對cdn.yaml進行額外的變更：

    origins:
     # ...existing code...
      - name: arbory-da
        domain: (BRANCH_NAME)--(rest of domain).aem.live
        forwardHost: false

準備推送變更時，您需要使用兩個主要命令：

aio aem:rde:install -t env-config ./config 這將推送您的/config的內容以及我們之前所做的排除項。

aio aem:rde:install -t dispatcher-config ./dispatcher/src 這將推送您的/src的內容——即調度程序配置.vhost中的更改。

由於 RDE 運行在與其他環境不同的網域上，因此您需要指定一個新的 URL 來進行代理。否則將視為第三方域名：

proxy: { 
   assets: 'your-rde-domain.aem.live/nr/agent', 
   beacon: 'your-rde-domain.aem.live/nr/data' 
}

雲端管理器管道部署（開發+生產）

透過 Adobe Cloud Manager 部署此功能需要比一般程式碼變更更多的協調工作。代理行為取決於多個層（CDN、調度器和瀏覽器），所有這些層都需要在同一部署中保持一致。

部署流程

流水線執行將：

建置並驗證應用程式
部署調度程序配置（包括.vhost 、過濾器和代理規則）
部署CDN 配置（ cdn.yaml ，包括來源選擇器）
使快取失效並將變更推廣到整個環境

在此實作中，調度程序和 CDN 的變更緊密耦合。如果兩者都不存在且一致，代理將無法正常運作。

所需更改（必須同時部署）

以下更新需要包含在同一次管線運行中：

CDN（ cdn.yaml ）
- 從邊緣交付路由排除/nr/agent/*和/nr/data/*
調度器（ .vhost ）
- ProxyPass / ProxyPassReverse規則，適用於 New Relic 端點
- SSLProxyEngine on
- 禁用代理路徑的重寫
調度員過濾器
- 明確允許規則 /nr/*

如果其中任何一個缺失或不同步，請求要麼會被錯誤路由，要麼會被阻止，要麼會回退到第三方端點。

燒傷期

現在代理程式已經配置和部署完畢，需要進行一段時間的測試，以確保一切運作正常。由於故障取決於使用者的實際情況，例如隱私設定、擴充功能和網路行為，因此需要一些時間才能全面了解情況。

經過一段時間的驗證，確認資料已正確攝取後，下一步是審查這些資料；驗證錯誤率是否符合預期流量，確保覆蓋所有環境，並改善任何差距（遺漏的事件、不一致的領域或邊緣情況阻塞）。由此，你可以開始將其視為可靠的指標，觀察其隨時間變化的趨勢，並用它來量化真正的用戶影響，而不是軼事報導。

最後想說的話

最初只是想“添加一些監控”，結果卻變成了一次關於瀏覽器隱私模型、第一方代理、CDN 路由以及如何衡量那些天生就難以衡量的事物的微妙藝術的探索之旅。

核心見解值得牢記：當你試圖觀察的物件和你用來觀察它的物件都被瀏覽器視為不受歡迎的物件時，你無法透過現成的工具來監控它。您需要更改瀏覽器對遙測資料的感知方式。透過我們的第一方域代理 New Relic 正是如此——將請求從第三方轉移到第一方，繞過了障礙物，讓我們真正看到了以前看不到的故障。

但代理人只是成功的一半。偵測 HubSpot 故障，尤其是腳本從未載入的靜默故障，需要仔細處理載入錯誤和執行階段錯誤，並將所有錯誤集中到一個報告路徑中。這一切都毫無意義，直到資料在試用期內得到驗證，真實的使用者條件用證據取代了假設。

這樣做的好處是能夠用數據代替軼事。現在，我們不再只是說“有些用戶反映表單無法加載”，而是有了可衡量、可追蹤的訊號，可以量化真實的用戶影響。有時候，最有價值的解決方法並非直接解決問題，而是讓你最終看清問題的解決方法。然後，你就可以開始著手改進它了。

故障排除

問題

原因

使固定

CORS 錯誤，重複 <https://https//...>

<https://> 包含在代理值中

僅使用主機名稱： arborydigital.com/nr/agent

New Relic 中沒有數據

腳本未載入或代理配置錯誤

檢查瀏覽器開發者工具的網路選項卡，查看 NR 請求；驗證代理反向規則

會話回放未錄製

抽樣率為10%。

增加NREUM.init.session_replay中的sampling_rate或進行錯誤測試以觸發 100% 捕獲

newrelic 物件未定義

腳本載入順序錯誤

確保newrelic.js是第一個<script> head.html

作者簡介

諾亞馬蒂森

Arbory Digital的技術交付經理

Noah 畢業於北卡羅來納大學威爾明頓分校電腦科學專業，並擁有兩項 AEM 開發人員認證。他最初走的是醫學預科路線，對癌症檢測和人工智慧充滿熱情，並將解決問題的思維方式帶到了他在 Arbory 的工作中。他協助規劃專案執行，分配跨團隊工作，保持良好的溝通，並支援內部運作。他認同 Arbory 的社區和願景，工作之餘，他關注環境保護，喜歡戶外活動，包括露營、衝浪、攀岩。

請透過領英聯繫諾亞。

喜歡你聽到的內容嗎？對什麼更適合自己有疑問嗎？我們很樂意與您交流！聯絡我們