Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add User-agent OS attributes #1434

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 4 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/user_agent_os.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: user-agent

# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Add user-agent OS attributes

# 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: [1433]

# (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:
31 changes: 31 additions & 0 deletions docs/attributes-registry/user-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@

# User Agent

- [User-agent Attributes](#user-agent-attributes)
- [User-agent OS Attributes](#user-agent-os-attributes)

## User-agent Attributes

Describes user-agent attributes.
Expand All @@ -19,3 +22,31 @@ Describes user-agent attributes.
**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version`

**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name`

## User-agent OS Attributes

Describes the OS user-agent attributes.
Copy link
Contributor

Choose a reason for hiding this comment

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

Could you please describe the use-case for these attributes? is there any instrumentation or semantic convention that's supposed to populate it?

We usually add attributes along with the convention (span/metric/resource/event) that uses them - this usually results in more specific attribute definition and more clarity for those who want to populate the attribute on other conventions.

So, could we define such convention and/or document the use-case in some other way?

Copy link
Contributor Author

@rogercoll rogercoll Oct 22, 2024

Choose a reason for hiding this comment

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

Could you please describe the use-case for these attributes?

For example, to understand which are the source OSes that are making requests to your system. This could be used from a Nginx Ingress Controller log, which records all requests UserAgent's.

is there any instrumentation or semantic convention that's supposed to populate it?

There is an ongoing PR in the collector: open-telemetry/opentelemetry-collector-contrib#35458

We usually add attributes along with the convention (span/metric/resource/event) that uses them - this usually results in more specific attribute definition and more clarity for those who want to populate the attribute on other conventions.

From the collector point of view, these attributes are agnostic to its location, they will be extracted from any defined context (span/metric/resource/event). I would like to use it to populate a Nginx Ingress Controller event, but it is not defined in Semconv yet (#982). Would it make sense to add a Nginx log example and explain how these attributes could be extracted?


| Attribute | Type | Description | Examples | Stability |
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| `user_agent.os.build_id` | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `user_agent.os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `user_agent.os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `user_agent.os.type` | string | The operating system type. | `windows`; `linux`; `darwin` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `user_agent.os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

`user_agent.os.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value | Description | Stability |
| -------------- | ------------------------------------ | ---------------------------------------------------------------- |
| `aix` | AIX (Advanced Interactive eXecutive) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `darwin` | Apple Darwin | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `dragonflybsd` | DragonFly BSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `freebsd` | FreeBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `hpux` | HP-UX (Hewlett Packard Unix) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `linux` | Linux | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `netbsd` | NetBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `openbsd` | OpenBSD | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `solaris` | SunOS, Oracle Solaris | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `windows` | Microsoft Windows | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `z_os` | IBM z/OS | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
80 changes: 80 additions & 0 deletions model/user-agent/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,83 @@ groups:
using a user-agent for non-browser products, such as microservices with multiple names/versions inside the
`user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align
with `user_agent.name`

- id: registry.user_agent.os
type: attribute_group
display_name: User-agent OS Attributes
brief: "Describes the OS user-agent attributes."
attributes:
- id: user_agent.os.type
type:
members:
- id: windows
value: 'windows'
brief: "Microsoft Windows"
stability: experimental
- id: linux
value: 'linux'
brief: "Linux"
stability: experimental
- id: darwin
value: 'darwin'
brief: "Apple Darwin"
stability: experimental
- id: freebsd
value: 'freebsd'
brief: "FreeBSD"
stability: experimental
- id: netbsd
value: 'netbsd'
brief: "NetBSD"
stability: experimental
- id: openbsd
value: 'openbsd'
brief: "OpenBSD"
stability: experimental
- id: dragonflybsd
value: 'dragonflybsd'
brief: "DragonFly BSD"
stability: experimental
- id: hpux
value: 'hpux'
brief: "HP-UX (Hewlett Packard Unix)"
stability: experimental
- id: aix
value: 'aix'
brief: "AIX (Advanced Interactive eXecutive)"
stability: experimental
- id: solaris
value: 'solaris'
brief: "SunOS, Oracle Solaris"
stability: experimental
- id: z_os
value: 'z_os'
brief: "IBM z/OS"
stability: experimental
brief: >
The operating system type.
stability: experimental
- id: user_agent.os.description
type: string
stability: experimental
brief: >
Human readable (not intended to be parsed) OS version information,
like e.g. reported by `ver` or `lsb_release -a` commands.
examples: ['Microsoft Windows [Version 10.0.18363.778]', 'Ubuntu 18.04.1 LTS']
- id: user_agent.os.name
type: string
stability: experimental
brief: 'Human readable operating system name.'
examples: ['iOS', 'Android', 'Ubuntu']
- id: user_agent.os.version
type: string
stability: experimental
brief: >
The version string of the operating system as defined in
[Version Attributes](/docs/resource/README.md#version-attributes).
examples: ['14.2.1', '18.04.1']
- id: user_agent.os.build_id
type: string
stability: experimental
brief: 'Unique identifier for a particular build or compilation of the operating system.'
examples: ['TQ3C.230805.001.B2', '20E247', '22621']
Loading