Agreed this is a bit wordy, althoughto me the suggestion makes it sound like /prod/<pid>/maps is also the mechanism to 'read from target process memory'. I'll try think of something else

Reworded inline. lmk what you think!

I think stringy is definitely too informal here, and the addition of utf-8 bytes makes sense to me. The 'length prefixed' feels a bit overspecified for this bit in the doc, though - it feels like it implies something more than what we have in the field layout section below. Reworded inline - wdyt @christos68k ?

I think either one works... And I have a small suggestion -- perhaps we could include a "hexdump" of a tiny example to clarify how it looks in practice?

We didn't do this for process context since that's mostly protobuf, but folks bootstrapping their own readers could use as a first test to check their parsing.

Clarifying:

Good point! I've rejigged it slightly more as i'm not happy with how we wrote it originally either - will push change shortly - lmk what you think

@florianl @christos68k @felixge @ivoanjo @brancz - as discussed in the prof sig yesterday, here is where we could consider adding add-hoc (i.e. not pre-configured in process context) labels.

Our discussion yesterday, I believe, came to the conclusion we probably shouldnt do this for now because:

• we want to discourage high cardinality keys / churn
• we don't expect that this is likely to serve a common use case
• we want to err on the side of keeping the spec simple and opinionated
• we can always add this later if we see demand

... but let's use this thread for more complete discussion as we need!

For context, relevant meeting notes are on the May 28th, 2026 meeting.

+1 I agree with err'ing on the side of simplicity for now, for the reasons Scott stated, especially as I can see no blockers with this being added in the future as an extension if needed.

Runtimes that cannot efficiently expose context, or runtimes for whom thread-local context is not relevant (e.g. in Go, Goroutine-local context is more interesting, and in Node, we want something that follows async execution, etc.)

This is a great point; there it's more about the unit of execution context being fundamentally different. Let me think about how to word this

Both go and node do end up mapping their own high-level things onto OS threads, so there is a world where they could use this thread-local context as well.

Thus at least for me the distinction is about what we can be implemented efficiently as a library -- it doesn't matter that "theoretically" someone could change go/node directly to update the thread-local context when they swap async execution scopes or goroutines, because we need a solution that works today.

This to say, in terms of wording, I think that's what's interesting to get across?

before the next record begins

...unless we are assuming a 2-byte alignment, in which case there will be an extra padding byte if the entire record has an odd length.

I was discussing this with Scott and I realized I wasn't quite sure I fully understood this suggestion.

Are you suggesting:

