@servicetitan/journey 4.0.0 → 4.1.0

package/src/integrations/http-report.ts

@@ -10,6 +10,7 @@ import { canRouteHttpToJourney, resolveJourneyEngine } from '../core/runtime';
 import type { JourneyStepStamp } from '../core/step-tag';
 import type { StepRecord } from '../core/types';
 import type { JourneyTimedMeta } from './request-key';
+import { captureRequestCorrelation } from './request-correlation';
 
 export interface HttpCompleteReport {
     stamp: JourneyStepStamp | undefined;
@@ -18,6 +19,8 @@ export interface HttpCompleteReport {
     requestKey: string;
     aborted?: boolean;
     url?: string;
+    /** Actual request base, used only to validate the log-correlation origin. */
+    baseURL?: string;
     method?: string;
     /** Per-request literal overrides from JourneyTimedMeta. */
     meta?: JourneyTimedMeta;
@@ -73,19 +76,7 @@ function httpScoreReason(report: HttpCompleteReport): string {
  * 4xx with policy `'continue'` (default) still scores latency.
  */
 export function onHttpComplete(report: HttpCompleteReport): void {
-    const {
-        stamp,
-        status,
-        durationMs,
-        requestKey,
-        aborted,
-        url,
-        method,
-        meta,
-        request,
-        response,
-        error,
-    } = report;
+    const { stamp, requestKey, aborted, meta } = report;
     if (!stamp) {
         return;
     }
@@ -124,6 +115,34 @@ export function onHttpComplete(report: HttpCompleteReport): void {
         return;
     }
 
+    // Capture before a policy/latency breach synchronously emits the terminal event.
+    const correlation = captureRequestCorrelation(report);
+    const previous = step.journey.scoringRequest;
+    // Scope this pointer to scoring. Later JS/business failures must not blame the last request.
+    step.journey.scoringRequest = correlation;
+    try {
+        scoreHttpComplete(report, step);
+    } finally {
+        step.journey.scoringRequest = previous;
+    }
+}
+
+function scoreHttpComplete(report: HttpCompleteReport, step: StepRecord): void {
+    const {
+        stamp,
+        status,
+        durationMs,
+        requestKey,
+        aborted,
+        url,
+        method,
+        meta,
+        request,
+        response,
+        error,
+    } = report;
+    const engine = resolveJourneyEngine(step.journey);
+
     const ctx: JourneyHttpPolicyContext = {
         requestKey,
         status,
@@ -134,7 +153,7 @@ export function onHttpComplete(report: HttpCompleteReport): void {
         stepName: step.name,
     };
 
-    const score = stamp.score;
+    const score = stamp?.score;
     if (score) {
         let policy: JourneyRequestPolicy | undefined;
         try {

package/src/integrations/jquery/instrument.ts

@@ -5,7 +5,8 @@ import {
     registerInstrumentRecord,
     type InstrumentRecord,
 } from '../../global';
-import { onHttpComplete } from '../http-report';
+import { onHttpComplete, type HttpCompleteReport } from '../http-report';
+import { captureRequestCorrelation } from '../request-correlation';
 import { requestKey, type JourneyTimedMeta } from '../request-key';
 import { acceptInstrumentTarget } from '../soft-skip';
 
@@ -14,6 +15,8 @@ export interface JqueryXHR {
     statusText?: string;
     stamp?: unknown;
     journeyStart?: number;
+    getResponseHeader?(name: string): string | null;
+    always?(callback: () => void): unknown;
 }
 
 export interface JqueryAjaxSettings extends JourneyTimedMeta {
@@ -39,7 +42,10 @@ export interface JqueryStatic {
     };
 }
 
-function reportTiming(jqXHR: JqueryXHR, settings: JqueryAjaxSettings): void {
+function timingReport(
+    jqXHR: JqueryXHR,
+    settings: JqueryAjaxSettings
+): HttpCompleteReport | undefined {
     const stamp = jqueryStamps.get(jqXHR) ?? adoptJourneyStepStamp(jqXHR.stamp);
     if (!stamp || stamp.ignore || settings.ignore === true) {
         return;
@@ -48,7 +54,7 @@ function reportTiming(jqXHR: JqueryXHR, settings: JqueryAjaxSettings): void {
     const aborted = jqXHR.statusText === 'abort';
     // jQuery uses status 0 for network / abort failures — treat like a missing status.
     const status = aborted || jqXHR.status === 0 ? undefined : jqXHR.status;
-    onHttpComplete({
+    return {
         stamp,
         status,
         durationMs: globalThis.performance.now() - start,
@@ -59,7 +65,7 @@ function reportTiming(jqXHR: JqueryXHR, settings: JqueryAjaxSettings): void {
         meta: settings,
         request: settings,
         response: jqXHR,
-    });
+    };
 }
 
 function isJqueryStatic(value: unknown): value is JqueryStatic {
@@ -118,6 +124,29 @@ export function instrumentJquery($: JqueryStatic | null | undefined): () => void
                     return;
                 }
                 stampAjax(jqXHR, options);
+                /*
+                 * Prefilters run before application success/error callbacks; ajaxComplete runs after.
+                 * Capture headers here, but keep verdict scoring in ajaxComplete as before.
+                 */
+                try {
+                    if (jqueryStamps.has(jqXHR)) {
+                        jqXHR.always?.(() => {
+                            if (current.disposed) {
+                                return;
+                            }
+                            try {
+                                const report = timingReport(jqXHR, options);
+                                if (report) {
+                                    captureRequestCorrelation(report);
+                                }
+                            } catch {
+                                // This observer must never interrupt application callbacks.
+                            }
+                        });
+                    }
+                } catch {
+                    // Partial jQuery-compatible clients may not support response observers.
+                }
             });
             jqueryPrefiltersInstalled.add(key);
         }
@@ -127,7 +156,10 @@ export function instrumentJquery($: JqueryStatic | null | undefined): () => void
                 if (!current || current.disposed) {
                     return;
                 }
-                reportTiming(jqXHR, settings);
+                const report = timingReport(jqXHR, settings);
+                if (report) {
+                    onHttpComplete(report);
+                }
             });
             jqueryCompletesInstalled.add(key);
         }

package/src/integrations/request-correlation.ts

@@ -0,0 +1,90 @@
+import { MAX_CORRELATED_REQUESTS, sanitizeRequestCorrelation } from '../core/request-correlation';
+import { canRouteHttpToJourney, resolveJourneyEngine } from '../core/runtime';
+import type { HttpCompleteReport } from './http-report';
+import type { JourneyRequestEvent } from '../core/types';
+
+const MONOLITH_ORIGIN = 'https://go.servicetitan.com';
+const capturedResponses = new WeakMap<object, JourneyRequestEvent>();
+
+interface ResponseHeaders {
+    headers?: { 'cf-ray'?: unknown; 'get'?(name: string): unknown };
+    url?: string;
+    responseURL?: string;
+    request?: { responseURL?: string };
+    getResponseHeader?(name: string): unknown;
+}
+
+/** Observation only. Safe to run before jQuery invokes application callbacks. */
+export function captureRequestCorrelation(
+    report: HttpCompleteReport
+): JourneyRequestEvent | undefined {
+    try {
+        const step = report.stamp?.step;
+        if (
+            !step?.journey ||
+            step.journey.closed ||
+            !canRouteHttpToJourney(step.journey) ||
+            report.stamp?.ignore ||
+            report.meta?.ignore ||
+            report.aborted ||
+            !report.url ||
+            resolveJourneyEngine(step.journey).shouldIgnoreRequest(report.requestKey)
+        ) {
+            return;
+        }
+
+        // Other environments/backends have not verified this log-field/data-view contract.
+        const pageUrl = globalThis.location?.href;
+        const base = report.baseURL ? new URL(report.baseURL, pageUrl).href : pageUrl;
+        const url = new URL(report.url, base);
+        if (url.origin !== MONOLITH_ORIGIN) {
+            return;
+        }
+        const response = report.response as ResponseHeaders | undefined;
+        if (!response || typeof response !== 'object') {
+            return;
+        }
+        const captured = capturedResponses.get(response);
+        if (captured) {
+            return step.requests?.includes(captured) ? captured : undefined;
+        }
+        const finalUrl = response.url || response.responseURL || response.request?.responseURL;
+        if (finalUrl && new URL(finalUrl).origin !== MONOLITH_ORIGIN) {
+            return;
+        }
+        const rayId =
+            typeof response.getResponseHeader === 'function'
+                ? response.getResponseHeader('cf-ray')
+                : typeof response.headers?.get === 'function'
+                  ? response.headers.get('cf-ray')
+                  : response.headers?.['cf-ray'];
+        if (typeof rayId !== 'string') {
+            return;
+        }
+        const request = sanitizeRequestCorrelation({
+            rayId,
+            startedAtEpoch: Date.now() - report.durationMs,
+            durationMs: report.durationMs,
+            status: report.status as number,
+        });
+        if (!request) {
+            return;
+        }
+        capturedResponses.set(response, request);
+        step.requests ??= [];
+        const requests = step.requests;
+        if (requests.length >= MAX_CORRELATED_REQUESTS) {
+            step.requestsTruncated = true;
+            // Keep errors when later successes arrive. A new error replaces a success first.
+            const replace = requests.findIndex(item => item.status < 400);
+            if (replace < 0 && request.status < 400) {
+                return request;
+            }
+            requests.splice(replace < 0 ? 0 : replace, 1);
+        }
+        requests.push(request);
+        return request;
+    } catch {
+        // Missing/blocked headers and unusual transport objects must not affect requests.
+    }
+}

package/src/sinks/datadog.ts

@@ -1,6 +1,7 @@
 import { isSanitizedJourneyEvent, sanitizeJourneyEvent } from '../core/sanitize';
 import { getJourneyRumFallback, setJourneyRumFallback } from '../global';
 import type { JourneyEvent, JourneyStepEvent } from '../core/types';
+import { requestLogsUrl } from './kibana';
 
 export { normalizeTagValue } from '../core/sanitize';
 
@@ -54,6 +55,18 @@ function toDatadogStep(step: JourneyStepEvent) {
         outcome: step.outcome,
         ...(step.reason ? { reason: step.reason } : {}),
         ...(step.httpStatus !== undefined ? { http_status: step.httpStatus } : {}),
+        ...(step.requests?.length
+            ? {
+                  requests: step.requests.map(request => ({
+                      request_id: request.rayId,
+                      started_at: new Date(request.startedAtEpoch).toISOString(),
+                      duration_ms: request.durationMs,
+                      http_status: request.status,
+                      kibana_url: requestLogsUrl(request),
+                  })),
+              }
+            : {}),
+        ...(step.requestsTruncated ? { requests_truncated: true } : {}),
         ...(step.attributes && Object.keys(step.attributes).length
             ? { attributes: step.attributes }
             : {}),
@@ -79,6 +92,12 @@ export function sendToDatadog(payload: JourneyEvent): void {
             group: j.group,
             service: j.service,
             outcome: j.outcome,
+            ...(j.failedRequest
+                ? {
+                      failed_request_id: j.failedRequest.rayId,
+                      kibana_url: requestLogsUrl(j.failedRequest),
+                  }
+                : {}),
             ...(j.reason ? { reason: j.reason } : {}),
             duration_ms: j.durationMs,
             steps: j.steps.map(toDatadogStep),

package/src/sinks/kibana.ts

@@ -0,0 +1,24 @@
+import { sanitizeRequestCorrelation } from '../core/request-correlation';
+import type { JourneyRequestEvent } from '../core/types';
+
+const DISCOVER_URL = 'https://kibana.st.dev/app/discover#/';
+// Production monolith logs; deliberately not the user's default data view.
+const DATA_VIEW_ID = '894110ed-c22d-449c-9dc2-c4816f08712a';
+const WINDOW_PADDING_MS = 60_000;
+
+/** Fixed destination and validated Ray ID only — no request URL, query string or user data. */
+export function requestLogsUrl(value: JourneyRequestEvent): string | undefined {
+    const request = sanitizeRequestCorrelation(value);
+    if (!request) {
+        return undefined;
+    }
+    const from = new Date(request.startedAtEpoch - WINDOW_PADDING_MS).toISOString();
+    const to = new Date(
+        request.startedAtEpoch + request.durationMs + WINDOW_PADDING_MS
+    ).toISOString();
+    // Origin/edge datacenter suffixes can differ. Match the hex prefix within the request window.
+    const rayPrefix = request.rayId.slice(0, 16);
+    const globalState = `(refreshInterval:(pause:!t,value:0),time:(from:'${from}',to:'${to}'))`;
+    const appState = `(dataSource:(type:dataView,dataViewId:'${DATA_VIEW_ID}'),query:(language:kuery,query:'Request.RequestId: ${rayPrefix}*'))`;
+    return `${DISCOVER_URL}?_g=${encodeURIComponent(globalState)}&_a=${encodeURIComponent(appState)}`;
+}