Skip to content

feat: add ztd-cli command phase telemetry spans#527

Merged
mk3008 merged 6 commits intomainfrom
codex/issue-518-command-spans
Mar 8, 2026
Merged

feat: add ztd-cli command phase telemetry spans#527
mk3008 merged 6 commits intomainfrom
codex/issue-518-command-spans

Conversation

@mk3008
Copy link
Copy Markdown
Owner

@mk3008 mk3008 commented Mar 8, 2026

Summary

  • add stable phase spans for query uses, model-gen, and ddl diff on top of the thin internal telemetry abstraction
  • add sync span support plus integration-style CLI telemetry tests for the command entry paths
  • keep failure handling on the existing root span wiring while documenting stable child span names in exported constants

Verification

  • pnpm --filter @rawsql-ts/ztd-cli build (fails in existing @rawsql-ts/testkit-core rawsql-ts module resolution errors before ztd-cli build completes)
  • tsc -p packages/ztd-cli/tsconfig.json --noEmit
  • vitest run --config packages/ztd-cli/vitest.config.ts packages/ztd-cli/tests/telemetry.unit.test.ts packages/ztd-cli/tests/commandTelemetry.unit.test.ts

Notes

Summary by CodeRabbit

  • Tests

    • Added telemetry tests for CLI flows (query, model-gen, ddl-diff) and a unit test validating synchronous span behavior.
  • Chores

    • Instrumented core CLI workflows with named telemetry phases for improved observability.
    • Added a synchronous telemetry-span helper and exposed span-name constants for telemetry consumers.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Mar 8, 2026

Warning

Rate limit exceeded

@mk3008 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 25 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b175ade1-d96c-41da-a97d-28f571469e00

📥 Commits

Reviewing files that changed from the base of the PR and between e7a1457 and d8dbbbf.

📒 Files selected for processing (3)
  • .github/workflows/ci.yml
  • .github/workflows/pr-check.yml
  • packages/ztd-cli/src/commands/modelGen.ts
📝 Walkthrough

Walkthrough

Instruments ztd-cli commands (query uses, model-gen, ddl diff) with phase-level telemetry spans, adds a synchronous span helper, exports span-name constants, restructures some flows to propagate resolved context, and adds tests validating emitted span lifecycles and attributes.

Changes

Cohort / File(s) Summary
Telemetry infra
packages/ztd-cli/src/utils/telemetry.ts
Adds withSpanSync(name, fn, attrs) to create synchronous child spans, manage span stack, record exceptions/status; existing withSpan unchanged.
DDL diff command
packages/ztd-cli/src/commands/diff.ts
Wraps local DDL collection, remote pull, diff computation, and emission in telemetry spans; adds/exports DDL_DIFF_SPAN_NAMES; returns plan with hasChanges and patch and records local file counts in span context.
Model-gen command
packages/ztd-cli/src/commands/modelGen.ts
Adds telemetry spans around resolveInputs, placeholderScan, probeClientConnect, probeQueryColumns, typeInference, renderOutput, fileEmit; exports MODEL_GEN_SPAN_NAMES; carries a resolved context object across spans and emits probe decision events.
Query uses command
packages/ztd-cli/src/commands/query.ts
Wraps option resolution and output rendering in spans; exports QUERY_USES_COMMAND_SPANS; propagates resolved options/target between spans and moves output I/O into a render span.
Query report building
packages/ztd-cli/src/query/report.ts
Adds QUERY_USES_REPORT_SPANS; restructures build flow to a discovery-first pattern, wraps spec discovery, report build, and impact aggregation in spans; records counts and warnings for telemetry.
Tests
packages/ztd-cli/tests/commandTelemetry.unit.test.ts, packages/ztd-cli/tests/telemetry.unit.test.ts, packages/ztd-cli/tests/queryUses.unit.test.ts
Adds tests verifying span emission sequences for query/model-gen/ddl-diff via CLI, tests withSpanSync synchronous span lifecycle, and a unit test ensuring query subcommands are registered.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as CLI Command
    participant Telemetry as Telemetry\n(withSpanSync/withSpan)
    participant FS as Filesystem
    participant DB as Remote DB\n(pgDump/probe)

    CLI->>Telemetry: start root span (command)
    CLI->>Telemetry: withSpanSync collect-local-ddl
    Telemetry->>FS: discover SQL files
    FS-->>Telemetry: file list, counts
    CLI->>Telemetry: withSpanSync pull-remote-ddl
    Telemetry->>DB: run pg_dump / probe
    DB-->>Telemetry: remote DDL
    CLI->>Telemetry: withSpanSync compute-diff-plan
    Telemetry->>Telemetry: detect changes, build patch/header
    CLI->>Telemetry: withSpanSync emit-diff-plan
    Telemetry->>FS: write patch file / stdout
    FS-->>Telemetry: write result
    Telemetry-->>CLI: end root span (ok/error)
