Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .chloggen/add-process-executable-entity.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.

# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: enhancement

# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: process

# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Add in a process executable entity to describe the executable being run by the process.

# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
issues: [2655]

# (Optional) One or more lines of additional information to render under the primary note.
# These lines will be padded with 2 spaces and then inserted directly into the document.
# Use pipe (|) for multiline entries.
subtext:
1 change: 1 addition & 0 deletions docs/registry/entities/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ Currently, the following namespaces exist:
| | [otel.scope](otel.md#otel-scope) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Obsoleted. |
| Process | | |
| | [process](process.md#process) | ![Development](https://img.shields.io/badge/-development-blue) |
| | [process.executable](process.md#process-executable) | ![Development](https://img.shields.io/badge/-development-blue) |
| | [process.runtime](process.md#process-runtime) | ![Development](https://img.shields.io/badge/-development-blue) |
| Service | | |
| | [service](service.md#service) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
Expand Down
18 changes: 18 additions & 0 deletions docs/registry/entities/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,24 @@

**[9] `process.title`:** In many Unix-like systems, process title (proctitle), is the string that represents the name or command line of a running process, displayed by system monitoring tools like ps, top, and htop.

## Process Executable

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

**type:** `process.executable`

**Description:** The executable which is being run by the process.

> :warning: This entity definition contains attributes without a role.
> Stable Entities MUST NOT have attributes without a defined role.

| Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
|---|---|---|---|---|---|---|
| Description | [`process.executable.build_id.gnu`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The GNU build ID as found in the `.note.gnu.build-id` ELF section (hex string). | `c89b11207f6479603b0d49bf291c092c2b719293` |
| Description | [`process.executable.build_id.go`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The Go build ID as retrieved by `go tool buildid <go executable>`. | `foh3mEXu7BLZjsN9pOwG/kATcXlYVCDEFouRMQed_/WwRFB1hPo9LBkekthSPG/x8hMC8emW2cCjXD0_1aY` |
| Description | [`process.executable.name`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` |
| Other | [`process.executable.build_id.htlhash`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Profiling specific build ID for executables. See the OTel specification for Profiles for more information. | `600DCAFE4A110000F2BF38C493F5FB92` |

## Process Runtime

**Status:** ![Development](https://img.shields.io/badge/-development-blue)
Expand Down
33 changes: 33 additions & 0 deletions docs/resource/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ linkTitle: Process

- [Process](#process)
- [Selecting process attributes](#selecting-process-attributes)
- [Process executable](#process-executable)
- [Process runtimes](#process-runtimes)
- [Erlang runtimes](#erlang-runtimes)
- [Go runtimes](#go-runtimes)
Expand Down Expand Up @@ -90,6 +91,38 @@ On Windows and other systems where the native format of process commands is a si

`process.args_count` can be additional be provided or instead when sanitization of the arguments is not being performed.

## Process executable

<!-- semconv entity.process.executable -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

**type:** `process.executable`

**Description:** The executable which is being run by the process.

> :warning: This entity definition contains attributes without a role.
> Stable Entities MUST NOT have attributes without a defined role.

| Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
|---|---|---|---|---|---|---|
| Description | [`process.executable.build_id.gnu`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The GNU build ID as found in the `.note.gnu.build-id` ELF section (hex string). | `c89b11207f6479603b0d49bf291c092c2b719293` |
| Description | [`process.executable.build_id.go`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The Go build ID as retrieved by `go tool buildid <go executable>`. | `foh3mEXu7BLZjsN9pOwG/kATcXlYVCDEFouRMQed_/WwRFB1hPo9LBkekthSPG/x8hMC8emW2cCjXD0_1aY` |
| Description | [`process.executable.name`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` |
| Other | [`process.executable.build_id.htlhash`](/docs/registry/attributes/process.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Profiling specific build ID for executables. See the OTel specification for Profiles for more information. | `600DCAFE4A110000F2BF38C493F5FB92` |



<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Process runtimes

<!-- semconv entity.process.runtime -->
Expand Down
14 changes: 14 additions & 0 deletions model/process/entities.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,17 @@ groups:
role: identifying
- ref: process.runtime.description
role: descriptive

- id: entity.process.executable
type: entity
stability: development
name: process.executable
brief: The executable which is being run by the process.
attributes:
- ref: process.executable.name
Copy link
Contributor

Choose a reason for hiding this comment

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

Can you select which ones of these will be identifying or descriptive?

Copy link
Contributor Author

@thompson-tomo thompson-tomo Aug 21, 2025

Choose a reason for hiding this comment

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

Hmm, should the identity attribute values change if the executable is updated to a new version? If so we would probs need an additional attribute for version or everything becomes identity.

Copy link
Contributor

Choose a reason for hiding this comment

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

That's a question for how this entity will be used and tracked in the system.

As I think this entity is MOST relevant to @open-telemetry/profiling-maintainers - I'd like to get there take on what "identity" for an executable should be.

Do you want to group profiles by an executable by "concept" or "by its version"? I suspect it's the later...

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It could be used as either but what I will do is define it without a version (this PR) and create a seperate pr to introduce a new attribute and add it to the entity as identifying as I see a couple of options to address it.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Seperate PR for adding an attribute for executable version #2673.

Copy link
Member

Choose a reason for hiding this comment

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

In profiling, process.executable.build_id.htlhash is used to uniquely identify executables when 1-1 accuracy is needed (e.g. symbolization) but for other cases (e.g. visualization of flamegraphs) one may use process.executable.name, which introduces fuzziness (e.g. multiple different executables, which could be entirely unrelated functionality-wise, with the same executable name collapsed under one entity).

Copy link
Contributor

Choose a reason for hiding this comment

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

It sounds to me like we want the executable to be identified by the build-id, and the name is a descriptive attirbute which can be used for grouping.

@braydonk / @christos68k - I think this is worth further discussion

Copy link
Contributor Author

@thompson-tomo thompson-tomo Nov 4, 2025

Choose a reason for hiding this comment

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

It's worth noting that it's not uncommon but possible for an executable to be renamed while a process is running. Based on the instrumentation instructions for this attribute, someone mving an executable during a process's runtime will result in a new name being retrieved. I haven't tried on Windows, but I'm pretty sure that renaming an executable while a process running will result in a new value from GetProcessImageFileNameW, so the same would apply if I'm remembering correctly (needs validation).

@braydonk Actually if the path to the executable is all that is changed and the file name renames the same the value of the name attribute wouldn't change.

I am more than happy to introduce a new attribute to use as the identifying attribute.

Howabout I set the name to descriptive in this PR or even leave it unset & we use #2673 for defining a new identifying attribute.

Copy link
Contributor

Choose a reason for hiding this comment

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

I think it's important that the profiling SIG make the decision for what the identifying attribute(s) should be. Based on my discussion with them we at least agreed on the name not being identifying so we'll start with that, and it seems like the attribute @christos68k mentioned above is likely the best candidate, but it sounded like the Profiling SIG had other things to work through before making the final decision if I understood correctly.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sure I have made the name attribute to be descriptive and the htlhash to not have a role so that we can discuss seperately if htlhash is the identity and the description is updated. Let me know if this PR nneeds any additional changes.

role: descriptive
- ref: process.executable.build_id.gnu
role: descriptive
- ref: process.executable.build_id.go
role: descriptive
- ref: process.executable.build_id.htlhash
Loading