@contrail/cli 3.5.0-alpha.d435e43 → 3.5.0-alpha.dd20a19

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

@@ -0,0 +1,135 @@
+"use strict";
+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_direct',
+    'http_transitive',
+    'opensearch',
+    'dynamodb',
+    's3',
+    'timestream',
+    'lambda',
+    'other',
+];
+exports.CATEGORY_LABEL = {
+    http_direct: 'HTTP — direct (called by the action)',
+    http_transitive: 'HTTP — transitive (called by downstream services)',
+    opensearch: 'OpenSearch',
+    dynamodb: 'DynamoDB',
+    s3: 'S3',
+    timestream: 'Timestream',
+    lambda: 'Lambda invokes',
+    other: 'Other',
+};
+function classifySpan(span) {
+    const name = span.name;
+    const service = span.resourceAttrs['service.name'] ?? '';
+    const httpTarget = span.attrs['http.target'] ?? '';
+    // Skip SERVER spans entirely — they are the receive-side of an HTTP call we
+    // already counted on the client side, plus their internal DB ops are children
+    // and will be classified on their own.
+    if (span.kind === 2 /* SERVER */)
+        return null;
+    // OpenSearch HTTP request — match the actual /<index>/_search call,
+    // not the wrapping contrail-open-search lambda span.
+    if (httpTarget && /\/_search(\?|$)/.test(httpTarget)) {
+        const method = span.attrs['http.request.method'] ?? 'GET';
+        return {
+            category: 'opensearch',
+            service: 'opensearch',
+            operation: `${method} ${templatePath(httpTarget)}`,
+        };
+    }
+    // AWS SDK spans expose service via span name prefixes like `DynamoDB.Query`,
+    // `S3.PutObject`, `TimestreamWrite.WriteRecords`.
+    if (name.startsWith('DynamoDB.')) {
+        return { category: 'dynamodb', service: 'dynamodb', operation: name };
+    }
+    if (name.startsWith('S3.')) {
+        return { category: 's3', service: 's3', operation: name };
+    }
+    if (name.startsWith('Timestream')) {
+        return { category: 'timestream', service: 'timestream', operation: name };
+    }
+    const isHttp = span.attrs['dash0.span.type'] === 'http' ||
+        span.attrs['http.request.method'] !== undefined ||
+        span.attrs['http.host'] !== undefined;
+    if (isHttp) {
+        const method = (span.attrs['http.request.method'] ?? 'GET').toUpperCase();
+        const target = httpTarget || span.attrs['url.full'] || '';
+        const path = templatePath(target);
+        // Span name is sometimes just the method (e.g. "GET"), sometimes the full
+        // route (e.g. "get /prod/api/items"). Build the operation from method+path
+        // 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: serverAncestors === 0 ? 'http_direct' : 'http_transitive',
+            service: service || 'unknown',
+            operation,
+        };
+    }
+    // Lambda-to-lambda invokes appear as CLIENT spans on aws.lambda resources
+    // without HTTP attributes.
+    const isLambdaCall = span.kind === 3 /* CLIENT */ &&
+        span.resourceAttrs['dash0.resource.type'] === 'aws.lambda';
+    if (isLambdaCall) {
+        return { category: 'lambda', service: service || 'unknown', operation: name };
+    }
+    return { category: 'other', service: service || 'unknown', operation: name };
+}
+exports.classifySpan = classifySpan;
+const HTTP_METHOD_PREFIX = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/i;
+function templatePath(target) {
+    if (!target)
+        return '';
+    // Strip query string.
+    let path = target.split('?', 1)[0];
+    // Drop scheme+host if present.
+    if (path.startsWith('http')) {
+        try {
+            path = new URL(path).pathname;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return path
+        .split('/')
+        .map((seg) => (looksLikeId(seg) ? ':id' : seg))
+        .join('/');
+}
+exports.templatePath = templatePath;
+// A segment is treated as an opaque ID (and replaced with `:id`) only when it
+// looks like one. Long kebab-case route names like `assortment-items` should
+// stay readable, so we require numeric content or non-trivial mixed case.
+function looksLikeId(seg) {
+    if (seg.length === 0)
+        return false;
+    if (/^\d+$/.test(seg))
+        return true; // pure numeric
+    if (/^[0-9a-f]{32}$/i.test(seg))
+        return true; // 32-hex (trace IDs etc)
+    // UUIDs.
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(seg)) {
+        return true;
+    }
+    // Mixed case + length suggests an opaque ID (e.g. "cl3MF7mosBf8-Yf9").
+    // Pure-lowercase or pure-uppercase with hyphens stays a route name.
+    if (seg.length >= 12 && /[A-Z]/.test(seg) && /[a-z]/.test(seg))
+        return true;
+    // Long alphanumeric without separators is suspicious.
+    if (seg.length >= 16 && /^[A-Za-z0-9]+$/.test(seg) && /\d/.test(seg))
+        return true;
+    return false;
+}
+exports.looksLikeId = looksLikeId;
+function normalizeRouteName(name) {
+    return name.replace(HTTP_METHOD_PREFIX, (m) => m.toUpperCase());
+}
+exports.normalizeRouteName = normalizeRouteName;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const classify_1 = require("./classify");
+function span(partial = {}) {
+    return {
+        name: 'unnamed',
+        traceId: 't',
+        spanId: 's',
+        parentSpanId: '',
+        kind: 3,
+        startNs: 0n,
+        endNs: 0n,
+        durationNs: 0n,
+        attrs: {},
+        resourceAttrs: {},
+        ...partial,
+    };
+}
+describe('templatePath', () => {
+    it('strips query string', () => {
+        expect((0, classify_1.templatePath)('/api/items?x=1')).toBe('/api/items');
+    });
+    it('replaces id-shaped segments with :id', () => {
+        expect((0, classify_1.templatePath)('/api/items/cl3MF7mosBf8-Yf9')).toBe('/api/items/:id');
+        expect((0, classify_1.templatePath)('/api/items/123456')).toBe('/api/items/:id');
+    });
+    it('keeps short alphabetic segments untouched', () => {
+        expect((0, classify_1.templatePath)('/api/items/foo')).toBe('/api/items/foo');
+    });
+    it('keeps long kebab-case route names untouched', () => {
+        expect((0, classify_1.templatePath)('/prod/api/assortment-items/batch')).toBe('/prod/api/assortment-items/batch');
+        expect((0, classify_1.templatePath)('/prod/api/project-items')).toBe('/prod/api/project-items');
+    });
+    it('replaces UUID segments', () => {
+        expect((0, classify_1.templatePath)('/api/things/550e8400-e29b-41d4-a716-446655440000')).toBe('/api/things/:id');
+    });
+    it('handles full URLs', () => {
+        expect((0, classify_1.templatePath)('https://api.vibeiq.com/prod/api/items?x=1')).toBe('/prod/api/items');
+    });
+});
+describe('classifySpan', () => {
+    it('classifies OpenSearch /_search HTTP spans', () => {
+        const s = span({
+            name: 'GET',
+            attrs: {
+                'http.target': '/gap1/_search',
+                'http.request.method': 'GET',
+            },
+        });
+        expect((0, classify_1.classifySpan)(s)).toEqual({
+            category: 'opensearch',
+            service: 'opensearch',
+            operation: 'GET /gap1/_search',
+        });
+    });
+    it('classifies DynamoDB AWS SDK spans by name prefix', () => {
+        expect((0, classify_1.classifySpan)(span({ name: 'DynamoDB.Query' }))).toEqual({
+            category: 'dynamodb',
+            service: 'dynamodb',
+            operation: 'DynamoDB.Query',
+        });
+        expect((0, classify_1.classifySpan)(span({ name: 'DynamoDB.UpdateItem' }))?.category).toBe('dynamodb');
+    });
+    it('classifies S3 AWS SDK spans', () => {
+        expect((0, classify_1.classifySpan)(span({ name: 'S3.PutObject' }))?.category).toBe('s3');
+    });
+    it('classifies Timestream AWS SDK spans', () => {
+        expect((0, classify_1.classifySpan)(span({ name: 'TimestreamWrite.WriteRecords' }))?.category).toBe('timestream');
+    });
+    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: {
+                'http.request.method': 'GET',
+                'http.target': '/prod/api/items?relations=&criteria=...',
+                'http.host': 'api.vibeiq.com:443',
+            },
+            resourceAttrs: { 'service.name': 'contrail-event-workflow-apps' },
+            serverAncestorCount: 0,
+        });
+        expect((0, classify_1.classifySpan)(s)).toEqual({
+            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',
+            kind: 3,
+            resourceAttrs: {
+                'service.name': 'contrail-items',
+                'dash0.resource.type': 'aws.lambda',
+            },
+        });
+        expect((0, classify_1.classifySpan)(s)).toEqual({
+            category: 'lambda',
+            service: 'contrail-items',
+            operation: 'contrail-items-prod-api',
+        });
+    });
+    it('drops SERVER-side spans (already represented by client side)', () => {
+        expect((0, classify_1.classifySpan)(span({ kind: 2, name: 'GET /prod/api/items' }))).toBeNull();
+    });
+    it('uppercases the HTTP method when falling back to span.name', () => {
+        // Some spans have only http.host set (not http.target/method) and a
+        // lowercase verb in the span name. They should bucket with their uppercase
+        // siblings rather than splitting.
+        const lower = span({
+            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

@@ -0,0 +1,12 @@
+import { AggregateResult } from './aggregate';
+export interface RenderOptions {
+    identifier: string;
+    dataset: string;
+    lookback: string;
+    samplesRequested: number;
+    samplesObtained: number;
+    tracesDropped: number;
+    totalOrphanCount: number;
+    preciseRootCount: number;
+}
+export declare function renderReport(result: AggregateResult, opts: RenderOptions): string;

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderReport = void 0;
+const tslib_1 = require("tslib");
+const cli_table3_1 = tslib_1.__importDefault(require("cli-table3"));
+const classify_1 = require("./classify");
+function renderReport(result, opts) {
+    const lines = [];
+    lines.push(`Action:    ${opts.identifier}`);
+    lines.push(`Dataset:   ${opts.dataset}`);
+    lines.push(`Lookback:  ${opts.lookback}`);
+    lines.push(`Samples:   ${opts.samplesObtained}/${opts.samplesRequested} (${opts.tracesDropped} dropped)`);
+    if (opts.preciseRootCount < opts.samplesObtained) {
+        const fallback = opts.samplesObtained - opts.preciseRootCount;
+        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. "% 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) {
+        const arr = byCategory.get(b.key.category) ?? [];
+        arr.push(b);
+        byCategory.set(b.key.category, arr);
+    }
+    let any = false;
+    for (const cat of classify_1.CATEGORY_ORDER) {
+        const buckets = byCategory.get(cat);
+        if (!buckets || buckets.length === 0)
+            continue;
+        any = true;
+        lines.push(classify_1.CATEGORY_LABEL[cat]);
+        const table = new cli_table3_1.default({
+            head: ['service', 'operation', 'median', 'p95', 'max', '% of traces'],
+            style: { head: [], border: [] },
+        });
+        buckets
+            .sort((a, b) => b.p95 - a.p95 || b.max - a.max)
+            .forEach((b) => table.push([
+            b.key.service,
+            b.key.operation,
+            fmt(b.median),
+            fmt(b.p95),
+            fmt(b.max),
+            `${(b.coverage * 100).toFixed(0)}%`,
+        ]));
+        lines.push(table.toString());
+        lines.push('');
+    }
+    if (!any) {
+        lines.push('  (no descendant spans observed in the action subtree)');
+        lines.push('');
+    }
+    if (opts.totalOrphanCount > 0) {
+        lines.push(`Note: ${opts.totalOrphanCount} span(s) across sampled traces have a parent ID we never observed — likely propagation gaps. Numbers above may undercount.`);
+    }
+    return lines.join('\n');
+}
+exports.renderReport = renderReport;
+function fmt(n) {
+    return Number.isInteger(n) ? n.toString() : n.toFixed(1);
+}

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

@@ -0,0 +1,20 @@
+import { FlatSpan } from '../../api/dash0/types';
+export interface SubtreeResult {
+    descendants: FlatSpan[];
+    actionSpan: FlatSpan;
+    preciseRoot: boolean;
+    orphanCount: number;
+}
+/**
+ * Walk descendants under the span carrying the action identifier.
+ *
+ * The action identifier is set on the workflow consumer span (the lambda root)
+ * AND echoed onto a child PRODUCER span named after the action identifier itself.
+ * We root from whichever bears `contrail.event_workflow.action.identifier` AND has
+ * a span name matching the identifier (the inner action span). If we can't find
+ * that, we fall back to the consumer-level span.
+ *
+ * The returned descendants set excludes the framework consumer overhead — only
+ * what the action's code touched.
+ */
+export declare function extractActionSubtree(spans: FlatSpan[], identifier: string): SubtreeResult | null;

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractActionSubtree = void 0;
+// AWS SDK span name prefixes that, when emitted as a *direct* child of the
+// consumer span, represent the workflow framework's own infrastructure
+// (task-state DDB writes, S3 payload staging, Timestream metrics, queue ops),
+// not customer code. These are stripped (along with their subtrees) when we
+// have to fall back to the consumer span as the root.
+const FRAMEWORK_AWS_SDK_PREFIXES = ['DynamoDB.', 'S3.', 'Timestream', 'SQS.', 'SNS.'];
+function isFrameworkAwsSdk(span) {
+    return FRAMEWORK_AWS_SDK_PREFIXES.some((p) => span.name.startsWith(p));
+}
+/**
+ * Walk descendants under the span carrying the action identifier.
+ *
+ * The action identifier is set on the workflow consumer span (the lambda root)
+ * AND echoed onto a child PRODUCER span named after the action identifier itself.
+ * We root from whichever bears `contrail.event_workflow.action.identifier` AND has
+ * a span name matching the identifier (the inner action span). If we can't find
+ * that, we fall back to the consumer-level span.
+ *
+ * The returned descendants set excludes the framework consumer overhead — only
+ * what the action's code touched.
+ */
+function extractActionSubtree(spans, identifier) {
+    if (spans.length === 0)
+        return null;
+    const byParent = new Map();
+    const byId = new Map();
+    for (const s of spans) {
+        byId.set(s.spanId, s);
+        if (s.parentSpanId) {
+            const arr = byParent.get(s.parentSpanId) ?? [];
+            arr.push(s);
+            byParent.set(s.parentSpanId, arr);
+        }
+    }
+    // The inner action span is named exactly after the identifier (PRODUCER kind,
+    // child of the consumer lambda). When that exists, walking it yields exactly
+    // the action's downstream calls.
+    const inner = spans.find((s) => s.name === identifier);
+    // The consumer/root span carries `contrail.event_workflow.action.identifier`
+    // as an attribute. Some action variants run inline in the consumer (no
+    // inner PRODUCER span); for those we root at the consumer and strip the
+    // framework's direct AWS-SDK children.
+    const carrier = spans.find((s) => s.attrs['contrail.event_workflow.action.identifier'] === identifier);
+    const actionSpan = inner ?? carrier;
+    if (!actionSpan)
+        return null;
+    const preciseRoot = !!inner;
+    const descendants = [];
+    // 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
+            // *direct* child of the consumer are framework infrastructure (task-state
+            // DDB writes, S3 payload staging, Timestream metrics). Skip them and
+            // their subtrees. Nested AWS-SDK spans (e.g. DDB queries inside a
+            // downstream contrail-items lambda) are kept.
+            if (!preciseRoot && parentId === actionSpan.spanId && isFrameworkAwsSdk(c)) {
+                continue;
+            }
+            c.depthFromAction = depth + 1;
+            c.serverAncestorCount = serverAncestors;
+            descendants.push(c);
+            // 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;
+    for (const s of spans) {
+        if (s.parentSpanId && !byId.has(s.parentSpanId))
+            orphanCount++;
+    }
+    return { descendants, actionSpan, preciseRoot, orphanCount };
+}
+exports.extractActionSubtree = extractActionSubtree;

package/dist/helpers/event-workflow-impact/subtree.spec.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const subtree_1 = require("./subtree");
+const IDENT = '@gap-automations:exampleAction';
+function s(part) {
+    return {
+        name: part.spanId,
+        traceId: 't',
+        parentSpanId: '',
+        kind: 3,
+        startNs: 0n,
+        endNs: 0n,
+        durationNs: 0n,
+        attrs: {},
+        resourceAttrs: {},
+        ...part,
+    };
+}
+describe('extractActionSubtree', () => {
+    it('returns null when no candidate exists', () => {
+        expect((0, subtree_1.extractActionSubtree)([s({ spanId: 'a' })], IDENT)).toBeNull();
+    });
+    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: '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 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)', () => {
+        it('walks consumer subtree but strips direct AWS-SDK children', () => {
+            // consumer carries the identifier attr.
+            // direct children: framework DDB, framework S3, framework Timestream,
+            //                  http GET (action work)
+            // http GET -> nested DDB (downstream's own DDB; should be kept)
+            const spans = [
+                s({
+                    spanId: 'consumer',
+                    parentSpanId: '',
+                    name: 'consumer-lambda',
+                    attrs: { 'contrail.event_workflow.action.identifier': IDENT },
+                }),
+                s({ spanId: 'fwDdb', parentSpanId: 'consumer', name: 'DynamoDB.Query' }),
+                s({ spanId: 'fwS3', parentSpanId: 'consumer', name: 'S3.GetObject' }),
+                s({
+                    spanId: 'fwTs',
+                    parentSpanId: 'consumer',
+                    name: 'TimestreamWrite.WriteRecords',
+                }),
+                s({ spanId: 'http1', parentSpanId: 'consumer', name: 'GET' }),
+                s({ spanId: 'nestedDdb', parentSpanId: 'http1', name: 'DynamoDB.Query' }),
+            ];
+            const result = (0, subtree_1.extractActionSubtree)(spans, IDENT);
+            expect(result).not.toBeNull();
+            expect(result.preciseRoot).toBe(false);
+            const ids = result.descendants.map((d) => d.spanId).sort();
+            expect(ids).toEqual(['http1', 'nestedDdb']);
+        });
+    });
+    it('counts orphans (parent_id pointing outside the trace)', () => {
+        const spans = [
+            s({
+                spanId: 'consumer',
+                parentSpanId: '',
+                attrs: { 'contrail.event_workflow.action.identifier': IDENT },
+            }),
+            s({ spanId: 'unattached', parentSpanId: 'missing-parent' }),
+        ];
+        const result = (0, subtree_1.extractActionSubtree)(spans, IDENT);
+        expect(result.orphanCount).toBe(1);
+    });
+});

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.0-alpha.d435e43",
+  "version": "3.5.0-alpha.dd20a19",
   "commands": {
     "app:create": {
       "id": "app:create",
@@ -672,6 +672,84 @@
         }
       }
     },
+    "event-workflows:assess-impact": {
+      "id": "event-workflows:assess-impact",
+      "description": "Sample Dash0 traces of an event-workflow action and report per-invocation downstream impact.",
+      "strict": true,
+      "pluginName": "@contrail/cli",
+      "pluginAlias": "@contrail/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "examples": [
+        "contrail event-workflows assess-impact @gap-automations:bomCcCostUpdate",
+        "contrail event-workflows assess-impact @gap-automations:bomCcCostUpdate --samples 25 --lookback 6h"
+      ],
+      "flags": {
+        "logLevel": {
+          "name": "logLevel",
+          "type": "option",
+          "char": "l",
+          "description": "The Log Level",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "error",
+            "warn",
+            "info",
+            "debug"
+          ]
+        },
+        "alwaysConfirmEnv": {
+          "name": "alwaysConfirmEnv",
+          "type": "option",
+          "char": "e",
+          "description": "The Environment variables",
+          "required": false,
+          "multiple": false,
+          "options": [
+            "true",
+            "false"
+          ],
+          "default": "true"
+        },
+        "samples": {
+          "name": "samples",
+          "type": "option",
+          "char": "s",
+          "description": "Number of distinct traces to sample (10-100).",
+          "multiple": false,
+          "default": 50
+        },
+        "lookback": {
+          "name": "lookback",
+          "type": "option",
+          "description": "How far back to search. Format: 30m | 6h | 2d.",
+          "multiple": false,
+          "default": "2d"
+        },
+        "dataset": {
+          "name": "dataset",
+          "type": "option",
+          "description": "Dash0 dataset.",
+          "multiple": false,
+          "default": "prod"
+        },
+        "json": {
+          "name": "json",
+          "type": "boolean",
+          "char": "j",
+          "description": "JSON output (not yet implemented; flag reserved).",
+          "allowNo": false
+        }
+      },
+      "args": {
+        "identifier": {
+          "name": "identifier",
+          "description": "Action identifier (contrail.event_workflow.action.identifier).",
+          "required": true
+        }
+      }
+    },
     "file:upload": {
       "id": "file:upload",
       "description": "Uploads a file to the VibeIQ platform",