feat!: remove `TraceId` and `telemetry` thread-local state #67

Nemo157 · 2025-10-10T14:11:12Z

See the individual commit descriptions for full context.

Overall this is removing the traces + root spans from the telemetry protocol, and moving the resolution of "implicit parents" to the consumer side rather than the producer. To allow the consumer to correctly track what is the implicit parent for events the execution id now needs to mix-in a thread-id. By having just this one id (which is queried via the OSAL) as part of the output data we avoid needing any other thread-local state within the producer so we can use it on systems that don't provide any.

This involves breaking changes to both the veecle-telemetry crate API and the JSON encoding.

Closes: DEV-911, DEV-913

github-actions · 2025-10-10T14:18:13Z

Deployment - Branch link	Commit link - `7b7033a`
user-manual preview	https://84da2528.user-manual-2bd.pages.dev
private-docs preview	https://b94b4ca6.private-docs-3bh.pages.dev
veecle-telemetry-ui preview	https://643679f0.veecle-telemetry-ui.pages.dev

claude · 2025-10-10T14:30:48Z

Change Summary

This PR removes the TraceId concept and thread-local state from the telemetry system. The SpanContext now uses ProcessId directly for span identification. The execution ID has been changed to include both a process ID and thread ID to uniquely identify thread/task combinations, allowing the consumer to track implicit parent spans without requiring thread-local state on the producer side. This enables telemetry on systems without thread-local storage support.

The changes include breaking API changes to the veecle-telemetry crate and modifications to the JSON encoding format. All examples and runtime code have been updated to use the new ProcessId instead of ExecutionId when setting exporters.

Issues Found

🟡 Style Guide - Inconsistent Formatting in ProcessId::Display

The Display implementation for ProcessId (veecle-telemetry/src/id.rs:48) uses a format string that may not produce consistent output across all values.

Location: veecle-telemetry/src/id.rs:48

Current code:

write!(f, "{:016x}", self.0)

Issue: A ProcessId is a u128 but the format string only shows 16 hex digits (which represents 64 bits). This will truncate values larger than u64::MAX.

Expected: The format string should use 32 hex digits to fully represent the 128-bit value:

write!(f, "{:032x}", self.0)

This is consistent with the serialization implementation which correctly uses all 16 bytes (32 hex chars) of the u128.

veecle-telemetry/src/id.rs

codecov · 2025-10-10T14:35:53Z

Codecov Report

❌ Patch coverage is 70.26316% with 113 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
veecle-telemetry-ui/src/store/mod.rs	0.00%	57 Missing ⚠️
veecle-telemetry/src/id.rs	77.03%	25 Missing and 6 partials ⚠️
veecle-telemetry/src/protocol.rs	60.31%	20 Missing and 5 partials ⚠️

📢 Thoughts on this report? Let us know!

ForsakenHarmony · 2025-10-13T09:43:08Z

veecle-os-runtime/src/datastore/slot/slot.rs

