feat: introduce the observed_utils crate

[Evgenii (Vaiz)]

Move the OpenTelemetry helper crate from the internal repo into this repository, following observed, observed_macros and observed_testing. It is the optional companion for consumers that export typed events to OpenTelemetry.

The crate is named observed_utils and starts at version 0.1.0. It ships internally as observed_helpers at 0.24.0; both were changed on review here, while nothing is published and the change is therefore free.

observed itself no longer depends on opentelemetry, so an exporter has to convert values on its own. That conversion lives here once rather than being re-derived in every exporter: any_value_of, otel_value_of and otel_severity_of. The crate also carries format_any_value, which renders an AnyValue in human-readable form instead of its Debug shape, and SensitiveSlice, a bounded, type-erased collection of RedactedDisplay references that renders without allocating.

Changes made during the move:

• any_value_of and otel_value_of handle Value::U64. The variant was added in 0.24 after this crate was written, so a u64 dimension used to fall through to the #[non_exhaustive] guard arm and be exported as a debug string. Values past i64::MAX still export as a decimal string, because neither AnyValue nor opentelemetry::Value has an unsigned variant.
• metric_number_of returns to this crate. It was parked in observed_testing because that was its only consumer here; observed_testing now uses it from this crate instead of keeping a second copy.
• The example uses the #[path = "support/taxonomy.rs"] stand-in taxonomy the observed examples use, instead of the ox-sdk-only microsoft_enterprise_data_taxonomy crate, and expect with a message instead of unwrap, to satisfy this workspace's clippy::unwrap_used policy.
• The #![doc(html_logo_url)] and #![cfg_attr(coverage_nightly, ...)] attributes are enabled, matching the convention of the other crates here.
• arrayvec and const-hex are added to [workspace.dependencies].

Effects:

• A crate that emits typed events and exports them no longer has to write its own Value mapping, and the mapping is governed by this repository's gates.
• observed_testing gains a dependency on observed_utils; the two copies of metric_number_of can no longer drift apart.
• Telemetry helper changes no longer need a manual transfer between two repositories.
• The crate name and version now differ from the internal copy until the follow-up PR removes it there.

---

Review changes

Rename and version (review request)

observed_helpers becomes observed_utils, and the version becomes 0.1.0 instead of inheriting observed's 0.24.0. Renamed in place: the directory, the package name, the repository and doc-URL attributes, both observed_testing call sites and its dependency entry, the [workspace.dependencies] entry, two prose references under crates/observed, and the lockfile. Git records every file as a rename, so the move carries no content change. The README is regenerated by cargo-doc2readme rather than hand-edited.

Correctness: an unreachable overflow probe removed

SensitiveSlice::new ended with a post-loop iter.next() used to detect overflow. It cannot be reached: a for loop exits normally only after next() returned None, so the extra call could report Some only for an iterator that resumes after None, which the Iterator contract leaves unspecified. The loop already detects overflow on its own, because is_full() is checked before the push, so the N+1-th item is pulled, observed and discarded.

The gates could not have caught this: the line executed on every non-overflowing call, so it counted as covered, and is_some() was simply always false.

Bytes render without allocating (review request)

format_any_value's Bytes arm used const_hex::encode, which returns an owned String. It now uses const_hex::display, a Display adapter that writes through const-hex's own encoder straight into the formatter, so every arm writes directly and rendering allocates nothing.

display is not gated behind const-hex's alloc feature and encode was the only user of it, so the feature is dropped. const-hex enables proptest through alloc, and nothing else in the workspace pulled it in, so proptest, rand_xorshift and unarray leave Cargo.lock too.

Other review fixes

• Spellcheck: implementors becomes implementers and the British signalled becomes signaled. Two genuinely new technical words introduced by the module docs, recursing and redactable, were added to .spelling.
• External types: the approved-type list names opentelemetry::logs::record::Severity, the canonical path cargo-check-external-types reports, instead of the re-export path.
• Docs: the example's module doc said SensitiveCollection, a type that does not exist; examples/support/taxonomy.rs claimed to be shared by the observed crate's examples, and now describes this crate's copy and why the copy exists; format_any_value.rs and sensitive_slice.rs gained //! headers, matching otel.rs.
• Tests: added for the paths nothing reached - AnyValue::Map rendering, metric_number_of on Value::U64, otel_value_of on Bool / F64 / BoolArray / F64Array, Text::Shared, and the Debug and Clone impls of SensitiveSlice.