Loading
sequenceDiagram
    participant CLI as Model-Gen Command
    participant Telemetry as Telemetry\n(withSpanSync/withSpan)
    participant FS as Filesystem
    participant DB as Probe Client

    CLI->>Telemetry: start root span (model-gen)
    CLI->>Telemetry: withSpanSync resolve-model-gen-inputs
    Telemetry->>FS: validate paths, scan placeholders
    CLI->>Telemetry: withSpanSync probe-client-connect
    Telemetry->>DB: open probe client
    CLI->>Telemetry: withSpanSync probe-query-columns
    Telemetry->>DB: execute probe queries
    CLI->>Telemetry: withSpanSync type-inference
    Telemetry->>Telemetry: infer types, render output
    CLI->>Telemetry: withSpanSync file-emit
    Telemetry->>FS: write generated file
    Telemetry-->>CLI: end root span (ok/error)
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

Poem

🐰 I hopped through spans both wide and small,
Tracing queries, models, diffs — I saw it all.
Files and probes, each phase in line,
Telemetry footprints, tidy and fine.
🥕 Hooray for traces — carrots on time!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title clearly describes the main change: adding telemetry spans for ztd-cli command phases.
Linked Issues check ✅ Passed The PR successfully implements all requirements from issue #518: adds phase spans to query uses, model-gen, and ddl diff commands; exports stable span names as constants; and records exceptions with proper status.
Out of Scope Changes check ✅ Passed All changes are directly related to implementing telemetry spans for the three target commands. No unrelated modifications to other functionality detected.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch codex/issue-518-command-spans

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
packages/ztd-cli/tests/telemetry.unit.test.ts (1)

71-92: LGTM!

The test validates the core synchronous span lifecycle:

  1. Span-start emission with attributes
  2. Correct return value from the wrapped function
  3. Span-end emission with 'ok' status

Consider adding an error-path test for withSpanSync similar to the async test at lines 52-55, verifying that exceptions are recorded and the span ends with 'error' status.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/ztd-cli/tests/telemetry.unit.test.ts` around lines 71 - 92, Add a
new unit test mirroring the async error-path to verify withSpanSync records
exceptions: create a test that enables telemetry (setTelemetryEnabled(true);
configureTelemetry(); beginCommandSpan('ddl diff')), call
withSpanSync('compute-diff-plan', () => { throw new Error('boom'); }, {
localFileCount: 2 }) inside an expect(() => ...).toThrow(), and assert the
captured stderr JSON payloads include a span-start for 'compute-diff-plan' with
the attributes and a span-end for 'compute-diff-plan' with status 'error' (and
optionally error details); reference withSpanSync, beginCommandSpan,
setTelemetryEnabled, configureTelemetry, and finishCommandSpan when adding the
assertions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/ztd-cli/tests/telemetry.unit.test.ts`:
- Around line 71-92: Add a new unit test mirroring the async error-path to
verify withSpanSync records exceptions: create a test that enables telemetry
(setTelemetryEnabled(true); configureTelemetry(); beginCommandSpan('ddl diff')),
call withSpanSync('compute-diff-plan', () => { throw new Error('boom'); }, {
localFileCount: 2 }) inside an expect(() => ...).toThrow(), and assert the
captured stderr JSON payloads include a span-start for 'compute-diff-plan' with
the attributes and a span-end for 'compute-diff-plan' with status 'error' (and
optionally error details); reference withSpanSync, beginCommandSpan,
setTelemetryEnabled, configureTelemetry, and finishCommandSpan when adding the
assertions.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e4610f48-b066-4cc6-a636-771ec832df59

