@servicetitan/journey 4.0.0 → 4.2.0

package/src/integrations/request-correlation.ts

@@ -0,0 +1,93 @@
+import {
+    isMonolithLogOrigin,
+    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 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 (!isMonolithLogOrigin(url.href)) {
+            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 && !isMonolithLogOrigin(finalUrl)) {
+            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 { journeyLogsLink, requestLogsUrl } from './kibana';
 
 export { normalizeTagValue } from '../core/sanitize';
 
@@ -14,6 +15,7 @@ const DD_RUM_KEY = 'DD_RUM';
  */
 interface RumLike {
     addAction(name: string, context?: object): void;
+    getUser?(): unknown;
 }
 
 function getDdRum(): RumLike | undefined {
@@ -54,6 +56,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 }
             : {}),
@@ -71,6 +85,7 @@ export function sendToDatadog(payload: JourneyEvent): void {
     const j = isSanitizedJourneyEvent(payload)
         ? payload.journey
         : sanitizeJourneyEvent(payload).journey;
+    const logs = journeyLogsLink(j, () => rum.getUser?.(), globalThis.location?.href);
     /* eslint-disable @typescript-eslint/naming-convention -- Datadog RUM wire format (snake_case) */
     rum.addAction(JOURNEY_ACTION, {
         journey: {
@@ -79,6 +94,12 @@ export function sendToDatadog(payload: JourneyEvent): void {
             group: j.group,
             service: j.service,
             outcome: j.outcome,
+            ...(j.failedRequest
+                ? {
+                      failed_request_id: j.failedRequest.rayId,
+                  }
+                : {}),
+            ...(logs ? { kibana_url: logs.url, kibana_scope: logs.scope } : {}),
             ...(j.reason ? { reason: j.reason } : {}),
             duration_ms: j.durationMs,
             steps: j.steps.map(toDatadogStep),

package/src/sinks/kibana.ts

@@ -0,0 +1,140 @@
+import {
+    isMonolithLogOrigin,
+    MAX_JOURNEY_CORRELATED_REQUESTS,
+    sanitizeRequestCorrelation,
+} from '../core/request-correlation';
+import type { JourneyEvent, 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);
+    return discoverUrl(`Request.RequestId: ${rayPrefix}*`, from, to);
+}
+
+interface JourneyLogLink {
+    url: string;
+    scope: 'request' | 'related_requests' | 'related_logs';
+}
+
+function discoverUrl(query: string, from: string, to: string): string {
+    const globalState = `(refreshInterval:(pause:!t,value:0),time:(from:'${from}',to:'${to}'))`;
+    // The query is a quoted Rison string containing a separately escaped KQL expression.
+    const quotedQuery = query.replace(/!/g, '!!').replace(/'/g, "!'");
+    const appState = `(dataSource:(type:dataView,dataViewId:'${DATA_VIEW_ID}'),query:(language:kuery,query:'${quotedQuery}'))`;
+    return `${DISCOVER_URL}?_g=${encodeURIComponent(globalState)}&_a=${encodeURIComponent(appState)}`;
+}
+
+function userValue(value: unknown): string | undefined {
+    return typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= 254 &&
+        // eslint-disable-next-line no-control-regex -- Reject controls in log query values.
+        !/[\u0000-\u001f\u007f]/.test(value)
+        ? value
+        : undefined;
+}
+
+function kqlValue(value: string): string {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function relatedLogsUrl(
+    durationMs: number,
+    user: unknown,
+    pageUrl: string | undefined
+): string | undefined {
+    if (
+        !pageUrl ||
+        !isMonolithLogOrigin(pageUrl) ||
+        !user ||
+        typeof user !== 'object' ||
+        !Number.isFinite(durationMs) ||
+        durationMs < 0 ||
+        durationMs > 86_400_000
+    ) {
+        return;
+    }
+    const context = user as Record<string, unknown>;
+    const tenant = userValue(context.tenant);
+    const users = [...new Set([userValue(context.name), userValue(context.email)])].filter(
+        (value): value is string => value !== undefined
+    );
+    // Never fall back to all tenants or all users when identity is missing.
+    if (!tenant || !/^[a-z0-9][a-z0-9_-]*$/i.test(tenant) || users.length === 0) {
+        return;
+    }
+    const query = `Context.TenantName: ${kqlValue(tenant)} AND (${users
+        .map(value => `Request.User: ${kqlValue(value)}`)
+        .join(' OR ')})`;
+    const now = Date.now();
+    return discoverUrl(
+        query,
+        new Date(now - durationMs - WINDOW_PADDING_MS).toISOString(),
+        new Date(now + WINDOW_PADDING_MS).toISOString()
+    );
+}
+
+/** Keep one visible link without claiming unrelated requests caused a JS/business failure. */
+export function journeyLogsLink(
+    journey: JourneyEvent['journey'],
+    getUser?: () => unknown,
+    pageUrl?: string
+): JourneyLogLink | undefined {
+    if (journey.failedRequest) {
+        const url = requestLogsUrl(journey.failedRequest);
+        if (url) {
+            return { url, scope: 'request' };
+        }
+    }
+
+    /*
+     * With no identified failure request, search this user's logs during the journey.
+     * RUM stubs/older hosts can lack getUser; enrichment must never prevent emission.
+     */
+    try {
+        const url = relatedLogsUrl(journey.durationMs, getUser?.(), pageUrl);
+        if (url) {
+            return { url, scope: 'related_logs' };
+        }
+    } catch {
+        // Retain request-only links if session context is unavailable or malformed.
+    }
+
+    const requests = journey.steps
+        .flatMap(step => step.requests ?? [])
+        .slice(0, MAX_JOURNEY_CORRELATED_REQUESTS)
+        .map(sanitizeRequestCorrelation)
+        .filter((request): request is JourneyRequestEvent => request !== undefined);
+    if (!requests.length) {
+        return;
+    }
+    const prefixes = [...new Set(requests.map(request => request.rayId.slice(0, 16)))];
+    const query = prefixes.map(prefix => `Request.RequestId: ${prefix}*`).join(' OR ');
+    return {
+        url: discoverUrl(
+            query,
+            new Date(
+                Math.min(...requests.map(request => request.startedAtEpoch)) - WINDOW_PADDING_MS
+            ).toISOString(),
+            new Date(
+                Math.max(...requests.map(request => request.startedAtEpoch + request.durationMs)) +
+                    WINDOW_PADDING_MS
+            ).toISOString()
+        ),
+        scope: 'related_requests',
+    };
+}