Visitar URL original
Add experimental SDK entity support and OTLP export by jsuereth · Pull Request #8464 · open-telemetry/opentelemetry-java · GitHub
Skip to content

Add experimental SDK entity support and OTLP export - #8464

Merged
jack-berg merged 35 commits into
open-telemetry:mainfrom
jsuereth:wip-entity-sdk-for-reals
Oct 8, 2026
Merged

jack-berg merged 35 commits into
open-telemetry:mainfrom
jsuereth:wip-entity-sdk-for-reals

Conversation

@jsuereth

@jsuereth jsuereth commented Jun 9, 2026 •

Copy link
Copy Markdown
Contributor

Adds experimental entity support to SDK resources through internal APIs, including merging, filtering, and OTLP entity references. Entities are exported / serialized whenever present.

Also parses OTEL_ENTITIES / otel.entities in autoconfiguration and adds entity support to autoconfigure and declarative configuration’s env and service resource detectors.

Resource behavior follows five rules of thumb:

  1. Later writes win, whether attributes come from an entity or an ordinary write.
  2. Compatible entities merge descriptions. Entities with the same type, identifying attributes, and schema merge descriptions. Different IDs or schemas replace the whole old entity, including its attributes.
  3. Conflicts remove associations, not unrelated attributes. An ordinary write changing any entity-owned attribute, or another entity type claiming it, removes the affected association and preserves non-conflicting attributes as ordinary attributes. Unchanged writes preserve associations.
  4. Existing resource APIs operate on all attributes. Filtering removes selected attributes and preserves the rest. Removing any identifying attribute also removes the entity association; removing only descriptive attributes preserves it.
  5. Log at WARNING whenever an entity changes or its association is removed.

- Create new Entity Detectors that are completely separate from existing
  reosurce detectors so entity must be FULL opt-in before behavior
  changes, even if OTLP is non-breaking.
- Wire "either/or" scenarios into resource factory and declarative
  config.

TODOs we need to sort out:

- Features of ResourceConfiguration spec that interact poorly with
  entities, e.g. attribute-specific filters that aren't entity aware,
  raw attribute definitions.
- Adding `env` as a supported detector for reading in Entity env
  variable propagation.
- Dealing with oddities of ResourceBuilder/Factory wanting to only use
  attributes in Java - we worked around it for now.

@jack-berg jack-berg left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You'll need to handle some merge conflicts since declarative config has been undergoing construction:

  • It moved out of the incubator into a dedicated artifact in #8265
  • We started commiting generated POJOs to VCS in #8408

As mentioned in the SIG meeting, I don't think you need the incubator copies of Entity interfaces. I pushed a commit here to delete them: jack-berg@3ea17f4

Per the discussion, resource detectors will need to updated to optionally produce entity-aware resources. If the user opts in, then those resource detectors can call the internal APIs from opentelemetry-sdk-common to produce those.

@otelbot otelbot Bot added the api-change Changes to public API surface area label Jun 25, 2026
@codecov

codecov Bot commented Jun 25, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.72349% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.64%. Comparing base (0d0b0ca) to head (a0fb597).

Files with missing lines Patch % Lines
...lemetry/sdk/autoconfigure/EnvironmentResource.java 85.64% 12 Missing and 16 partials ⚠️
...entelemetry/sdk/resources/internal/EntityUtil.java 80.00% 6 Missing ⚠️
...try/sdk/resources/internal/AttributeCheckUtil.java 87.50% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@             Coverage Diff              @@
##               main    #8464      +/-   ##
============================================
+ Coverage     90.58%   90.64%   +0.06%     
- Complexity    10742    10855     +113     
============================================
  Files          1007     1014       +7     
  Lines         29205    29643     +438     
  Branches       3786     3858      +72     
============================================
+ Hits          26456    26871     +415     
- Misses         1850     1859       +9     
- Partials        899      913      +14     

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

- Simplify API for using entities.
- Update  so we can use current resource detection unchanged with entities.
- Memoize full attributes manually when creating a resource.
@otelbot otelbot Bot removed the api-change Changes to public API surface area label Jun 25, 2026
@jsuereth jsuereth changed the title [DRAFT] Entity SDK prototype Entity SDK - Initial opt-in SDK features Jun 25, 2026

@jack-berg jack-berg left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking pretty good

