EntityProvider prototype #7360

breedx-splk · 2025-05-21T00:50:37Z

Here's an initial straw-man implementation in java of the EntityProvider described in otep-4316.

My first impressions are that the implementation itself is pretty basic and open to future tweaking/improvements (it's really just supposed to be a caching thread-safe CRUD bucket), but the interesting and more complicated stuff begins to happen when the EntityProvider is integrated with or otherwise used by other places in the code.

Right now, it is wired up into the SdkTracerProvider and has exposed builder methods on the SdkTracerProviderBuilder. I think there are bound to be breaking changes in that, so please feel free to call those out. Right now, there's also no way for users or instrumentations to get any handle to the "live" EntityProvider in order to add/update/delete any entities...it would have to be wired up entirely by the user and retained.

I also did not yet attempt to wire it up metrics or logs, because I figured there would be enough to talk about first with traces. :)

codecov · 2025-05-21T05:36:37Z

Codecov Report

Attention: Patch coverage is 93.40659% with 6 lines in your changes missing coverage. Please review.

Project coverage is 89.85%. Comparing base (cc7d085) to head (f279641).

Files with missing lines	Patch %	Lines
...ntelemetry/sdk/trace/SdkTracerProviderBuilder.java	50.00%	5 Missing ⚠️
.../opentelemetry/sdk/entities/SdkEntityProvider.java	98.48%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #7360      +/-   ##
============================================
- Coverage     89.87%   89.85%   -0.02%     
- Complexity     6899     6921      +22     
============================================
  Files           786      789       +3     
  Lines         20793    20877      +84     
  Branches       2026     2034       +8     
============================================
+ Hits          18687    18760      +73     
- Misses         1465     1473       +8     
- Partials        641      644       +3

☔ View full report in Codecov by Sentry.
📢 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.

jsuereth

Great start!!!

Just some random thoughts, brainstorms and questions on the implementation.

jsuereth · 2025-05-21T12:39:26Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/EntityListener.java

+
+public interface EntityListener {
+
+  void onEntityState(Entity state, Resource resource);


Why is this returning a resource?

It's just following this part of the otep. My understanding was that it's something like "Here's the entity that changed and here's the new resource after it was applied".

Is it wrong?

Not necessarily, I was just curious on the motivation/use-case.

jsuereth · 2025-05-21T12:40:52Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/EntityProvider.java

+   * be removed and a new instance will be inserted at the end of the list of entities. After the
+   * entity is added, the resource is rebuilt and the listeners are notified.
+   */
+  void addEntity(String id, String name, Attributes attributes);


Entities will need Schema URL with them.

I'd suggest dropping this method, even from the prototype (or keeping it private).

Feel free to copy-paste the entity + entity builder classes from my prototype (https://github.com/open-telemetry/opentelemetry-java/blob/cdd5f792b0f412948783e89762d2dc090fe77daa/sdk/common/src/main/java/io/opentelemetry/sdk/resources/EntityBuilder.java)

jsuereth · 2025-05-21T12:42:17Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/EntityProvider.java

+   * the change is effectively made "in-place". After the Entity has been updated, the listeners
+   * will be notified.
+   */
+  void updateEntity(String id, Attributes attributes);


So entities are made of identifying and descriptive attributes and a type (or name).

I'd expect this method to either take in an entity wholesale or somehow take in EntityId that is a combination of Identifying Attributes, type/name and SchemaUrl.

jsuereth · 2025-05-21T12:44:11Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/EntityProvider.java

+   * then it is effectively a no-op. If the Entity is removed, the Resource will be rebuilt and
+   * listeners will then be notified.
+   */
+  void deleteEntity(String id);


Should this be by name/type or by all identifying components of the Entity?

My thinking is we may want both, or we want a "replace entity", something like:

void onSessionChange(Session session) { entityManager.replaceEntity(createEntityFromSession(session); }

jsuereth · 2025-05-21T12:46:06Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/SdkEntityProvider.java

+public class SdkEntityProvider implements EntityProvider {
+
+  private final Object lock = new Object();
+  private final AtomicReference<Resource> resource = new AtomicReference<>(Resource.empty());


I like this concurrency model.

You have a lock guarding the raw entity information, and then you publish Resource to threads via AtomicReference.

Not needed for prototype, but I'd document this somewhere so it's easy to pick up and understand how to protect the resource reference.

jsuereth · 2025-05-21T12:49:50Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/SdkEntityProvider.java

+  private final AtomicReference<Resource> resource = new AtomicReference<>(Resource.empty());
+
+  @GuardedBy("lock")
+  private final LinkedHashMap<String, Entity> entities = new LinkedHashMap<>();


Are you using linked-hash-map to get predicatability in the final set of resource attributes or for another reason?

Yeah, it's to maintain the order in which the Entities were added, because that iteration order determines how the Resource gets merge()d to the final result.

So resource.merge logic is in a previous otep.

For this prototype we shouldn't stress over details, but note that the previous otep as it reaches the specification will give you a merge method you can use here.

jsuereth · 2025-05-21T12:51:57Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/SdkEntityProvider.java

+      listeners = new ArrayList<>(this.listeners);
+    }
+    for (EntityListener listener : listeners) {
+      listener.onEntityState(updatedEntity, resource);


Nit: We may want to track whether there was an actual attribute change here before firing state.

Given we own the known state of the entity, it's unlikely callers of this method will actually know if an event they receive marks a real change in attirbutes, so we could filter down events to only real changes that have occurred.

Again, not needed for a prototype, just brainstorming features for final solution.

Agree, that did occur to me as I was hacking this up. I would go so far as to say that there probably needs to be spec language that addresses this...something like "Add/update/delete actions that don't result in an underlying change to the Resource should not notify listeners and SHOULD be treated like a no-op".

jsuereth · 2025-05-21T13:02:44Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/SdkEntityProvider.java

+
+  private Resource rebuildResource() {
+    Resource newResource = doRebuildResource();
+    resource.set(newResource);


nit, you can use lazySet here to avoid flushing your local cache. The details on this are quite obtuse over time, but here's the best explanation (that I believe is still valid) for why: https://psy-lob-saw.blogspot.com/2012/12/atomiclazyset-is-performance-win-for.html

I believe you're abiding by single-writer principle, and this could help avoiding flushing cache on write until the time the rest of the SDK requests access to the resource.

jsuereth · 2025-05-21T13:03:25Z

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/SdkTracerProviderBuilder.java

+   *
+   * @since ??.??.??
+   */
+  public SdkTracerProviderBuilder addEntity(String id, String name, Attributes attributes) {


Is the plan to expose this on TraceProvider?

Why not force things through EntityProvider?

Oh, I dunno....this is almost certainly misplaced, good catch. I think I should remove it.

I think maybe I was just hammering through all the compilation problems and thought this needed parity with the addResource() but that's not quite right.

I'm still not sure how the user is supposed to get ahold of the EntityProvider though.

Yeah - I'm thinking we may need it to be an API level thing ... But hoping prototypes like this can teach us that.

jsuereth · 2025-05-21T13:04:18Z

sdk/trace/src/main/java/io/opentelemetry/sdk/trace/SdkTracerProviderBuilder.java

@@ -76,19 +115,19 @@ public SdkTracerProviderBuilder setIdGenerator(IdGenerator idGenerator) {
   */
  public SdkTracerProviderBuilder setResource(Resource resource) {
    requireNonNull(resource, "resource");
-    this.resource = resource;
+    this.entityProvider = new SdkEntityProvider(Collections.singletonList(Entity.create(resource)));


This will need to be much more sophisticated to deal with Resource vs. Entity shenanigans.

trask · 2025-05-22T16:18:22Z

sdk/common/src/main/java/io/opentelemetry/sdk/entities/EntityProvider.java

+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.sdk.resources.Resource;
+
+public interface EntityProvider {


ResourceProvider?

if that's impossible, maybe EntitiesProvider?

How about ResourceFromEntitiesProvider so that we can avoid the existing name conflict?

breedx-splk added 5 commits May 20, 2025 17:09

initial EntityProvider prototype

abfcb41

initial prototype of EntityProvider

126c7cf

re-add setResource() and run jApiCmp

7df12a5

fix test

4cd447a

fix test

f279641

jsuereth reviewed May 21, 2025

View reviewed changes

remove addEntity methods

3949ed3

trask reviewed May 22, 2025

View reviewed changes


		public interface EntityListener {

		void onEntityState(Entity state, Resource resource);

EntityProvider prototype #7360

Are you sure you want to change the base?

EntityProvider prototype #7360

Uh oh!

Conversation

breedx-splk commented May 21, 2025

Uh oh!

codecov bot commented May 21, 2025

Codecov Report

Uh oh!

jsuereth left a comment

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!

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!