-        self.borrow_mut().take()
+    pub(crate) fn take(
+        &self,
+        #[cfg(feature = "veecle-telemetry")] span_context: Option<SpanContext>,


This is very unfortunate, but unavoidable I suppose

TBH I would get rid of the feature and just always have this code, since it's supposed to be zero-cost without veecle-telemetry/enable. But that's separate from these changes.

I was talking about passing down the SpanContext, I'd really prefer a solution where this isn't necessary (thread locals and alternatives on no_std) because it makes some things very awkward, but I guess this is what we decided on doing

ForsakenHarmony · 2025-10-13T09:45:57Z

veecle-telemetry/tests/lib.rs

            root []
                + attr: runtime_attr="added_later"
-                + link: trace=123456789abcdef0, span=fedcba9876543210
+                + link: span=fedcba9876543210


this should be printing the process id now?

veecle-osal-api/src/thread.rs

veecle-telemetry/src/protocol.rs

veecle-telemetry/tests/lib.rs

veecle-telemetry/src/protocol.rs

veecle-telemetry/src/collector/mod.rs

veecle-telemetry/src/id.rs

veecle-telemetry/src/protocol.rs

ForsakenHarmony · 2025-10-15T13:41:12Z

veecle-telemetry/src/id.rs

-/// An identifier for a trace, which groups a set of related spans together.
-#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
-pub struct TraceId(pub u128);
+/// A globally-unique id identifying a process.


Not a big fan of the name because it only really fits on std?

ExecutionId kinda was the general name for this "an execution of code happening somewhere"

But I guess if it's just this name it shouldn't block the PR

This was supposed to be on ProcessId

Do we even need it or can we just add ThreadId to the InstanceMessage?

A span can be entered+exited from many threads on the same process (e.g. if it's part of a future that gets stolen within a multi-threaded tokio executor).

I know, I'd just like to not have both ExecutionId and ProcessId, so I'm thinking we can probably remove ProcessId again and put ThreadId next to ExecutionId where necessary

I think it's much easier to think about the context-tracking in the UI when you have a name for the "thread of execution", instead of having a HashMap<(ProcessId, ThreadId), _>, and I felt ExecutionId fit that better than it did the process.

One other option would be to not name the integer for the threads, and have

struct ThreadId { process: ProcessId, thread: u64, }

to only need to come up with two names.

I guess thinking about it ThreadId also doesn't make sense on no_std targets

I guess nesting ExecutionId inside whatever we want to call ThreadId would always make it globally unique as well which might be nice

Trying to pin it down, the two things we're identifying are:

the global memory space

the call stack

These don't really give great names, so personally I think using the standard OS names for these works fine. They're probably instantly understandable to most devs and are easy to map to other systems (freertos process=reset thread=task)

Do you think that having this separate together is needed?
Why don't we split into nibbles? high nibble process id and lower one thread id?
So it is still a newtype but can be carried anywhere. I am not sure it can be more than 2^32 thread id can happen for a single process.

This has been moved to #90

The collector is now initialized with a process id and automatically combines this with a per-thread id from the OSAL to create a globally unique id for the current thread/task. Closes: DEV-913 Signed-off-by: Wim Looman <[email protected]>

…ntification Remove the `TraceId` concept and use `ProcessId` directly to identify the context within which `SpanId`s are unique. Previously, `TraceId` was generated from `ProcessId` using a counter, but this added complexity without clear benefit and requires thread local state. `SpanId`s are now unique within a process, and the combination of `ProcessId` + `SpanId` provides global uniqueness through `SpanContext`. Signed-off-by: Wim Looman <[email protected]>

Remove the thread-local `CURRENT_SPAN` tracking and `SpanContext::current` method. Span context is now determined by execution id (process + thread) rather than explicit parent-child span relationships. This simplifies the telemetry model by eliminating implicit state within the process. Span messages are correlated through their execution id, which provides sufficient context for external tools to reconstruct the span relationships. Closes: DEV-911 Signed-off-by: Wim Looman <[email protected]>

Add custom `Display`, `FromStr`, `Serialize`, and `Deserialize` implementations for `ProcessId`, `ThreadId`, `ExecutionId`, and `SpanContext` types. These provide a consistent hex-encoded string format with colon separators for composite IDs (`process:thread` for `ExecutionId`, `process:span` for `SpanContext`). This makes telemetry ids more readable and provides a unified format for logging and serialization. Signed-off-by: Wim Looman <[email protected]>

Nemo157 force-pushed the wim/push-pxywosxxsluy branch from 11a89b2 to 739c5f9 Compare October 10, 2025 14:21

Nemo157 marked this pull request as ready for review October 10, 2025 14:29

Nemo157 requested review from ForsakenHarmony and arctic-alpaca as code owners October 10, 2025 14:29

claude bot reviewed Oct 10, 2025

View reviewed changes

veecle-telemetry/src/id.rs Outdated Show resolved Hide resolved

Nemo157 force-pushed the wim/push-pxywosxxsluy branch from 739c5f9 to 4341f4e Compare October 10, 2025 14:36

ForsakenHarmony reviewed Oct 13, 2025

View reviewed changes

Nemo157 force-pushed the wim/push-pxywosxxsluy branch 2 times, most recently from 8175512 to af394c0 Compare October 13, 2025 10:54

arctic-alpaca reviewed Oct 14, 2025

View reviewed changes

veecle-osal-api/src/thread.rs Show resolved Hide resolved

arctic-alpaca reviewed Oct 14, 2025

View reviewed changes

veecle-telemetry/src/protocol.rs Show resolved Hide resolved

Nemo157 force-pushed the wim/push-pxywosxxsluy branch 2 times, most recently from 57070a8 to 8b1b3b3 Compare October 14, 2025 09:49

arctic-alpaca reviewed Oct 14, 2025

View reviewed changes

veecle-telemetry/tests/lib.rs Show resolved Hide resolved

arctic-alpaca reviewed Oct 14, 2025

View reviewed changes

veecle-telemetry/src/protocol.rs Outdated Show resolved Hide resolved

arctic-alpaca reviewed Oct 15, 2025

View reviewed changes

Nemo157 force-pushed the wim/push-pxywosxxsluy branch 2 times, most recently from 88f862d to 969a3f1 Compare October 15, 2025 08:53

arctic-alpaca approved these changes Oct 15, 2025

View reviewed changes

ForsakenHarmony reviewed Oct 15, 2025

View reviewed changes

arctic-alpaca mentioned this pull request Oct 20, 2025

chore: block dependabot embedded-io-* updates #77

Merged

Nemo157 mentioned this pull request Oct 20, 2025

test(telemetry): verify output structure in trailing comma test #82

Merged

Nemo157 force-pushed the wim/push-pxywosxxsluy branch from 969a3f1 to 85148d1 Compare October 20, 2025 14:52

Nemo157 marked this pull request as draft October 20, 2025 15:21

Nemo157 mentioned this pull request Oct 21, 2025

feat(telemetry)!: replace execution id with thread id #90

Open

arctic-alpaca mentioned this pull request Oct 22, 2025

refactor!: use NonZeroU64 for thread id #96

Merged

Nemo157 force-pushed the wim/push-pxywosxxsluy branch from 85148d1 to 52aadd1 Compare October 22, 2025 12:33

Nemo157 added 4 commits October 23, 2025 11:32

Nemo157 force-pushed the wim/push-pxywosxxsluy branch from 52aadd1 to d2ab38d Compare October 23, 2025 09:33

Nemo157 closed this Oct 23, 2025

Nemo157 deleted the wim/push-pxywosxxsluy branch October 23, 2025 09:42

Uh oh!

feat!: remove TraceId and telemetry thread-local state #67

feat!: remove TraceId and telemetry thread-local state #67

Uh oh!

Conversation

Nemo157 commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Oct 10, 2025

Change Summary

Issues Found

🟡 Style Guide - Inconsistent Formatting in ProcessId::Display

Uh oh!

Uh oh!

codecov bot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ForsakenHarmony Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nemo157 Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

feat!: remove `TraceId` and `telemetry` thread-local state #67

feat!: remove `TraceId` and `telemetry` thread-local state #67

Nemo157 commented Oct 10, 2025 •

edited

Loading

github-actions bot commented Oct 10, 2025 •

edited

Loading

codecov bot commented Oct 10, 2025 •

edited

Loading

ForsakenHarmony Oct 15, 2025 •

edited

Loading

Nemo157 Oct 15, 2025 •

edited

Loading