Deliberate decision: the #[non_exhaustive] guard arms stay

The only lines no test reaches are the wildcard arms guarding the foreign #[non_exhaustive] enums observed::Value, observed::Text and opentelemetry::logs::AnyValue. All variants that exist today are matched explicitly, so those arms are unreachable and cannot be covered by a test. They are kept on purpose: they are what makes a variant added upstream degrade to a readable debug form instead of failing to compile or silently dropping data.

Rather than delete them for the 100 % line-coverage gate, the four dispatch functions carry #[cfg_attr(coverage_nightly, coverage(off))] with a comment stating exactly what the exclusion covers - including that the inline scalar and Bytes arms are excluded too, and are pinned by tests and mutation testing rather than by the gate. The work they delegate to (unsigned_any_value, unsigned_otel_value, list_of, write_list / write_map) stays measured.

cargo-deny: h2 advisory fixed, stale ignores removed

anvil-deny failed on the advisory "h2 unbounded empty DATA frames" against h2 0.4.15, which this repository carries transitively. The advisory predates this branch, but the fix is a one-line lockfile bump, so it is included: h2 moves to the patched 0.4.16. Only the h2 entry is touched - a full cargo update h2 also re-resolved unrelated windows-sys edges downwards.

Two ignores that no longer match any crate were removed from deny.toml: RUSTSEC-2025-0141 (bincode, no longer in the lockfile at all) and RUSTSEC-2026-0173 (proc-macro-error2, still present but no longer matched). The quick-xml ignores stay, because quick-xml 0.39.4 is still pulled in through the Azure SDK. cargo deny check all now reports advisories, bans, licenses and sources ok with no advisory-not-detected warnings.

Verification

On the renamed crate: tests, clippy -D warnings, doc, both rustfmt configs, doc2readme --check, spellcheck, cargo-sort, cargo-machete and cargo deny check all are clean; coverage is 100 % with no uncovered lines; cargo mutants over the package reports no surviving mutants.

Second review round: public documentation corrected

Three claims in the public documentation were not supported by the implementation as written. All three are fixed as documentation; no behaviour changed.

• The u64 threshold is now public. any_value_of and otel_value_of described their result as the value's OpenTelemetry counterpart, but a Value::U64 has no single output type: up to i64::MAX it becomes the integer variant, past it a decimal string. That boundary was documented only on the private helpers, which never reach rustdoc. It is now on both public functions and in the crate overview. The policy itself is unchanged - neither destination enum has an unsigned variant, so the alternatives are wrapping into a negative number or dropping the value.
• SensitiveSlice's capacity has a lower bound. N was documented only as the maximum number of stored items, while new asserts N > 0 at compile time. The type parameter and the constructor now state it.
• SensitiveSlice's guarantees are scoped to what the wrapper controls. The module said items are "never rendered in the clear by this module" and the crate said rendering happens "without allocating". Rendering is delegated to each item's own RedactedDisplay implementation under the caller's Redactor, which is permitted to pass values through, and an item may allocate. The wording now promises inline storage of the collection and names the delegation instead.

Declined in this PR: changing metric_number_of to preserve the numeric kind, or returning it to observed_testing. The precision analysis is correct and is already acknowledged by the cast_precision_loss expectations at both call sites, but a new numeric contract is a redesign of a helper this PR only moves, and returning it to observed_testing reverses the de-duplication that is part of the move. Follow-up material, together with the adjacent-u64 boundary test suggested in review.

Third review round: the Sync bound is documented

SensitiveSlice was documented as storing &dyn RedactedDisplay fat pointers, and new as accepting implementers of RedactedDisplay. The stored type is actually &(dyn RedactedDisplay + Sync) and the constructor requires T: RedactedDisplay + Sync, so a caller with a non-Sync item type satisfied the documented bound and still failed to compile.

The bound is documented rather than removed. &(dyn Trait + Sync) is itself Send and Sync while a bare &dyn Trait is neither, so the bound is what lets an event struct holding a SensitiveSlice cross threads; dropping it would narrow where the type can be used. Documentation only, and the generated README is unaffected because these docs live on the type rather than in lib.rs.

---