📥 Commits

Reviewing files that changed from the base of the PR and between 0f03d91 and 5f9b684.

📒 Files selected for processing (7)
  • packages/ztd-cli/src/commands/diff.ts
  • packages/ztd-cli/src/commands/modelGen.ts
  • packages/ztd-cli/src/commands/query.ts
  • packages/ztd-cli/src/query/report.ts
  • packages/ztd-cli/src/utils/telemetry.ts
  • packages/ztd-cli/tests/commandTelemetry.unit.test.ts
  • packages/ztd-cli/tests/telemetry.unit.test.ts

@mk3008 mk3008 force-pushed the codex/issue-518-command-spans branch from 5f9b684 to 85bced6 Compare March 8, 2026 02:30
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
packages/ztd-cli/src/commands/query.ts (1)

131-135: Minor formatting: comment and function declaration on same line.

The JSDoc comment ending on line 134 and the function declaration starting on the same line 135 creates an unusual formatting pattern. Consider separating them for readability.

🔧 Suggested formatting fix
-/**
- * Keep outline/graph aligned with the existing query surface from main.
- * Telemetry instrumentation in this file is intentionally limited to query uses so conflict resolution
- * does not regress the established outline/graph commands while issue `#518` focuses on the uses workflow.
- */function runQueryUsesCommand(kind: 'table' | 'column', target: string | undefined, options: QueryUsesOptions): void {
+/**
+ * Keep outline/graph aligned with the existing query surface from main.
+ * Telemetry instrumentation in this file is intentionally limited to query uses so conflict resolution
+ * does not regress the established outline/graph commands while issue `#518` focuses on the uses workflow.
+ */
+function runQueryUsesCommand(kind: 'table' | 'column', target: string | undefined, options: QueryUsesOptions): void {
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/ztd-cli/src/commands/query.ts` around lines 131 - 135, The JSDoc
block is currently merged with the function declaration on the same line;
separate the comment and the function signature so the JSDoc ending (the comment
that documents the query uses behavior) sits on its own line(s) and the function
declaration runQueryUsesCommand(kind: 'table' | 'column', target: string |
undefined, options: QueryUsesOptions): void starts on the next line for proper
formatting and readability — update the placement so the /** ... */ block is
immediately above and not trailing into the function line.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/ztd-cli/src/commands/query.ts`:
- Around line 131-135: The JSDoc block is currently merged with the function
declaration on the same line; separate the comment and the function signature so
the JSDoc ending (the comment that documents the query uses behavior) sits on
its own line(s) and the function declaration runQueryUsesCommand(kind: 'table' |
'column', target: string | undefined, options: QueryUsesOptions): void starts on
the next line for proper formatting and readability — update the placement so
the /** ... */ block is immediately above and not trailing into the function
line.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a8e7c8b2-285c-43e6-9a7f-1e3da56e6e98

📥 Commits

Reviewing files that changed from the base of the PR and between 5f9b684 and 80de364.

📒 Files selected for processing (8)
  • packages/ztd-cli/src/commands/diff.ts
  • packages/ztd-cli/src/commands/modelGen.ts
  • packages/ztd-cli/src/commands/query.ts
  • packages/ztd-cli/src/query/report.ts
  • packages/ztd-cli/src/utils/telemetry.ts
  • packages/ztd-cli/tests/commandTelemetry.unit.test.ts
  • packages/ztd-cli/tests/queryUses.unit.test.ts
  • packages/ztd-cli/tests/telemetry.unit.test.ts
🚧 Files skipped from review as they are similar to previous changes (2)
  • packages/ztd-cli/src/utils/telemetry.ts
  • packages/ztd-cli/tests/commandTelemetry.unit.test.ts

@mk3008
Copy link
Copy Markdown
Owner Author

mk3008 commented Mar 8, 2026

If all GithubActions are successful, merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Instrument high-value commands with OpenTelemetry spans

1 participant