@contrail/cli 3.5.0-alpha.7efeaa8 → 3.5.0-alpha.9d881a5

package/README.md

@@ -17,7 +17,7 @@ $ npm install -g @contrail/cli
 $ contrail COMMAND
 running command...
 $ contrail (--version)
-@contrail/cli/3.5.0-alpha.7efeaa8 linux-x64 node-v24.14.1
+@contrail/cli/3.5.0-alpha.9d881a5 linux-x64 node-v24.14.1
 $ contrail --help [COMMAND]
 USAGE
   $ contrail COMMAND

package/dist/api/dash0/types.d.ts

@@ -79,4 +79,6 @@ export interface FlatSpan {
     durationNs: bigint;
     attrs: Record<string, string | number | boolean>;
     resourceAttrs: Record<string, string | number | boolean>;
+    depthFromAction?: number;
+    serverAncestorCount?: number;
 }

package/dist/commands/event-workflows/assess-impact.js

@@ -68,6 +68,7 @@ class AssessImpact extends basecommand_1.BaseCommand {
         }
         this.log(`Got ${traceIds.length} trace(s). Fetching subtrees...`);
         const perTraceDescendants = [];
+        const actionDurationsNs = [];
         let dropped = 0;
         let totalOrphans = 0;
         let preciseRootCount = 0;
@@ -79,6 +80,7 @@ class AssessImpact extends basecommand_1.BaseCommand {
                 continue;
             }
             perTraceDescendants.push(result.descendants);
+            actionDurationsNs.push(result.actionSpan.durationNs);
             totalOrphans += result.orphanCount;
             if (result.preciseRoot)
                 preciseRootCount++;
@@ -98,6 +100,7 @@ class AssessImpact extends basecommand_1.BaseCommand {
             tracesDropped: dropped,
             totalOrphanCount: totalOrphans,
             preciseRootCount,
+            actionDuration: (0, aggregate_1.summarizeDurations)(actionDurationsNs),
         }));
     }
 }

package/dist/helpers/event-workflow-impact/aggregate.d.ts

@@ -21,3 +21,12 @@ export interface AggregateResult {
 }
 export declare function aggregate(input: AggregateInput): AggregateResult;
 export declare function percentile(values: number[], p: number): number;
+export interface DurationStats {
+    count: number;
+    meanMs: number;
+    p50Ms: number;
+    p95Ms: number;
+    p99Ms: number;
+    maxMs: number;
+}
+export declare function summarizeDurations(durationsNs: bigint[]): DurationStats;

package/dist/helpers/event-workflow-impact/aggregate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.percentile = exports.aggregate = void 0;
+exports.summarizeDurations = exports.percentile = exports.aggregate = void 0;
 const classify_1 = require("./classify");
 const keyId = (k) => `${k.category}\x1f${k.service}\x1f${k.operation}`;
 function aggregate(input) {
@@ -47,3 +47,19 @@ function percentile(values, p) {
     return sorted[idx];
 }
 exports.percentile = percentile;
+function summarizeDurations(durationsNs) {
+    const ms = durationsNs.map((n) => Number(n / 1000000n));
+    if (ms.length === 0) {
+        return { count: 0, meanMs: 0, p50Ms: 0, p95Ms: 0, p99Ms: 0, maxMs: 0 };
+    }
+    const sum = ms.reduce((a, b) => a + b, 0);
+    return {
+        count: ms.length,
+        meanMs: sum / ms.length,
+        p50Ms: percentile(ms, 0.5),
+        p95Ms: percentile(ms, 0.95),
+        p99Ms: percentile(ms, 0.99),
+        maxMs: ms.reduce((a, b) => Math.max(a, b), 0),
+    };
+}
+exports.summarizeDurations = summarizeDurations;

package/dist/helpers/event-workflow-impact/aggregate.spec.js

@@ -13,6 +13,7 @@ function clientHttp(target, service = 'contrail-items') {
         durationNs: 0n,
         attrs: { 'http.request.method': 'GET', 'http.target': target },
         resourceAttrs: { 'service.name': service },
+        depthFromAction: 1,
     };
 }
 function dynamoQuery() {
@@ -69,7 +70,7 @@ describe('aggregate', () => {
         ];
         const result = (0, aggregate_1.aggregate)({ perTraceDescendants: perTrace });
         expect(result.traceCount).toBe(4);
-        const items = result.buckets.find((b) => b.key.category === 'http' && b.key.operation === 'GET /api/items');
+        const items = result.buckets.find((b) => b.key.category === 'http_direct' && b.key.operation === 'GET /api/items');
         expect(items).toBeDefined();
         // counts vector [2,4,0,1] sorted [0,1,2,4]; nearest-rank p50=1, p95=4.
         expect(items.median).toBe(1);
@@ -106,3 +107,28 @@ describe('aggregate', () => {
         expect(result.buckets).toHaveLength(0);
     });
 });