@opentelemetry-pr-dashboard

opentelemetry-pr-dashboard Bot commented Jun 29, 2026 •

Copy link
Copy Markdown

Pull request dashboard status

Merged · refreshed 2026-10-08 20:16 UTC

Status above doesn't look right?
  • Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

jsuereth added 6 commits June 29, 2026 12:48
QT_ACCESSIBILITY=1
COLORTERM=truecolor
HISTCONTROL=ignoredups
XDG_MENU_PREFIX=gnome-
TERM_PROGRAM_VERSION=1.107.0
GNOME_DESKTOP_SESSION_ID=this-is-deprecated
GTK_IM_MODULE=ibus
QT_IM_MODULES=wayland;ibus
PULSE_RUNTIME_PATH=/run/user/110055/crd_audio#_Bm5JrFQNq
CHROME_REMOTE_DESKTOP_HOST_EXTRA_PARAMS=--enable-utempter
P4CONFIG=.p4config
SSH_AUTH_SOCK=/run/user/110055/crd_ssh_auth_sock
MEMORY_PRESSURE_WRITE=c29tZSAyMDAwMDAgMjAwMDAwMAA=
XMODIFIERS=@im=ibus
X20_HOME=/google/data/rw/users/jo/joshuasuereth
ANTIGRAVITY_CLI_ALIAS=jetski-ide
GTK_MODULES=gail:atk-bridge
PWD=/usr/local/google/home/joshuasuereth/projects/open-telemetry/opentelemetry-java
RSYNC_RSH=ssh
LOGNAME=joshuasuereth
XDG_SESSION_TYPE=x11
CHROME_CONFIG_HOME=/usr/local/google/home/joshuasuereth/.config/chrome-remote-desktop/chrome-config
GPG_AGENT_INFO=/run/user/110055/gnupg/S.gpg-agent:0:1
SYSTEMD_EXEC_PID=4924
XAUTHORITY=/usr/local/google/home/joshuasuereth/.Xauthority
VSCODE_GIT_ASKPASS_NODE=/opt/jetski-ide/jetski
GOOGLE_API_CERTIFICATE_CONFIG=/etc/gcloud/certificate_config.json
P4MERGE=/google/src/files/head/depot/eng/perforce/mergep4.tcl
PULSE_SINK=chrome_remote_desktop_session
HOME=/usr/local/google/home/joshuasuereth
LANG=en_US.UTF-8
CLOUDSDK_CONTEXT_AWARE_USE_CLIENT_CERTIFICATE=true
LS_COLORS=rs=0:di=01;34:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:or=40;31;01:mi=00:su=37;41:sg=30;43:ca=00:tw=30;42:ow=34;42:st=37;44:ex=01;32:*.7z=01;31:*.ace=01;31:*.alz=01;31:*.apk=01;31:*.arc=01;31:*.arj=01;31:*.bz=01;31:*.bz2=01;31:*.cab=01;31:*.cpio=01;31:*.crate=01;31:*.deb=01;31:*.drpm=01;31:*.dwm=01;31:*.dz=01;31:*.ear=01;31:*.egg=01;31:*.esd=01;31:*.gz=01;31:*.jar=01;31:*.lha=01;31:*.lrz=01;31:*.lz=01;31:*.lz4=01;31:*.lzh=01;31:*.lzma=01;31:*.lzo=01;31:*.pyz=01;31:*.rar=01;31:*.rpm=01;31:*.rz=01;31:*.sar=01;31:*.swm=01;31:*.t7z=01;31:*.tar=01;31:*.taz=01;31:*.tbz=01;31:*.tbz2=01;31:*.tgz=01;31:*.tlz=01;31:*.txz=01;31:*.tz=01;31:*.tzo=01;31:*.tzst=01;31:*.udeb=01;31:*.war=01;31:*.whl=01;31:*.wim=01;31:*.xz=01;31:*.z=01;31:*.zip=01;31:*.zoo=01;31:*.zst=01;31:*.avif=01;35:*.jpg=01;35:*.jpeg=01;35:*.jxl=01;35:*.mjpg=01;35:*.mjpeg=01;35:*.gif=01;35:*.bmp=01;35:*.pbm=01;35:*.pgm=01;35:*.ppm=01;35:*.tga=01;35:*.xbm=01;35:*.xpm=01;35:*.tif=01;35:*.tiff=01;35:*.png=01;35:*.svg=01;35:*.svgz=01;35:*.mng=01;35:*.pcx=01;35:*.mov=01;35:*.mpg=01;35:*.mpeg=01;35:*.m2v=01;35:*.mkv=01;35:*.webm=01;35:*.webp=01;35:*.ogm=01;35:*.mp4=01;35:*.m4v=01;35:*.mp4v=01;35:*.vob=01;35:*.qt=01;35:*.nuv=01;35:*.wmv=01;35:*.asf=01;35:*.rm=01;35:*.rmvb=01;35:*.flc=01;35:*.avi=01;35:*.fli=01;35:*.flv=01;35:*.gl=01;35:*.dl=01;35:*.xcf=01;35:*.xwd=01;35:*.yuv=01;35:*.cgm=01;35:*.emf=01;35:*.ogv=01;35:*.ogx=01;35:*.aac=00;36:*.au=00;36:*.flac=00;36:*.m4a=00;36:*.mid=00;36:*.midi=00;36:*.mka=00;36:*.mp3=00;36:*.mpc=00;36:*.ogg=00;36:*.ra=00;36:*.wav=00;36:*.oga=00;36:*.opus=00;36:*.spx=00;36:*.xspf=00;36:*~=00;90:*#=00;90:*.bak=00;90:*.crdownload=00;90:*.dpkg-dist=00;90:*.dpkg-new=00;90:*.dpkg-old=00;90:*.dpkg-tmp=00;90:*.old=00;90:*.orig=00;90:*.part=00;90:*.rej=00;90:*.rpmnew=00;90:*.rpmorig=00;90:*.rpmsave=00;90:*.swp=00;90:*.tmp=00;90:*.ucf-dist=00;90:*.ucf-new=00;90:*.ucf-old=00;90:
XDG_CURRENT_DESKTOP=GNOME
PYTHONSTARTUP=/usr/local/google/home/joshuasuereth/.config/Jetski/User/workspaceStorage/cbb7ec0eec555b4d06671311926a9b6f/ms-python.python/pythonrc.py
MEMORY_PRESSURE_WATCH=/sys/fs/cgroup/user.slice/user-110055.slice/user@110055.service/session.slice/org.gnome.Shell@x11.service/memory.pressure
VTE_VERSION=8390
VSCODE_JAVA_EXEC=/usr/lib/jvm/java-21-openjdk-amd64/bin/java
GIT_ASKPASS=/opt/jetski-ide/resources/app/extensions/git/dist/askpass.sh
GNOME_TERMINAL_SCREEN=/org/gnome/Terminal/screen/1538e342_19f1_4bdb_9b1d_20e770cebc04
STREAMZ_SERVERS=[2001:4860:f802::78]:9530
CHROME_DESKTOP=jetski.desktop
CLUTTER_IM_MODULE=ibus
INFOPATH=/usr/share/emacs-google-config/info:
CHROME_REMOTE_DESKTOP_SESSION=1
VSCODE_GIT_ASKPASS_EXTRA_ARGS=
VSCODE_PYTHON_AUTOACTIVATE_GUARD=1
CLOUDSDK_CONTAINER_USE_APPLICATION_DEFAULT_CREDENTIALS=true
LESSCLOSE=/usr/bin/lesspipe %s %s
XDG_SESSION_CLASS=user
PYTHONPATH=/usr/local/buildtools/current/sitecustomize
TERM=xterm-256color
PYTHON_BASIC_REPL=1
LESSOPEN=| /usr/bin/lesspipe %s
SK_SIGNING_PLUGIN=gnubbyagent
USER=joshuasuereth
VSCODE_GIT_IPC_HANDLE=/run/user/110055/vscode-git-e5a8f99bf6.sock
GNOME_TERMINAL_SERVICE=:1.94
CHROME_REMOTE_DESKTOP_DEFAULT_DESKTOP_SIZES=1600x1200,3840x2160,3840x2560,5120x1440,2160x3840
CLOUDSDK_CONTEXT_AWARE_USE_MTLS_FOR_GRPC=true
DISPLAY=:20
SHLVL=1
PARINIT=rTbgqR B=.?_A_a Q=_s>|:
CLOUDSDK_CONTEXT_AWARE_CERTIFICATE_CONFIG_FILE_PATH=/etc/gcloud/certificate_config.json
GOOGLE_AUTH_WEBAUTHN_PLUGIN=gcloudwebauthn
QT_IM_MODULE=ibus
CVS_RSH=ssh
MANAGERPIDFDID=2490
FC_FONTATIONS=1
LD_LIBRARY_PATH=/usr/lib/mesa-diverted/x86_64-linux-gnu:/usr/lib/x86_64-linux-gnu/mesa:/usr/lib/x86_64-linux-gnu/dri:/usr/lib/x86_64-linux-gnu/gallium-pipe
XDG_RUNTIME_DIR=/run/user/110055
PIPEWIRE_REMOTE=crd_audio#_Bm5JrFQNq/pipewire
VSCODE_GIT_ASKPASS_MAIN=/opt/jetski-ide/resources/app/extensions/git/dist/askpass-main.js
GTK3_MODULES=xapp-gtk3-module
VSCODE_JDWP_ADAPTER_ENDPOINTS=/usr/local/google/home/joshuasuereth/.jetski/extensions/vscjava.vscode-java-debug-0.59.0-universal/.noConfigDebugAdapterEndpoints/endpoint-c1594771e7136dbf.txt
XDG_DATA_DIRS=/usr/share/gnome:/usr/local/share/:/usr/share/
GDK_BACKEND=x11
PATH=/usr/local/google/home/joshuasuereth/.local/bin:/usr/local/google/home/joshuasuereth/bin:/usr/local/google/home/joshuasuereth/.cargo/bin:/usr/local/google/home/joshuasuereth/.local/bin:/usr/local/google/home/joshuasuereth/bin:/usr/lib/google-golang/bin:/usr/local/buildtools/java/jdk/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/google/home/joshuasuereth/.jetski/extensions/vscjava.vscode-java-debug-0.59.0-universal/bundled/scripts/noConfigScripts
GOOGLE_CLOUD_DISABLE_DIRECT_PATH=true
CLOUDSDK_INTERNAL_USER=true
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/110055/bus
CLOUDSDK_CONTEXT_AWARE_USE_ECP_HTTP_PROXY=true
DATA_CLOUD_CURR_IDE_NAME=jetski
TERM_PROGRAM=vscode
BASH_FUNC_poetry%%=() {  /usr/bin/gpkg poetry "$@"
}
BASH_FUNC_yarn%%=() {  /usr/bin/gpkg yarn "$@"
}
BASH_FUNC_pip%%=() {  /usr/bin/gpkg pip "$@"
}
BASH_FUNC_pdm%%=() {  /usr/bin/gpkg pdm "$@"
}
BASH_FUNC_uvx%%=() {  /usr/bin/gpkg uvx "$@"
}
BASH_FUNC_npm%%=() {  /usr/bin/gpkg npm "$@"
}
BASH_FUNC_npx%%=() {  /usr/bin/gpkg npx "$@"
}
BASH_FUNC_pip3%%=() {  /usr/bin/gpkg pip3 "$@"
}
BASH_FUNC_python3%%=() {  /usr/bin/gpkg python3 "$@"
}
BASH_FUNC_pipx%%=() {  /usr/bin/gpkg pipx "$@"
}
BASH_FUNC_pnpx%%=() {  /usr/bin/gpkg pnpx "$@"
}
BASH_FUNC_pnpm%%=() {  /usr/bin/gpkg pnpm "$@"
}
BASH_FUNC_yarnpkg%%=() {  /usr/bin/gpkg yarnpkg "$@"
}
BASH_FUNC_uv%%=() {  /usr/bin/gpkg uv "$@"
}
BASH_FUNC_python%%=() {  /usr/bin/gpkg python "$@"
}
BASH_FUNC_hatch%%=() {  /usr/bin/gpkg hatch "$@"
}
_=/usr/bin/env resource providerr.
@jsuereth