1. That the overall "Thread-Local Context Record" should have a total size that is aligned (so that e.g. people don't create one that is "exactly 613 bytes")?
2. That inside attrs-data the key/length/bytes entries should be aligned?
3. (Something else?)

Maybe there's confusion around

before the next record begins.

We're actually talking about the next attribute in attrs-data here, right? And not the next ThreadContextRecord (which needs not exist, needs not be placed after this one, and is not 1-byte aligned indeed). On the other hand, everything in attrs-data are individual bytes or byte arrays, so there's no reason for padding or alignment here.

If so, maybe substituting "record" for "attribute" or at least "attribute record" could dispel the confusion?

I think that's a good idea to disambiguate. Have added:

Inline array of the string value itself. Exactly length bytes appear here, before the next attribute entry begins.

Why is this initial setting to 0 necessary; can't we just set the pointer to the new record once it's done being constructed? Then the reader will see either the old record or the new record, never "no record" (at least in this code path; the mutate-in-place path is different).

I reckon the tradeoff here is whether we want to prefer "some record" over "no record". Said otherwise, at the point we are trying to set a new record, the old record is no longer valid for the thread and we should clear it quickly. Maybe something like:

wdyt @umanwizard ?

We could restrict this a bit; yet I think allowing "no record" does make things easier on the writer. It allows a new webserver request to start by setting a record and to end by clearing it (before a thread goes back to the idle thread pool or similar).

Requiring always an active record would disallow an implementation of this kind. So I'd classify the "be able to go back to no record" as a nice to have, although yes we could make do without it.

I agree that we should not always require an active record. I guess my point is that either approach will work, and which one should be preferred probably depends on the application, so I don't think the OTEP needs to be prescriptive about it.

Ah, yeah, good point -- indeed the text can suggest detaching for in-place updates OR swapping if an "update" is done by creating an entire new record to replace the previous point.

In general I agree without that the spec should not be overly prescriptive and should try to leave space for implementations to do what makes sense for them.

Ok so i've dropped the "Sets the TLS pointer to zero ..." bit, and added a comment below:

If reusing storage that may already be visible to readers, the SDK MAY first set the TLS pointer to NULL to ensure readers see no record during construction.

Thinking about this more, I'm not convinced valid is needed.

If we didn't have the valid field, then when modifying a record in-place, we could simply detach it first, e.g.:

ThreadContextRecord *r = otel_thread_ctx_v1;
otel_thread_ctx_v1 = NULL;
BARRIER;
// do some mutations on r...
BARRIER;
otel_thread_ctx_v1 = r;

AFAICT, this would not be any slower or worse than the current approach of mutating valid, but I might be missing something.

Lifting @ivoanjo 's words out of a slack chat:

What you're saying is correct -- the thinking about having this bit of extra flexibility is that if you're exposing the thread context from C/C++/Rust to another language, if there's a valid field in there you can "just" expose a byte-buffer and allow the high-level language to directly update the context without needing to also somehow teach it how to update the TLS (and expose something like "a raw pointer"). Thus it's a bit of extra redundancy for a bit of extra implementation flexibility for writers -- at least that's how I'd describe it

While we've been PoCing this internally, we found it to be useful for Java in particular where the cost of twiddling the TLS pointer itself is relatively high.

Yeah, this :D

We actually already have some text about this later on in the doc:

A SDK should choose to either set/unset the TLS pointer itself, or the valid flag, but not both.

The intention of this design is to enable flexibility for the writers. We envision that some writers may choose to keep a fixed record for a given thread and can thus mutate it in-place, and that other writers may instead keep the record associated with some other high-level concept (coroutine, request, etc) and swap out the pointer as needed when they become active on any given thread.

We discussed this a bit more in Slack, but it's probably better to take the discussion to a public place. I am still not fully convinced, for two main reasons:

1. First, why is it expensive in Java? Even if the FFI required to access TLS variables in Java is high, it seems to me you could save a pointer to the TLS variable in each Java thread, and access the variable through that pointer, rather than redoing the TLS lookup every time. I don't know Java beyond the basics, so please let me know if I'm making any erroneous assumptions.
2. Even if it is in fact true that the valid flag makes it possible for the Java implementation to be slightly faster, this has other efficiency drawbacks. We have to check the valid flag on every trip through the unwinder (that's only one branch but it's not nothing), whereas any disadvantage on the writing side is only incurred when the label set is actually changed. Furthermore, having this flag makes the struct 2 bytes longer and the ABI more complicated.

I could be convinced that this flag is useful, but I'd be interested in seeing a more concrete example of how it's used from Java and what it would look like from Java if we didn't have the valid flag and only could set/unset the TLS variable to NULL.

Those are good points, let me try to address them ;)

1. First, why is it expensive in Java? Even if the FFI required to access TLS variables in Java is high, it seems to me you could save a pointer to the TLS variable in each Java thread, and access the variable through that pointer, rather than redoing the TLS lookup every time. I don't know Java beyond the basics, so please let me know if I'm making any erroneous assumptions.

Indeed what you're saying it's possible. The way I think about it is:

• You always need to touch the thread-local context record to update it, so if you're exposing it to a high-level language as a byte-buffer ish (e.g. Java, Ruby), you're always going to need to expose that memory location. Exposing a byte-buffer to the high-level language is useful because the JIT can then kick in and make updating the context something you can do in a very optimized way, without needing to jump over the FFI. (In the JVM in specific, calling across the FFI is more expensive than regular Java methods, and these calls cannot be optimized by the JIT)
• Thinking about CPU caches and whatnot, with valid sitting in the middle of the record, it would be pulled into the CPU cache already.
• The context record structure itself has only data and no pointers. So a high-level bit of code that's limited to writing in a sized byte-buffer can't do much damage if there's any bugs.

Removing the valid and forcing the thread-local storage to always be written would mean:

• Two pointers need to be exposed to the high-level code: the TLS and the context record. (Or at least, there would need to be an FFI call to "set TLS to null" && "set it back to the context")
• The TLS pointer is almost for sure in a different memory location from the context, so that's an extra cache miss
• Having the high-level code be able to update a pointer sounds like it might be a bit more error-prone. E.g. what if it sets the pointer to something else that's not a context record?

As part of validating this work, we've implemented the current thread context sharing proposal in Datadog's Java Profiler (used by dd-trace-java, Datadog's Java SDK) in DataDog/java-profiler#347 and it takes advantage of the things I mentioned above:

1. It initializes the TLS when a new thread gets created and never touches it again
2. It exposes the thread-local context record to the high-level Java code, and thus you never need to cross the FFI back to C++ code to update the context

In our internal benchmarks, this approach was even cheaper than the one we had before (there's a markdown file in that PR with our results), which was really great news, since I think we want as many OTel and other SDKs to adopt this feature, on by default, and being able to say "look the cost is ultra-low, you don't need to worry about this impacting performance".

(To be clear, my claim is not that we couldn't have done this without valid, only that it worked out quite well there -- and you can see the history of all our discussions and that we tried several designs and went quite a lot back-and-forth on that PR)

2. Even if it is in fact true that the valid flag makes it possible for the Java implementation to be slightly faster, this has other efficiency drawbacks. We have to check the valid flag on every trip through the unwinder (that's only one branch but it's not nothing), whereas any disadvantage on the writing side is only incurred when the label set is actually changed. Furthermore, having this flag makes the struct 2 bytes longer and the ABI more complicated.

I won't claim this does not add a bit more work on the reader side -- so that's definitely a trade-off for the gains I mention above.

Yet, I think there's an important flip-side to -- "We have to check the valid flag on every trip through the unwinder (that's only one branch but it's not nothing), whereas any disadvantage on the writing side is only incurred when the label set is actually changed.": the writer must always incur the cost of setting, otherwise, data will be missing/incomplete. If spans are installed for 100ms or even more at a time, that's not a lot of writes. But on a high-throughput system with requests in the single-ms range, it's possible there'll be even more writes than reads. And while the reader can always decide to self-throttle by tweaking the sampling rate, the writer doesn't have a good mechanism for this.

Both go and node do end up mapping their own high-level things onto OS threads, so there is a world where they could use this thread-local context as well.

Thus at least for me the distinction is about what we can be implemented efficiently as a library -- it doesn't matter that "theoretically" someone could change go/node directly to update the thread-local context when they swap async execution scopes or goroutines, because we need a solution that works today.

This to say, in terms of wording, I think that's what's interesting to get across?

I think either one works... And I have a small suggestion -- perhaps we could include a "hexdump" of a tiny example to clarify how it looks in practice?

We didn't do this for process context since that's mostly protobuf, but folks bootstrapping their own readers could use as a first test to check their parsing.

Yeah, this :D

We actually already have some text about this later on in the doc:

A SDK should choose to either set/unset the TLS pointer itself, or the valid flag, but not both.

The intention of this design is to enable flexibility for the writers. We envision that some writers may choose to keep a fixed record for a given thread and can thus mutate it in-place, and that other writers may instead keep the record associated with some other high-level concept (coroutine, request, etc) and swap out the pointer as needed when they become active on any given thread.

I was discussing this with Scott and I realized I wasn't quite sure I fully understood this suggestion.

Are you suggesting:

1. That the overall "Thread-Local Context Record" should have a total size that is aligned (so that e.g. people don't create one that is "exactly 613 bytes")?
2. That inside attrs-data the key/length/bytes entries should be aligned?
3. (Something else?)

We could restrict this a bit; yet I think allowing "no record" does make things easier on the writer. It allows a new webserver request to start by setting a record and to end by clearing it (before a thread goes back to the idle thread pool or similar).

Requiring always an active record would disallow an implementation of this kind. So I'd classify the "be able to go back to no record" as a nice to have, although yes we could make do without it.

I think mandating this seems a bit too strong?

E.g. if a reader wants to race the writer, why not? They'd be signing up for any of the usual problems, but I think that's par-for-the-course for that path, so I think the spec itself can suggest "you pro'lly don't wanna do that", but I think we can leave some space and not outright mandate it.

I think MUST is fine. It doesn't mean you will go to jail if you violate it, it just means "whatever you are doing is outside the scope of this specification, so we make no guarantees about what will happen". Which seems appropriate to me. E.g. if you violate this constraint you'll possibly read valid == true and nevertheless get torn reads in the rest of the record, and the spec can't really assign any useful semantics in that case.

I was indeed thinking along the lines you're suggesting. Going by the definition of the terms in https://datatracker.ietf.org/doc/html/rfc2119 "should" looked closer to me to what we want here, but I don't mind keeping the must if we want the stronger language to "discourage" racy implementations.

1. MUST This word, > or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.

3. SHOULD This > word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.

I'm going to leave this as it is until someone has a stronger opinion one way or the other; I kinda like being overly restrictive here because it feels like it constrains readers in a sensible fashion but agree it could go either way

Does this mean it will be targeting Linux only? (e.g., what about MacOS and Windows)

With this first version yes, for a few reasons:

• We expect the first consumers of this to be the eBPF Profiler and OBI both of which are Linux-specific
• This mechanism is quite low-level and with very tight efficiency goals, so we believe it's better to evaluate how exactly they would map to other OS with more care, than just going "they also have some thread-locals right? just use whatever they have there"
• While all three OS provide thread-locals, there is a very different security model across them (especially on macOS), and because of that it's not clear that this option would be the best one there

Thanks!

For a single pair, we'd have 28 bytes for the value; for two, 26 bytes total.
This sounds unexpected to me. Could we rephrase it to make it clear how we get to 28 bytes for a single value but 26 bytes for two values?

Do we want to have (key+length+val) to be aligned? And if so, should there be some padding?