+describe('summarizeDurations', () => {
+    it('returns zeros for empty input', () => {
+        expect((0, aggregate_1.summarizeDurations)([])).toEqual({
+            count: 0,
+            meanMs: 0,
+            p50Ms: 0,
+            p95Ms: 0,
+            p99Ms: 0,
+            maxMs: 0,
+        });
+    });
+    it('converts ns to ms and computes mean + nearest-rank percentiles', () => {
+        // 10 values: 100ms, 200ms, ..., 1000ms.
+        const ns = [];
+        for (let i = 1; i <= 10; i++)
+            ns.push(BigInt(i * 100) * 1000000n);
+        const stats = (0, aggregate_1.summarizeDurations)(ns);
+        expect(stats.count).toBe(10);
+        expect(stats.meanMs).toBe(550); // sum=5500, n=10
+        expect(stats.p50Ms).toBe(500); // ceil(0.5*10)-1 = 4 → sorted[4] = 500
+        expect(stats.p95Ms).toBe(1000); // ceil(0.95*10)-1 = 9 → sorted[9] = 1000
+        expect(stats.p99Ms).toBe(1000);
+        expect(stats.maxMs).toBe(1000);
+    });
+});

package/dist/helpers/event-workflow-impact/classify.d.ts

@@ -1,5 +1,5 @@
 import { FlatSpan } from '../../api/dash0/types';
