[DO NOT MERGE] Prototype Entities (otep#264) in Java SDK #6855
Conversation
jsuereth
force-pushed
the
wip-resource-updates
branch
from
4d81df2
to
b7421c2
Compare
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #6855 +/- ##
============================================
- Coverage 90.23% 90.11% -0.13%
- Complexity 6594 6658 +64
============================================
Files 729 739 +10
Lines 19800 20024 +224
Branches 1947 1973 +26
============================================
+ Hits 17867 18045 +178
- Misses 1341 1376 +35
- Partials 592 603 +11 ☔ View full report in Codecov by Sentry. |
sdk/common/src/main/java/io/opentelemetry/sdk/resources/Entity.java
Outdated
Show resolved
Hide resolved
| static final Entity create( | ||
| String entityType, | ||
| Attributes identifying, | ||
| Attributes descriptive, |
There was a problem hiding this comment.
If we call these descriptive here, should the getAttributes() method be renamed to getDescriptiveAttributes()?
There was a problem hiding this comment.
We discussed this a bit in the Entities WG. I think yes.
| /** | ||
| * Modify the descriptive attributes of this Entity. | ||
| * | ||
| * @param f A thunk which manipulates descriptive attributes. |
There was a problem hiding this comment.
What's a thunk?
Separately, what's the motivation behind a consumer rather than the simpler withDescriptive(Attributes atributes)? The consumer pattern is more clever and lower overhead, but is less intuitive and this probably isn't a place where efficiency matter.s
There was a problem hiding this comment.
This was just me taking shortcuts in adding all the various methods. I think if we submit this we should expand to ALL relevant methods of add{Identifying|Descriptive}Attribute{s?}.
A "thunk" is a term in other languages for first-class functions, lambdas, etc. I can update this API to actually be the one we'd expose. For now, just assume you have a bunch of reasonable methods to add attributes :).
sdk/common/src/main/java/io/opentelemetry/sdk/resources/Entity.java
Outdated
Show resolved
Hide resolved
| * the SDK (called "associated entities"). For Example, if the SDK is running in a kubernetes pod, | ||
| * it may provide an Entity for that pod. | ||
| */ | ||
| public interface EntityDetector { |
There was a problem hiding this comment.
What's the thinking behind making EntityDetector a part of the SDK, instead of part of opentelemetry-sdk-extension-autoconfigure-spi like ResourceProvider?
There was a problem hiding this comment.
Long term direction is for ResourceProvider to become part of SDK and allow mutating the set of entities or descriptive attributes over time.
I.e. ResourceProvider might provide something like an observer-pattern for gaining access to the current definition of resource. You can then pass this to {Signal}Provider.
Initially we don't need that and I expect ResourceProvider to be an internal detail.
| * | ||
| * @return a list of discovered entities. | ||
| */ | ||
| List<Entity> detectEntities(); |
There was a problem hiding this comment.
Should a single entity detector return multiple entities or a single entity?
There was a problem hiding this comment.
Multiple, as is the case today for most non-otel detectors.
E.g. k8s entity detector may detect all relevant entities (k8s.cluster, k8s.namespace, k8s.pod, etc.). AWS/GCP/Azure/Other Cloud detector might find cloud entity in addition to host, faas, etc.
| package io.opentelemetry.sdk.resources; | ||
|
|
||
| /** A Registry which provides the {@link Resource} to the SDK. */ | ||
| public final class ResourceProvider { |
There was a problem hiding this comment.
We already have ResourceProvider and will likely need to pick a different name.
Separately, I'm a little confused on the purpose of this thing. Seems like we could get away extending ResourceBuilder to include entity concepts.
There was a problem hiding this comment.
It's called out in the OTEP: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/entities/0264-resource-and-entities.md#resource-provider
Initially it doesn't do much, eventually it'll be critical for client-side handling (e.g. Android SDK)
| // } | ||
|
|
||
| private static String getServiceName() { | ||
| return System.getenv().getOrDefault("OTEL_SERVICE_NAME", "unknown_service:java"); |
There was a problem hiding this comment.
We separate out the interpretation of environment variables into autoconfigure, which has proved to be an separation of responsibilities. Should put all built-in entity detectors over there.
There was a problem hiding this comment.
You need to give me a solution to this then: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/common/src/main/java/io/opentelemetry/sdk/resources/Resource.java#L51. Effectively your "required" entity will be service from the SDK. I can have the baked in discover a broken one, but then we need to make sure it appropriately gets overriden in all scenarios.
Additionally, be ready for: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/entities/0264-resource-and-entities.md#environment-variable-detector. This explicitly not a configuration-based ENV variable. This is a "carrier" of context for environments (e.g. K8S, FAAS, etc.) to provide identity to things they run. I think we should probably talk about how best to encode this in Java. I'd rather not have this rely on autoconfigure, as that implies it's a configuration thing.
|
|
||
| public final class ServiceInstanceDetector implements EntityDetector { | ||
| private static final String SCHEMA_URL = "https://opentelemetry.io/schemas/1.28.0"; | ||
| private static final String ENTITY_TYPE = "service.instance"; |
There was a problem hiding this comment.
Are these entity types and their associated identifying / descriptive attributes codified anywhere yet?
There was a problem hiding this comment.
https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource
We're working on formalizing and stabilizing. Starting with k8s.* here: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/k8s.md
This does NOT update Resource.merge for entities yet. This has many inefficiencies that can be optimised away. - Adds Entity + EntityBuilder for constructing entities in the SDK - Add EntityDetector for discovering entities - Moves `service` and `telemetry.sdk` detection to EntityDetectors - Updates to semconv 1.28.0 for service/telemetry.sdk - Updates Resource + ResourceBuilder to preserve Entity - Creates a ResourceProvider that can be used to construct Resource using entity merge rules. - Hacky `getAttributes` update on Resource to preserve existing behavior. Tests pending.
jsuereth
force-pushed
the
wip-resource-updates
branch
from
144e141
to
8b4f48f
Compare
This is a prototype of Java SDK updates for Entities OTEP.
Entity,EntityBuilder,EntityDetectorto sdk common package.ResourceandResourceBuilder. Updates merge logic to match OTEP specification.ResourceProviderwhich attempts to centralize Resource/Entity logic. This will need to be sorted out with existing sdk-extension ResourceProviders.toStringchanges.Note: This prototype does NOT attempt to isolate experimental features into
internaldirectories and expose an experimental package. That would be done when fragmenting this prototype into components and submitting "final" variants w/ specification work.