feat: instrument telemetry for status command (#1317)

Hweinstock · jesseturner21 · web-flow · commit 6915c477fc5a · 2026-05-26T09:05:18.000-04:00
* feat: instrument telemetry for status command

Wrap status command execution paths with withCommandRunTelemetry:
- Validation errors (invalid --type/--state)
- Runtime lookup by ID (--runtime-id)
- Default project status

Schema changes:
- Add runtime-endpoint, config-bundle, ab-test to FilterType enum

Error typing:
- Use ValidationError for invalid --type/--state input

Tests:
- Integration tests verifying telemetry emission for all paths

* fix: include deployedState in ProjectStatusResult to fix scope error

After rebasing, the dataset enrichment code referenced context.deployedState
outside the withCommandRunTelemetry callback where context was defined.

Rather than hoisting context outside the callback (which would lose telemetry
coverage for loadStatusConfig failures), include deployedState in the
ProjectStatusResult so it flows through the Result type naturally.

---------

Co-authored-by: Jesse Turner &lt;57651174+jesseturner21@users.noreply.github.com&gt;
diff --git a/integ-tests/status.test.ts b/integ-tests/status.test.ts
@@ -0,0 +1,115 @@
+import { createTelemetryHelper, runCLI } from '../src/test-utils/index.js';
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+describe('status command', () => {
+  let testDir: string;
+  let projectDir: string;
+  const telemetry = createTelemetryHelper();
+
+  beforeAll(async () => {
+    testDir = join(tmpdir(), `agentcore-status-telemetry-${randomUUID()}`);
+    await mkdir(testDir, { recursive: true });
+
+    const projectName = 'StatusTelemetryProj';
+    const result = await runCLI(['create', '--name', projectName, '--no-agent'], testDir);
+    if (result.exitCode !== 0) {
+      throw new Error(`Failed to create project: ${result.stdout} ${result.stderr}`);
+    }
+    projectDir = join(testDir, projectName);
+  });
+
+  afterEach(() => {
+    telemetry.clearEntries();
+  });
+
+  afterAll(async () => {
+    telemetry.destroy();
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it('emits success telemetry for basic status', async () => {
+    const result = await runCLI(['status', '--json'], projectDir, { env: telemetry.env });
+    expect(result.exitCode).toBe(0);
+    telemetry.assertMetricEmitted({
+      command: 'status',
+      exit_reason: 'success',
+      filter_type: 'none',
+      filter_state: 'none',
+    });
+  });
+
+  it('emits success telemetry with filter attrs', async () => {
+    const result = await runCLI(['status', '--type', 'agent', '--state', 'deployed', '--json'], projectDir, {
+      env: telemetry.env,
+    });
+    expect(result.exitCode).toBe(0);
+    telemetry.assertMetricEmitted({
+      command: 'status',
+      exit_reason: 'success',
+      filter_type: 'agent',
+      filter_state: 'deployed',
+    });
+  });
+
+  it('emits success telemetry for runtime-endpoint filter', async () => {
+    const result = await runCLI(['status', '--type', 'runtime-endpoint', '--json'], projectDir, {
+      env: telemetry.env,
+    });
+    expect(result.exitCode).toBe(0);
+    telemetry.assertMetricEmitted({
+      command: 'status',
+      exit_reason: 'success',
+      filter_type: 'runtime-endpoint',
+    });
+  });
+
+  it('emits failure telemetry for invalid --type', async () => {
+    const result = await runCLI(['status', '--type', 'bogus'], projectDir, { env: telemetry.env });
+    expect(result.exitCode).toBe(0);
+    telemetry.assertMetricEmitted({
+      command: 'status',
+      exit_reason: 'failure',
+      filter_type: 'unknown',
+      filter_state: 'none',
+    });
+  });
+
+  it('emits failure telemetry for invalid --state', async () => {
+    const result = await runCLI(['status', '--state', 'bogus'], projectDir, { env: telemetry.env });
+    expect(result.exitCode).toBe(0);
+    telemetry.assertMetricEmitted({
+      command: 'status',
+      exit_reason: 'failure',
+      filter_type: 'none',
+      filter_state: 'unknown',
+    });
+  });
+
+  it('emits failure telemetry for nonexistent target', async () => {
+    const result = await runCLI(['status', '--target', 'nonexistent', '--json'], projectDir, {
+      env: telemetry.env,
+    });
+    expect(result.exitCode).toBe(1);
+    telemetry.assertMetricEmitted({
+      command: 'status',
+      exit_reason: 'failure',
+      filter_type: 'none',
+      filter_state: 'none',
+    });
+  });
+
+  it('emits failure telemetry for --runtime-id lookup', async () => {
+    const result = await runCLI(['status', '--runtime-id', 'fake-id', '--json'], projectDir, {
+      env: telemetry.env,
+    });
+    expect(result.exitCode).toBe(1);
+    telemetry.assertMetricEmitted({
+      command: 'status',
+      exit_reason: 'failure',
+    });
+  });
+});
diff --git a/src/cli/commands/status/action.ts b/src/cli/commands/status/action.ts
@@ -37,6 +37,7 @@ export interface ResourceStatusEntry {
 export type ProjectStatusResult = Result<{
   targetRegion?: string;
   resources: ResourceStatusEntry[];
+  deployedState: DeployedState;
 }> & { projectName?: string; targetName?: string; logPath?: string; resources?: ResourceStatusEntry[] };
 
 export interface StatusContext {
@@ -490,6 +491,7 @@ export async function handleProjectStatus(
     targetName: selectedTargetName ?? '',
     targetRegion: targetConfig?.region,
     resources,
+    deployedState,
     logPath: logger.getRelativeLogPath(),
   };
 }
diff --git a/src/cli/commands/status/command.tsx b/src/cli/commands/status/command.tsx
@@ -1,7 +1,9 @@
-import { serializeResult } from '../../../lib';
+import { ValidationError, serializeResult } from '../../../lib';
 import { getErrorMessage } from '../../errors';
 import { getDatasetStatus } from '../../operations/dataset';
 import type { DatasetStatusResult } from '../../operations/dataset';
+import { withCommandRunTelemetry } from '../../telemetry/cli-command-run.js';
+import { FilterState, FilterType, standardize } from '../../telemetry/schemas/common-shapes.js';
 import { COMMAND_DESCRIPTIONS } from '../../tui/copy';
 import { requireProject } from '../../tui/guards';
 import type { ResourceStatusEntry } from './action';
@@ -73,48 +75,58 @@ export const registerStatus = (program: Command) => {
     .action(async (cliOptions: StatusCliOptions) => {
       requireProject();
 
+      const telemetryAttrs = {
+        filter_type: standardize(FilterType, cliOptions.type ?? 'none'),
+        filter_state: standardize(FilterState, cliOptions.state ?? 'none'),
+      };
+
       // Validate --type
       if (cliOptions.type && !(VALID_RESOURCE_TYPES as readonly string[]).includes(cliOptions.type)) {
-        render(
-          <Text color="red">
-            Invalid resource type &apos;{cliOptions.type}&apos;. Valid types: {VALID_RESOURCE_TYPES.join(', ')}
-          </Text>
-        );
+        const msg = `Invalid resource type '${cliOptions.type}'. Valid types: ${VALID_RESOURCE_TYPES.join(', ')}`;
+        await withCommandRunTelemetry('status', telemetryAttrs, () => ({
+          success: false as const,
+          error: new ValidationError(msg),
+        }));
+        render(<Text color="red">{msg}</Text>);
         return;
       }
 
       // Validate --state
       if (cliOptions.state && !(VALID_STATES as readonly string[]).includes(cliOptions.state)) {
-        render(
-          <Text color="red">
-            Invalid state &apos;{cliOptions.state}&apos;. Valid states: {VALID_STATES.join(', ')}
-          </Text>
-        );
+        const msg = `Invalid state '${cliOptions.state}'. Valid states: ${VALID_STATES.join(', ')}`;
+        await withCommandRunTelemetry('status', telemetryAttrs, () => ({
+          success: false as const,
+          error: new ValidationError(msg),
+        }));
+        render(<Text color="red">{msg}</Text>);
         return;
       }
 
       try {
-        const context = await loadStatusConfig();
-
         // Direct runtime lookup by ID
         if (cliOptions.runtimeId) {
-          const result = await handleRuntimeLookup(context, {
-            agentRuntimeId: cliOptions.runtimeId,
-            targetName: cliOptions.target,
+          const result = await withCommandRunTelemetry('status', telemetryAttrs, async () => {
+            const context = await loadStatusConfig();
+            return handleRuntimeLookup(context, {
+              agentRuntimeId: cliOptions.runtimeId!,
+              targetName: cliOptions.target,
+            });
           });
 
-          if (cliOptions.json) {
-            console.log(JSON.stringify(serializeResult(result), null, 2));
-            return;
+          if (!result.success) {
+            if (cliOptions.json) {
+              console.log(JSON.stringify(serializeResult(result), null, 2));
+            } else {
+              render(<Text color="red">{result.error.message}</Text>);
+            }
+            process.exit(1);
           }
 
-          if (!result.success) {
-            render(<Text color="red">{result.error.message}</Text>);
+          if (cliOptions.json) {
+            console.log(JSON.stringify(serializeResult(result), null, 2));
             return;
           }
-
           const runtimeStatus = result.runtimeStatus ? `Runtime status: ${result.runtimeStatus}` : '';
-
           render(
             <Text>
               AgentCore Status - {result.runtimeId} (target: {result.targetName})
@@ -125,22 +137,23 @@ export const registerStatus = (program: Command) => {
         }
 
         // Default path: show all resource types with deployment state
-        const result = await handleProjectStatus(context, {
-          targetName: cliOptions.target,
+        const result = await withCommandRunTelemetry('status', telemetryAttrs, async () => {
+          const context = await loadStatusConfig();
+          return handleProjectStatus(context, { targetName: cliOptions.target });
         });
 
-        if (cliOptions.json) {
-          if (result.success) {
-            const filtered = filterResources(result.resources, cliOptions);
-            console.log(JSON.stringify({ ...result, resources: filtered }, null, 2));
-          } else {
+        if (!result.success) {
+          if (cliOptions.json) {
             console.log(JSON.stringify(serializeResult(result), null, 2));
+          } else {
+            render(<Text color="red">{result.error.message}</Text>);
           }
-          return;
+          process.exit(1);
         }
 
-        if (!result.success) {
-          render(<Text color="red">{result.error.message}</Text>);
+        if (cliOptions.json) {
+          const filtered = filterResources(result.resources, cliOptions);
+          console.log(JSON.stringify({ ...serializeResult(result), resources: filtered }, null, 2));
           return;
         }
 
@@ -162,7 +175,7 @@ export const registerStatus = (program: Command) => {
         // Fetch enriched dataset info when --type dataset is specified
         let datasetDetails: DatasetStatusResult[] = [];
         if (cliOptions.type === 'dataset' && datasets.length > 0 && result.targetRegion && result.targetName) {
-          const deployedState = context.deployedState;
+          const deployedState = result.deployedState;
           const targetResources = deployedState.targets?.[result.targetName]?.resources;
           const deployedDatasets = targetResources?.datasets ?? {};
 
diff --git a/src/cli/telemetry/schemas/common-shapes.ts b/src/cli/telemetry/schemas/common-shapes.ts
@@ -57,13 +57,16 @@ export const ExitReason = z.enum(['success', 'failure']);
 export const FilterState = z.enum(['deployed', 'local-only', 'pending-removal', 'none']);
 export const FilterType = z.enum([
   'agent',
+  'runtime-endpoint',
   'memory',
   'credential',
   'gateway',
   'evaluator',
   'online-eval',
   'policy-engine',
   'policy',
+  'config-bundle',
+  'ab-test',
   'none',
 ]);
 export const AgentFramework = z.enum(['strands', 'langchain_langgraph', 'googleadk', 'openaiagents']);
