feat(instrument): per-instance log messages via message = dynamic

[chet]

Event's log message has been a single static string. message = dynamic lets an event pick its message per instance: declare it instead of a literal message, implement the new DynamicMessage trait, and the derive routes Event::message() through it, typically a match on a #[label] enum. Level and message stay independent axes.

That lets an event that today keeps a separate tracing:: line per outcome (purely to preserve per-variant wording) fold that line into the emit(), so the metric and its message are one declaration.

• DynamicMessage trait plus the message = dynamic value; a message that is neither a string literal nor dynamic is a compile error.
• The check-metric-docs gate learns the ident form, so a metric-backed event can use message = dynamic without tripping the catalogue parser.

Guide docs are in a separate PR (#3707).

Part of the instrumentation-coherency initiative (#3169). Enables the folded metric+log form for outcome-enum events like the /metrics scrape-failure meta-metric (#3546, contributor PR #3686).

[coderabbitai]

Walkthrough

The event derive macro now supports static, dynamic, and absent messages. A public DynamicMessage trait supplies per-instance text, while metric documentation parsing accepts message = dynamic and tests cover runtime selection, validation, and collection.

Changes

Dynamic event messages

Layer / File(s)	Summary
Message specification and generated dispatch crates/instrument-macros/src/lib.rs	The derive macro represents absent, static, and dynamic messages, validates invalid forms, and generates Event::message() accordingly.
Runtime trait and event behavior crates/instrument/src/lib.rs	A public DynamicMessage trait is added, with tests verifying per-instance message selection independently from dynamic log-level selection.
Metric attribute collection crates/xtask/src/metric_docs.rs	Metric parsing accepts string literals and dynamic, with coverage confirming dynamic-message events are collected using their metric name.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant EventDeclaration as Event declaration
  participant EventDerive as Event derive macro
  participant GeneratedEvent as Generated Event
  participant DynamicMessage as DynamicMessage implementation
  EventDeclaration->>EventDerive: declare message = dynamic
  EventDerive->>GeneratedEvent: generate Event::message()
  GeneratedEvent->>DynamicMessage: call message()
  DynamicMessage-->>GeneratedEvent: return per-instance message

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately captures the main change: per-instance log messages via message = dynamic.
Description check	✅ Passed	The description is clearly related to the implemented dynamic message API, derive behavior, and metric-docs parsing changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[chet]

@coderabbitai full_review

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pull-request-3705.docs.buildwithfern.com/infra-controller

[coderabbitai]

@chet, I’ll perform a complete review of the pull request, including the dynamic-message API, derive behavior, documentation, and metric-doc validation changes.

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

crates/instrument/src/lib.rs (1)

574-596: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use one table for outcome-to-message and outcome-to-level expectations.

The test maps the same input enum to two outputs; table-driven cases keep variant coverage and expectations together.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/instrument/src/lib.rs` around lines 574 - 596, Refactor
dynamic_message_selects_wording_per_variant to use one table-driven set of cases
containing each Outcome variant, its expected message, and its expected LogAt
value. Iterate over the table and perform both Event::message and Event::log_at
assertions per case, keeping coverage and expectations together.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/xtask/src/metric_docs.rs`:
- Around line 255-264: Update the message attribute parsing branch in the metric
documentation gate to accept string literals or only the identifier dynamic;
reject any other identifier with a parse error, matching the validation in the
instrument macro implementation. Add a negative parser test covering message =
bogus.

---

Nitpick comments:
In `@crates/instrument/src/lib.rs`:
- Around line 574-596: Refactor dynamic_message_selects_wording_per_variant to
use one table-driven set of cases containing each Outcome variant, its expected
message, and its expected LogAt value. Iterate over the table and perform both
Event::message and Event::log_at assertions per case, keeping coverage and
expectations together.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 095f6cf0-a1ef-4b0a-87b3-171228140314

📥 Commits

Reviewing files that changed from the base of the PR and between d538254 and f9b53d5.

📒 Files selected for processing (4)

• crates/instrument-macros/src/lib.rs
• crates/instrument/src/lib.rs
• crates/xtask/src/metric_docs.rs
• docs/observability/instrumentation.md