Rebase note (2026-08-19): rebased onto main after it advanced; the branch had gone into a conflicting state. The only conflict was in Cargo.lock, where upstream's new arty_executor package entry landed in the same alphabetical slot as this branch's arrayvec entry. Both were kept, in alphabetical order; cargo metadata --locked accepts the merged lockfile. No source change.

[github-actions]

✅ Version increments look sufficient

cargo semver-checks compared the 1 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
observed_utils	new crate	—	0.1.0	0.1.0	✅ ok

This check is informational and does not block the merge.

View the check run

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (a6ca774) to head (3763be2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #677   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         554      557    +3     
  Lines       61509    61583   +74     
=======================================
+ Hits        61509    61583   +74     

Flag	Coverage Δ
linux	69.2% <100.0%> (?)
linux-arm	68.5% <100.0%> (?)
windows	69.2% <100.0%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Introduces a new observed_utils crate that centralizes OpenTelemetry conversion helpers and related utilities for observed ecosystem consumers, and wires it into the workspace (including observed_testing) while cleaning up cargo-deny advisory configuration.

Changes:

• Added the new crates/observed_utils crate (OTel conversions, SensitiveSlice, format_any_value, metric_number_of, examples/tests/docs scaffolding).
• Updated workspace and downstream crates to depend on and reference observed_utils (replacing prior observed_helpers/local copies).
• Refreshed dependency/advisory state (lockfile bump for h2, removed stale deny.toml ignores, added .spelling entries).

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
deny.toml	Removes stale advisory ignore entries.
crates/observed/FEATURES.md	Updates documentation reference to observed_utils::metric_number_of.
crates/observed/examples/support/otel.rs	Updates doc comments to reference observed_utils conversions.
crates/observed_utils/src/sensitive_slice.rs	Adds SensitiveSlice implementation plus unit tests.
crates/observed_utils/src/otel.rs	Adds Value/Text/Severity → OpenTelemetry conversion helpers plus tests.
crates/observed_utils/src/metric_number.rs	Provides metric_number_of (including Value::U64) plus tests.
crates/observed_utils/src/lib.rs	New crate root, docs, lint config, and public re-exports.
crates/observed_utils/src/format_any_value.rs	Adds format_any_value Display adapter for AnyValue plus tests.
crates/observed_utils/README.md	Generated crate README for crates.io/docs.rs.
crates/observed_utils/logo.png	Adds crate logo asset (Git LFS pointer).
crates/observed_utils/favicon.ico	Adds crate favicon asset (Git LFS pointer).
crates/observed_utils/examples/support/taxonomy.rs	Example-only taxonomy support module for classification/redaction demos.
crates/observed_utils/examples/sensitive_collection.rs	Example demonstrating SensitiveSlice usage in events and processors.
crates/observed_utils/CHANGELOG.md	Adds initial changelog for the new crate.
crates/observed_utils/Cargo.toml	Defines the new package metadata and dependencies (workspace-inherited).
crates/observed_testing/tests/derive_enrichment.rs	Switches metric extraction call site to observed_utils::metric_number_of.
crates/observed_testing/tests/coverage_dyn_sink.rs	Switches metric extraction call sites to observed_utils::metric_number_of.
crates/observed_testing/src/mock_processor.rs	Switches internal metric extraction to observed_utils::metric_number_of.
crates/observed_testing/src/lib.rs	Removes local metric_number module export now sourced from observed_utils.
crates/observed_testing/Cargo.toml	Adds observed_utils dependency.
Cargo.toml	Adds workspace dependency entries for arrayvec, const-hex, and observed_utils.
Cargo.lock	Bumps h2 and adds new dependency resolutions for the new crate and deps.
.spelling	Adds new terms used by the moved/added docs.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated no new comments.

[martin-kolinek]

Is there a document or diagram somewhere that explains the intended end state of crates and dependencies in the observed space? Who is supposed to depend on observed_utils? I would really like to prevent having applications have to depend on something called "observed_utils" - for me, a utils crate is something that should generally be buried in the dependency tree.

[Evgenii (Vaiz)]

generally speaking, I put here all common functionality that often is required by observed users, but doesn't have place in observed crate itself due to increased risk of breaking changes

[Evgenii (Vaiz)]

I expected that certain percent of crates using observed, also use observed_util instead of reimplementing similar functionality

[Sander Saares (sandersaares)]

If this is "ordinary" functionality, it sounds like we should stabilize it, so it could go in main crate. For "ultra-stable" things, maybe the "re-export critical types from observed_core that you never touch" pattern helps avoid accidental breakage? Just speaking in generalizations, I guess it is not something that has a universal pattern we have worked out so far but in general if we expect most users to use a _utils crate it stops having value on its own IMO and might as well get merged into the top-level crate. But probably any detailed analysis needs to be case by case - I know little about observed structure and what is needed by which users. Maybe opportunity for design discussion at future arch meeting?

[Evgenii (Vaiz)]

I would call it experimental. Let's see what people actually use, and where to put it. Right now it solves the problem of reinventing the wheel, and it's good enough for me.

for example, I also plan to add info! shortcut here that defines event struct inline, so you don't need to declare a separate struct for simple events.

[Sander Saares (sandersaares)]

[Copilot speaking]

Published 4 findings. No finding follows up on an existing discussion thread.

See diagnostics

Diagnostic	Value
Cache	Miss

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated no new comments.

Suppressed comments (2)

crates/observed_utils/src/sensitive_slice.rs:82

• The constructor requires T: RedactedDisplay + Sync, but the doc comment only mentions RedactedDisplay. Please document the Sync requirement explicitly so callers aren't surprised by the additional bound.

    /// Collects items from any iterator of references to [`RedactedDisplay`]
    /// implementers.

crates/observed_utils/src/sensitive_slice.rs:22

• The docs say this stores &dyn RedactedDisplay fat pointers, but the actual stored type is &(dyn RedactedDisplay + Sync). This Sync bound is part of the public contract and should be documented (or the bound removed if it's not required).

This issue also appears on line 81 of the same file.

/// to `N` `&dyn RedactedDisplay` fat pointers in an inline array. This makes

[Evgenii (Vaiz)]

🤖 Clawpilot here! Posted automatically by Clawpilot (an AI agent), not by a human. Please verify before acting.

Re the two suppressed comments in review #4971552344, both about SensitiveSlice's undocumented Sync bound — accepted, fixed in 8db85fb3.

Both are correct and they are the same gap seen from two angles. The type documentation said it stores &dyn RedactedDisplay fat pointers, and new said it accepts implementers of RedactedDisplay, but the stored type is &(dyn RedactedDisplay + Sync) and the constructor requires T: RedactedDisplay + Sync. A caller with a non-Sync item type therefore satisfied the documented bound and still failed to compile.

Documented on both the type and the constructor rather than removing the bound. The bound is load-bearing: &(dyn Trait + Sync) is itself Send and Sync, while a bare &dyn Trait is neither, so it is what allows an event struct holding a SensitiveSlice to cross threads. Dropping it would narrow where the type can be used, which is a behaviour change to code this PR only relocates.

Documentation only — no behaviour change, and the generated README is unaffected since these docs live on the type rather than in lib.rs.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated no new comments.

[Ralf Biedert (ralfbiedert)]

🤖 This crate combines independently usable OpenTelemetry conversion, metric extraction, formatting, and privacy collection APIs. A SensitiveSlice consumer therefore compiles the OpenTelemetry dependencies, while conversion users compile the privacy stack. Please split the independently usable surfaces (for example, a focused OpenTelemetry crate and a privacy collection crate) or otherwise avoid forcing unrelated dependency sets.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated no new comments.

[Ralf Biedert (ralfbiedert)]

🤖 Requesting changes for the lossy integer-to-float metric conversion. The crate-boundary concern is secondary.

[Ralf Biedert (ralfbiedert)]

🤖 The implementation still converts i64 and u64 to f64; this small-value test misses the boundary where adjacent counters above 2^53 collapse to the same observation. Please preserve the numeric kind until instrument selection and add boundary tests around 2^53.

[Evgenii (Vaiz)]

🤖 Clawpilot here! Posted automatically by Clawpilot (an AI agent), not by a human. Please verify before acting.

This point was already raised and answered on this PR — see #677 (comment) for the reasoning (the numerics are correct and acknowledged by the #[expect(clippy::cast_precision_loss, ...)] at both arms; changing the return type is a redesign of a helper this PR only relocates, so it is follow-up material along with the 2^53 boundary test). Flagging it to the PR owner rather than re-deciding it here.