Change process.open_file_descriptors

[braydonk]

Area(s)

area:process

What's missing?

Note: first discussed in #1797

process.open_file_descriptors has 2 problems:

1. The open_ is arguably redundant, since a "file descriptor" is itself a representation of an open file (i.e. there's no such thing as counting closed_file_descriptors)
2. It can be confusing to Windows users, since on Windows you'd be counting Handles, a distinct windows exclusive concept, rather than file_descriptors.

Describe the solution you'd like

I suggest renaming the metric to process.file_descriptors, or process.unix.file_descriptors. At first glance I like unix being in the name, but this would be the first time we use that as a platform name so we'll need to think a bit about that before making that jump.

There will also be a metric called process.windows.handles in the future. Hopefully the presence of this metric will alleviate the platform confusion.

[braydonk]

Marking as GA Blocker since open_file_descriptors is an existing metric in use by instrumentation today.

[lmolkova]

nit, since it's an up-down counter we should avoid pluralization

semantic-conventions/docs/general/naming.md

Lines 252 to 260 in 21c230d

	#### Use `count` Instead of Pluralization for UpDownCounters
	If the value being recorded represents the count of concepts signified
	by the namespace then the metric should be named `count` (within its namespace).
	For example if we have a namespace `system.process` which contains all metrics related
	to the processes then to represent the count of the processes we can have a metric named
	`system.process.count`.

So probably process.file_descriptor.count?

I'm a Windows user, and my subjective and not very-well-though-out reaction is to use the same metric if there are no substantial differences except name.

I also wonder if we could be more approachable and just call it process.open_file.count

[trask]

process.open_file.count

I think you can have multiple open file descriptors for the same file, so could be misleading?

process.open_file_handle.count doesn't seem like the worst idea to me

from https://en.wikipedia.org/wiki/File_descriptor (my emphasis):

In Unix and Unix-like computer operating systems, a file descriptor is a process-unique identifier (handle) for a file

I think I'd also be ok with keeping them as separate metrics in order to stay closer to the domain-specific terminology, e.g.

• unix.process.open_file_descriptor.count
• windows.process.open_file_handle.count

(trying to follow proposed naming guidance in #1708 (comment))

[braydonk]

Finally getting back to this issue in the hopes of unblocking #1838.

---

RE: Relation of terms handle and file descriptor

You do tend to see usage of both terms in Unix documentation/mailing lists, and they are interchangeable... ish.

handle is often used within the process context, i.e. I call open(2) and the thing I have in my program could be called a "handle". According to the open(2) manual (secion Notes -> Open file descriptions), POSIX will use numerous terms to refer to this. However, in general kernel APIs such as the /proc filesystem, file descriptor ends up being the term being used (see the proc_pid_fd(5) manual as well as the previously linked open(2) manual). The kernel itself also definitively uses the term descriptor/fd in their code.

---

RE: Using the same or similar terminology between Unix and Windows.

We currently have the process.handles metric in hostmetricsreceiver and will inevitably adapt it for semantic conventions. A handle in a Windows context can be a file, but can represent lots of other system/kernel objects (see Microsoft docs for more on this, also refer to the full list of object categories a handle can represent).

open_file_handle may end up being a metric we can instrument in Windows. You can technically loop through all the handles a process owns and check which ones represent the Kernel Object category File. This is a semi-expensive check and we didn't have any plans to implement it in Windows, but it's technically possible. That being said, it might be strange to have a metric that is cross-platform, but while the information is logical and easily available in one platform (getting this number in a Unix system is generally trivial and made available) and requiring special APIs and calculations in another (on Windows you need to actively search a process's list of handles and count which ones are File).

Arguably though, this is also a metric with a different level of value on each system. Even in the case of a Linux system (which this metric is exclusive to in right now in hostmetricsreceiver) the value isn't necessarily in the fact that it's specifically "files" because that's a given. You want to keep track of your process' descriptors to ensure it's remaining under the ulimit, and not somehow leaking descriptors. This is also true in Windows, but it's true about all handles. Knowing this information just for files likely doesn't have a great immediate use as a metric. So I am not sure how useful it is to unify when the fundamental use of these metrics is different across platforms as it is.

---

This is still all blocked on the OS namespacing decision, however I'd like to give my recommendation based on what I've written above for the descriptor vs handle thing.

I think the final point around the usefulness of an open_file counter metric of some kind of Windows being dubious is the reason I am inclined to suggest these be two different metrics. I also still stand by that open_ in both of these cases would be redundant, as these are going to be UpDownCounters anyway which implies that any counted instances of handles/descriptors are nominally "open".

I suggest the following:

• process.unix.file_descriptor.count
• process.windows.handle.count

(OS namespace interchangeable based on the outcome of that decision)