Copy link
Copy Markdown
Contributor Author

@jack-berg I updated the method names and hopefully have tests passing (ran spotless locally)

pull Bot pushed a commit to thompson-tomo/opentelemetry-specification that referenced this pull request Jul 27, 2026
Fixes open-telemetry#5200

## Changes

- Add new retrieve method for entities and unassociated attributes
- Add new parameters for creating Resources
- Update `merge` to require the data model merge algorithm (or
equivalent) when entities exist.

For non-trivial changes, follow the [change proposal
process](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#proposing-a-change).

Prototypes:
- [java](open-telemetry/opentelemetry-java#8464)

NOTE: Did not update compliance matrix as I wasn't sure how to mark
things as experimental

* [x] Related issues #
* [X] Related [OTEP(s)](https://github.com/open-telemetry/oteps)
[#264](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/entities/0264-resource-and-entities.md)
* [x] Links to the prototypes (when adding or changing features)
* [x]
[`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md)
file updated for non-trivial changes
* For trivial changes, include `[chore]` in the PR title to skip the
changelog check
* [x] [Spec compliance
matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/template.yaml)
updated if necessary
* [x] [Declarative config data
model](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/data-model.md#overview)
is updated if SDK config surface is changed

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
Co-authored-by: Dmitry Anoshin <anoshindx@gmail.com>
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
jsuereth added a commit to jsuereth/opentelemetry-specification that referenced this pull request Jul 27, 2026
Fixes open-telemetry#5200

## Changes

- Add new retrieve method for entities and unassociated attributes
- Add new parameters for creating Resources
- Update `merge` to require the data model merge algorithm (or
equivalent) when entities exist.

For non-trivial changes, follow the [change proposal
process](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#proposing-a-change).

Prototypes:
- [java](open-telemetry/opentelemetry-java#8464)

NOTE: Did not update compliance matrix as I wasn't sure how to mark
things as experimental

* [x] Related issues #
* [X] Related [OTEP(s)](https://github.com/open-telemetry/oteps)
[open-telemetry#264](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/entities/0264-resource-and-entities.md)
* [x] Links to the prototypes (when adding or changing features)
* [x]
[`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md)
file updated for non-trivial changes
* For trivial changes, include `[chore]` in the PR title to skip the
changelog check
* [x] [Spec compliance
matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/template.yaml)
updated if necessary
* [x] [Declarative config data
model](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/data-model.md#overview)
is updated if SDK config surface is changed

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
Co-authored-by: Dmitry Anoshin <anoshindx@gmail.com>
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
@opentelemetry-pr-dashboard

This comment has been minimized.

@jack-berg
jack-berg self-requested a review August 19, 2026 21:28
@jack-berg

Copy link
Copy Markdown
Member

Removed my approval so this doesn't get accidentally merged. I agree with it in principle - we just need the spec to catch up and iron out details on whether entities should be enabled by default.

@opentelemetry-pr-dashboard

This comment has been minimized.

pull Bot pushed a commit to thompson-tomo/opentelemetry-specification that referenced this pull request Sep 28, 2026
Update resource detectors to generate *entities* vs. raw attributes.

- Call out the entities that are generated by named detectors vs.
namespaces.
- Add `env` detector which will support the "environment variable"
resource context propagation defined for entities.
- Updates naming guidance to involve entities.

Note: This should be a *non-breaking change* as the OTLP produces will
only contain additional information, but `Resource` generated using
these named detectors should be exactly the same as before.

Prototype:
- open-telemetry/opentelemetry-java#8464

Relevant Issues:
-
open-telemetry/opentelemetry-configuration#651
- open-telemetry#5209

What this does NOT do:

- Figure out how to have `env` detection built-in. We believe we need to
move from OTEL_RESOURCE_ATTRIBUTES to OTEL_ENTITIES to safely allow
runtime environments to populate ENV variable in ways that will not
clobber other runtimes. We want this migration to be seamless. I expect
this change to declare the named resource detector and we'll later
specify default-on resource detectors. This name would allow
configuration to be used to *disable* ENV-based propagation.
- Add necessary SDK components as these are part of
open-telemetry#5057

---------

Co-authored-by: David Ashpole <dashpole@google.com>
@jack-berg jack-berg changed the title Entity SDK - Initial opt-in SDK features Add experimental SDK entity support and OTLP export Oct 8, 2026
@jack-berg
jack-berg merged commit 6e4eb27 into open-telemetry:main Oct 8, 2026
34 checks passed
@jsuereth
jsuereth deleted the wip-entity-sdk-for-reals branch October 9, 2026 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants