[DO NOT MERGE] Entity Prototype for SDK Specification #7434

jsuereth · 2025-06-20T02:16:11Z

Replaces #6855

Implementation of OTEP#264

Updates OTLP Resource Marshaler code for OTLP 1.7 (which includes entity ref).
Puts new entity code in io.opentelemetry.sdk.resources.internal
Resource and ResourceBuilder do NOT follow other data class conventions in the SDK (of being a pure interface), so we are
unable to have this code anywhere but inside the SDK to make everything work.
Adds entity merge algorithm, partitioned into three key components.
Updates toString tests to be more flexible
Creates an entity incubator package
- Adds bare minimum EntityProvider
- Adds minimal EntityDetector
- Adds two implementation of EntityDetector for service and telemetry.sdk

Context

TODOs

Figure out where to put Entity classes
Figure out what to do about Resource in the SDK. Bincompat prevents many good design options.
Update telemetry.sdk and service resource attributes to be entities and include a SchemaURL.
EntityDetector mechanism and wiring
EntityProvider or ResourceProvider in the SDK, similar to TraceProvider, MeterProvider, etc.

The current design represents a "middle ground" for binary compatibility given the state of Resource today in the SDK.

- Create Entity/EntityBuilder class in internal package - Update serialization code Need to discuss how to work with Resource going forward.

- Remove ResourceWithEntity, no way to keep bincompat that way - Update toString tests to be a lot more forgiving, but preserve intent

codecov · 2025-06-20T02:30:14Z

Codecov Report

Attention: Patch coverage is 73.87387% with 145 lines in your changes missing coverage. Please review.

Project coverage is 89.64%. Comparing base (cc2844d) to head (7a7c426).
Report is 44 commits behind head on main.

Files with missing lines	Patch %	Lines
...cubator/entities/CurrentThreadExecutorService.java	11.90%	36 Missing and 1 partial ⚠️
...entelemetry/sdk/resources/internal/EntityUtil.java	75.42%	18 Missing and 11 partials ⚠️
...n/incubator/ObfuscatedExtendedOpenTelemerySdk.java	49.05%	27 Missing ⚠️
...ion/incubator/entities/SdkResourceSharedState.java	85.50%	5 Missing and 5 partials ⚠️
...ion/incubator/ExtendedOpenTelemetrySdkBuilder.java	70.96%	9 Missing ⚠️
...etry/api/incubator/entities/NoopEntityBuilder.java	0.00%	6 Missing ⚠️
...try/api/incubator/entities/NoopEntityProvider.java	0.00%	4 Missing ⚠️
...xtension/incubator/entities/SdkEntityProvider.java	66.66%	4 Missing ⚠️
...try/exporter/internal/otlp/EntityRefMarshaler.java	90.00%	0 Missing and 3 partials ⚠️
...k/extension/incubator/entities/SdkEntityState.java	57.14%	3 Missing ⚠️
... and 8 more

❌ Your patch check has failed because the patch coverage (73.87%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #7434      +/-   ##
============================================
- Coverage     89.75%   89.64%   -0.11%     
- Complexity     6980     7203     +223     
============================================
  Files           797      826      +29     
  Lines         21165    21926     +761     
  Branches       2057     2118      +61     
============================================
+ Hits          18996    19656     +660     
- Misses         1505     1589      +84     
- Partials        664      681      +17

☔ 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.

- fix reflective method lookup - also add unit test in the right project.

- Creates an API matching EntityProvider OTEP - Updates EntityDetector to be ResourceDetector - Creates synchronous "update resource with this entity" method. - Adds wiring for incubating API + incubating SDK Note: Still have some thoughts and ideas about a formal API, this may still change.

- Remove `Entity` and only expose `EntityBuilder` similar to how we do `LogRecord`s. - Have methods on `Resource` which determine if you're attaching the entity, simplify "remove" or just ignore for now.

…OpenTelemetry API. - Update shared state in SDK to use Supplier<Resource> instead of Resource - Add helper utils to expose private methods to supply the supplier - Create new ExtendedOpenTelemetry* API/SDK and end-to-end test.

jack-berg

Left a variety of comments, but the only material ones are about naming.

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/ExtendedOpenTelemetry.java

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/Resource.java

jack-berg · 2025-07-09T22:39:14Z

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/Resource.java

+   * @param entityType the type of entity to remove.
+   * @return true if entity was found and removed.
+   */
+  public boolean removeEntity(String entityType);


So can multiple instrumentations compete to add or remove an entity with the same type?

Yes. This API is here to explore the browser-SIGs needs where session has changed and needs to be replaced.

The current addOrUpdate method does NOT replace an entity if the ID has changed, you must manually remove it.

This is the "footgun" we're worried about in Entities SIG and need to explore.

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/Resource.java

sdk/common/src/main/java/io/opentelemetry/sdk/resources/internal/SdkEntity.java

jack-berg · 2025-07-09T23:03:59Z

sdk/logs/src/main/java/io/opentelemetry/sdk/logs/LoggerSharedState.java

@@ -18,28 +18,29 @@
 */
 final class LoggerSharedState {
  private final Object lock = new Object();
-  private final Resource resource;
+  private final Supplier<Resource> resourceSupplier;


sdk/logs/src/main/java/io/opentelemetry/sdk/logs/LoggerSharedState.java

sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkLoggerProviderBuilder.java

jack-berg · 2025-07-09T23:06:58Z

sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkLoggerProviderBuilder.java

+   * @param supplier The supplier of {@link Resource}.
+   * @since 1.X.0
+   */
+  SdkLoggerProviderBuilder setResourceSupplier(Supplier<Resource> supplier) {


I don't see these new Sdk{Signal}ProviderBuilder#setResourceSupplier methods being exercised. How do these fit into the puzzle?

They're called reflectively in the extension: https://github.com/jsuereth/opentelemetry-java/blob/reboot-entity-prototype/sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/ExtendedOpenTelemetrySdkBuilder.java#L88

…internal/otlp/EntityRefMarshaler.java Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com>

…iderBuilder.java Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com>

- Hide more methods (no incubating methods in public APIs that are not internal) - Update builder API to use attributes directly - Use static instances in Noop API

jsuereth added 9 commits June 18, 2025 10:13

Reboot the entity prototype

f056298

- Create Entity/EntityBuilder class in internal package - Update serialization code Need to discuss how to work with Resource going forward.

Add base entity class, merge logic and test

5460d5e

Move Entity and EntityBuilder to be pure interfaces

ce0e66d

Add more merge helper methods and tests

cb74286

Added test for merging raw attributes

3369be3

Cleanups and reverting silly changes

2c4aaeb

fix minor style issue

8af2cd1

Actually wire entities into resource

da525bd

- Remove ResourceWithEntity, no way to keep bincompat that way - Update toString tests to be a lot more forgiving, but preserve intent

Fix typo

b119561

jsuereth changed the title ~~[DO NOT MERGE] Reboot the Entity Prototype~~ [DO NOT MERGE] Entity Prototype for SDK Specification Jun 20, 2025

jsuereth mentioned this pull request Jun 20, 2025

EntityProvider prototype #7360

Draft

jsuereth added 4 commits June 20, 2025 18:12

Remove all publicly accessible references to Entity from stable packages

ddf096d

Add incubating EntityProvider API for specification work

9c222dd

Fix refactoring that broke reflection.

2871ff0

- fix reflective method lookup - also add unit test in the right project.

Fix schema url and test, now that we proved it works

34b6f60

jsuereth added this to Entities Jun 21, 2025

jsuereth moved this to In Progress in Entities Jun 21, 2025

jsuereth mentioned this pull request Jun 23, 2025

First cut at Entity API + SDK specification. open-telemetry/opentelemetry-specification#4565

Draft

jsuereth added 4 commits July 5, 2025 15:01

Further simplify the API and SDK for entities

ebf9557

- Remove `Entity` and only expose `EntityBuilder` similar to how we do `LogRecord`s. - Have methods on `Resource` which determine if you're attaching the entity, simplify "remove" or just ignore for now.

Fix javadoc issues

8d4288e

jack-berg reviewed Jul 9, 2025

View reviewed changes

jsuereth mentioned this pull request Jul 10, 2025

OTEP: Define EntityProvider open-telemetry/opentelemetry-specification#4316

Open

jsuereth and others added 5 commits July 10, 2025 09:52

Update exporters/otlp/common/src/main/java/io/opentelemetry/exporter/…

f22ec8d

…internal/otlp/EntityRefMarshaler.java Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com>

Update sdk/logs/src/main/java/io/opentelemetry/sdk/logs/SdkLoggerProv…

d220005

…iderBuilder.java Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com>

Fixes from review.

f9dcb52

- Hide more methods (no incubating methods in public APIs that are not internal) - Update builder API to use attributes directly - Use static instances in Noop API

Remove methods we don't need yet.

18afb60

Remove redundant visibility.

7ace665

jsuereth added 12 commits July 10, 2025 13:04

More cleanups from review.

d5219d1

Simplify prototype of SdkResource.

cba0606

Fix typo.

a38a544

More cleanups from review.

d01f5a3

Add more tests for ResourceProvider.

2560c51

Fix stylecheck.

bf72978

More checkstyle fixes.

af3bbd9

Rename prototype to more closely match OTEP 4316.

2809916

Finish remove implementation and listeners.

912ba24

Remove assertjs helpers, update javadoc.

634c4a3

Fix entity javadoc.

5c126c9

Fix tests.

7a7c426

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[DO NOT MERGE] Entity Prototype for SDK Specification #7434

[DO NOT MERGE] Entity Prototype for SDK Specification #7434

Uh oh!

jsuereth commented Jun 20, 2025 •

edited

Loading

Uh oh!

codecov bot commented Jun 20, 2025 •

edited

Loading

Uh oh!

jack-berg left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jack-berg Jul 9, 2025

Uh oh!

jsuereth Jul 10, 2025

Uh oh!

Uh oh!

Uh oh!

jack-berg Jul 9, 2025

Uh oh!

Uh oh!

Uh oh!

jack-berg Jul 9, 2025

Uh oh!

jsuereth Jul 10, 2025

Uh oh!

Uh oh!

[DO NOT MERGE] Entity Prototype for SDK Specification #7434

Are you sure you want to change the base?

[DO NOT MERGE] Entity Prototype for SDK Specification #7434

Uh oh!

Conversation

jsuereth commented Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

TODOs

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

jack-berg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jack-berg Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

jsuereth Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jack-berg Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jack-berg Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

jsuereth Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jsuereth commented Jun 20, 2025 •

edited

Loading

codecov bot commented Jun 20, 2025 •

edited

Loading