-export type Category = 'http' | 'opensearch' | 'dynamodb' | 's3' | 'timestream' | 'lambda' | 'other';
+export type Category = 'http_direct' | 'http_transitive' | 'opensearch' | 'dynamodb' | 's3' | 'timestream' | 'lambda' | 'other';
 export declare const CATEGORY_ORDER: Category[];
 export declare const CATEGORY_LABEL: Record<Category, string>;
 export interface Classified {

package/dist/helpers/event-workflow-impact/classify.js

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeRouteName = exports.looksLikeId = exports.templatePath = exports.classifySpan = exports.CATEGORY_LABEL = exports.CATEGORY_ORDER = void 0;
 exports.CATEGORY_ORDER = [
-    'http',
+    'http_direct',
+    'http_transitive',
     'opensearch',
     'dynamodb',
     's3',
@@ -11,7 +12,8 @@ exports.CATEGORY_ORDER = [
     'other',
 ];
 exports.CATEGORY_LABEL = {
-    http: 'HTTP',
+    http_direct: 'HTTP — direct (called by the action)',
+    http_transitive: 'HTTP — transitive (called by downstream services)',
     opensearch: 'OpenSearch',
     dynamodb: 'DynamoDB',
     s3: 'S3',
@@ -61,8 +63,13 @@ function classifySpan(span) {
         // when we have a path; otherwise normalize the leading verb in name so
         // "get /x" and "GET /x" don't split into two buckets.
         const operation = path ? `${method} ${path}` : normalizeRouteName(name);
+        // Direct HTTP = called by the action's own code (no SERVER boundary
+        // between this span and the action root). Transitive = inside a service
+        // the action invoked (1+ SERVER ancestors). Spans without subtree info
+        // (e.g. unit tests) default to direct.
+        const serverAncestors = span.serverAncestorCount ?? 0;
         return {
-            category: 'http',
+            category: serverAncestors === 0 ? 'http_direct' : 'http_transitive',
             service: service || 'unknown',
             operation,
         };

package/dist/helpers/event-workflow-impact/classify.spec.js

@@ -67,7 +67,9 @@ describe('classifySpan', () => {
     it('classifies Timestream AWS SDK spans', () => {
         expect((0, classify_1.classifySpan)(span({ name: 'TimestreamWrite.WriteRecords' }))?.category).toBe('timestream');
     });
-    it('classifies generic HTTP CLIENT spans, templating the path', () => {
+    it('classifies HTTP with no SERVER ancestor as http_direct', () => {
+        // Apps lambda's outbound HTTP CLIENT — sits below the action span via a
+        // lambda-invoke CLIENT, no SERVER boundary in between.
         const s = span({
             name: 'GET',
             attrs: {
@@ -76,13 +78,29 @@ describe('classifySpan', () => {
                 'http.host': 'api.vibeiq.com:443',
             },
             resourceAttrs: { 'service.name': 'contrail-event-workflow-apps' },
+            serverAncestorCount: 0,
         });
         expect((0, classify_1.classifySpan)(s)).toEqual({
-            category: 'http',
+            category: 'http_direct',
             service: 'contrail-event-workflow-apps',
             operation: 'GET /prod/api/items',
         });
     });
+    it('classifies HTTP behind a SERVER boundary as http_transitive', () => {
+        // Outbound HTTP from a downstream service the action called — there is a
+        // SERVER span between this and the action.
+        const s = span({
+            name: 'GET',
+            attrs: {
+                'http.request.method': 'GET',
+                'http.target': '/prod/api/open-search',
+                'http.host': 'api.vibeiq.com:443',
+            },
+            resourceAttrs: { 'service.name': 'contrail-items' },
+            serverAncestorCount: 1,
+        });
+        expect((0, classify_1.classifySpan)(s)?.category).toBe('http_transitive');
+    });
     it('classifies lambda-to-lambda invokes (no HTTP attrs, aws.lambda resource)', () => {
         const s = span({
             name: 'contrail-items-prod-api',
@@ -109,8 +127,10 @@ describe('classifySpan', () => {
             name: 'get /prod/api/custom-entities',
             attrs: { 'http.host': 'api.vibeiq.com:443' },
             resourceAttrs: { 'service.name': 'contrail-custom-entities' },
+            serverAncestorCount: 1,
         });
         expect((0, classify_1.classifySpan)(lower)?.operation).toBe('GET /prod/api/custom-entities');
+        expect((0, classify_1.classifySpan)(lower)?.category).toBe('http_transitive');
     });
     it('falls back to "other" for unknown CLIENT spans without aws.lambda resource', () => {
         expect((0, classify_1.classifySpan)(span({ name: 'mystery-step' }))?.category).toBe('other');

package/dist/helpers/event-workflow-impact/render.d.ts

@@ -1,4 +1,4 @@
-import { AggregateResult } from './aggregate';
+import { AggregateResult, DurationStats } from './aggregate';
 export interface RenderOptions {
     identifier: string;
     dataset: string;
@@ -8,5 +8,6 @@ export interface RenderOptions {
     tracesDropped: number;
     totalOrphanCount: number;
     preciseRootCount: number;
+    actionDuration: DurationStats;
 }
 export declare function renderReport(result: AggregateResult, opts: RenderOptions): string;

package/dist/helpers/event-workflow-impact/render.js

@@ -15,7 +15,15 @@ function renderReport(result, opts) {
         lines.push(`Rooting:   ${opts.preciseRootCount} precise / ${fallback} fallback (no inner action span — framework AWS-SDK direct children stripped heuristically)`);
     }
     lines.push('');
-    lines.push('Per-invocation downstream calls (median / p95 / max / coverage):');
+    const d = opts.actionDuration;
+    if (d.count > 0) {
+        const note = opts.preciseRootCount < opts.samplesObtained
+            ? ' (includes some framework overhead on fallback-rooted traces)'
+            : '';
+        lines.push(`Action duration: mean ${fmtMs(d.meanMs)} · p50 ${fmtMs(d.p50Ms)} · p95 ${fmtMs(d.p95Ms)} · p99 ${fmtMs(d.p99Ms)} · max ${fmtMs(d.maxMs)}${note}`);
+        lines.push('');
+    }
+    lines.push('Per-invocation downstream calls. "% of traces" is how often the bucket appears in any invocation; median/p95/max include zeros.');
     lines.push('');
     const byCategory = new Map();
     for (const b of result.buckets) {
@@ -31,7 +39,7 @@ function renderReport(result, opts) {
         any = true;
         lines.push(classify_1.CATEGORY_LABEL[cat]);
         const table = new cli_table3_1.default({
-            head: ['service', 'operation', 'median', 'p95', 'max', 'coverage'],
+            head: ['service', 'operation', 'median', 'p95', 'max', '% of traces'],
             style: { head: [], border: [] },
         });
         buckets
@@ -60,3 +68,10 @@ exports.renderReport = renderReport;
 function fmt(n) {
     return Number.isInteger(n) ? n.toString() : n.toFixed(1);
 }
+function fmtMs(ms) {
+    if (ms < 1)
+        return `${ms.toFixed(2)}ms`;
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}

package/dist/helpers/event-workflow-impact/subtree.js

@@ -49,9 +49,17 @@ function extractActionSubtree(spans, identifier) {
         return null;
     const preciseRoot = !!inner;
     const descendants = [];
-    const stack = [actionSpan.spanId];
-    while (stack.length) {
-        const parentId = stack.pop();
+    // BFS tracking depth and "service boundary crossings" level-by-level. A
+    // service boundary is a SERVER span (kind=2) that represents code running
+    // in another service. The action's own executor SERVER — the SERVER span
+    // emitted on the receive side of the lambda invocation that runs the
+    // action — is NOT counted, because it represents the action's own
+    // execution context, not downstream work.
+    const queue = [
+        { spanId: actionSpan.spanId, depth: 0, serverAncestors: 0 },
+    ];
+    while (queue.length) {
+        const { spanId: parentId, depth, serverAncestors } = queue.shift();
         const children = byParent.get(parentId) ?? [];
         for (const c of children) {
             // Fallback path: when rooting at the consumer, AWS-SDK spans that are a
@@ -62,8 +70,17 @@ function extractActionSubtree(spans, identifier) {
             if (!preciseRoot && parentId === actionSpan.spanId && isFrameworkAwsSdk(c)) {
                 continue;
             }
+            c.depthFromAction = depth + 1;
+            c.serverAncestorCount = serverAncestors;
             descendants.push(c);
-            stack.push(c.spanId);
+            // Skip the action's executor SERVER from boundary counting: a SERVER
+            // span that is a *direct* child of a non-SERVER action span is the
+            // server side of the invocation that runs the action's code itself.
+            const isExecutorServer = c.kind === 2 &&
+                parentId === actionSpan.spanId &&
+                actionSpan.kind !== 2;
+            const childServerCount = c.kind === 2 && !isExecutorServer ? serverAncestors + 1 : serverAncestors;
+            queue.push({ spanId: c.spanId, depth: depth + 1, serverAncestors: childServerCount });
         }
     }
     let orphanCount = 0;

package/dist/helpers/event-workflow-impact/subtree.spec.js

@@ -20,30 +20,42 @@ describe('extractActionSubtree', () => {
     it('returns null when no candidate exists', () => {
         expect((0, subtree_1.extractActionSubtree)([s({ spanId: 'a' })], IDENT)).toBeNull();
     });
-    describe('precise root (inner PRODUCER span exists)', () => {
-        it('walks descendants of the inner span and excludes consumer-side framework spans', () => {
-            // consumer (root) -> [framework DDB, framework S3, inner action]
-            // inner -> [http GET, http PUT]
-            // http GET -> nested DDB (downstream service's own DDB; should be kept)
+    describe('precise root (inner action span exists)', () => {
+        it('does not count the action executor SERVER as a service boundary', () => {
+            // Realistic Lambda shape: action span (kind=CLIENT, the invocation) has
+            // a SERVER child representing the receive-side of that invocation —
+            // this is the action's own executor lambda. The HTTP outbound from
+            // inside that lambda must be classified as direct (serverAncestorCount=0).
+            // Only SERVER spans BELOW outbound calls (downstream services) count.
             const spans = [
                 s({
                     spanId: 'consumer',
                     parentSpanId: '',
                     name: 'consumer',
+                    kind: 2,
                     attrs: { 'contrail.event_workflow.action.identifier': IDENT },
                 }),
-                s({ spanId: 'frameworkDdb', parentSpanId: 'consumer', name: 'DynamoDB.Query' }),
-                s({ spanId: 'frameworkS3', parentSpanId: 'consumer', name: 'S3.PutObject' }),
-                s({ spanId: 'inner', parentSpanId: 'consumer', name: IDENT, kind: 4 }),
-                s({ spanId: 'http1', parentSpanId: 'inner', name: 'GET' }),
-                s({ spanId: 'http2', parentSpanId: 'inner', name: 'PUT' }),
-                s({ spanId: 'nestedDdb', parentSpanId: 'http1', name: 'DynamoDB.Query' }),
+                s({ spanId: 'inner', parentSpanId: 'consumer', name: IDENT, kind: 3 }),
+                // Action's own executor SERVER (apps lambda receive side) — exempt.
+                s({ spanId: 'execSrv', parentSpanId: 'inner', name: 'apps-lambda', kind: 2 }),
+                // Action code's own outbound HTTP — direct.
+                s({ spanId: 'http1', parentSpanId: 'execSrv', name: 'GET', kind: 3 }),
+                // Downstream SERVER (e.g. contrail-items receiving the request).
+                s({ spanId: 'downSrv', parentSpanId: 'http1', name: 'GET /api/items', kind: 2 }),
+                // HTTP outbound from downstream — transitive.
+                s({ spanId: 'http2', parentSpanId: 'downSrv', name: 'GET', kind: 3 }),
             ];
             const result = (0, subtree_1.extractActionSubtree)(spans, IDENT);
             expect(result).not.toBeNull();
             expect(result.preciseRoot).toBe(true);
-            const ids = result.descendants.map((d) => d.spanId).sort();
-            expect(ids).toEqual(['http1', 'http2', 'nestedDdb']);
+            const find = (id) => result.descendants.find((d) => d.spanId === id);
+            // Executor SERVER is exempt: it gets count 0 itself, and its descendants
+            // don't see +1 from it.
+            expect(find('execSrv').serverAncestorCount).toBe(0);
+            expect(find('http1').serverAncestorCount).toBe(0);
+            // The downstream SERVER does count for its descendants.
+            expect(find('downSrv').serverAncestorCount).toBe(0);
+            expect(find('http2').serverAncestorCount).toBe(1);
         });
     });
     describe('fallback root (no inner span)', () => {

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.0-alpha.7efeaa8",
+  "version": "3.5.0-alpha.9d881a5",
   "commands": {
     "app:create": {
       "id": "app:create",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/cli",
-  "version": "3.5.0-alpha.7efeaa8",
+  "version": "3.5.0-alpha.9d881a5",
   "description": "VibeIQ's Contrail Platform CLI.",
   "bin": {
     "contrail-cli": "./bin/run",