From 1aa6a5c024f806ca15260c2e83bee2c1d63a50b2 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 10 Jan 2025 03:42:18 +0100 Subject: [PATCH 01/39] Messaging: Align span kind in example tables with the spec (#1730) --- docs/messaging/messaging-spans.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index cda4fcfa54..0d13af08bd 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -608,7 +608,7 @@ flowchart LR; | Links | | | Span Send A, Span Send B | | Link attributes | | | Span Send A: `messaging.message.id`: `"a1"` | | | | | Span Send B: `messaging.message.id`: `"a2"` | -| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | +| SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` | | `server.address` | `"ms"` | `"ms"` | `"ms"` | | `server.port` | `1234` | `1234` | `1234` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | @@ -657,7 +657,7 @@ flowchart LR; | Span name | `create Q` | `create Q` | `send Q` | `poll Q` | `poll Q` | | Parent | | | | | | | Links | | | | Span Create A | Span Create B | -| SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` | `CONSUMER` | `CONSUMER` | +| SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` | `CLIENT` | `CLIENT` | | `server.address` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | | `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | @@ -702,7 +702,7 @@ flowchart LR; | Span name | `send Q` | `poll Q` | `poll Q` | | Parent | | | | | Links | | Span Publish | Span Publish | -| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | +| SpanKind | `PRODUCER` | `CLIENT` | `CLIENT` | | `server.address` | `"ms"` | `"ms"` | `"ms"` | | `server.port` | `1234` | `1234` | `1234` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | From f965a2298a1672c68acdcef93224241fae7f6205 Mon Sep 17 00:00:00 2001 From: Dave Cadwallader Date: Fri, 10 Jan 2025 06:21:31 -0800 Subject: [PATCH 02/39] Add Oracle Cloud Infrastructure as Cloud Provider (#1720) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/.oracle_cloud.yaml | 22 ++++++++++++++++++++++ docs/attributes-registry/cloud.md | 3 +++ docs/resource/cloud.md | 3 +++ model/cloud/registry.yaml | 12 ++++++++++++ 4 files changed, 40 insertions(+) create mode 100644 .chloggen/.oracle_cloud.yaml diff --git a/.chloggen/.oracle_cloud.yaml b/.chloggen/.oracle_cloud.yaml new file mode 100644 index 0000000000..fb402ce405 --- /dev/null +++ b/.chloggen/.oracle_cloud.yaml @@ -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: cloud + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add Oracle Cloud Infrastructure to Semantic Conventions + +# 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: [1658] + +# (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: diff --git a/docs/attributes-registry/cloud.md b/docs/attributes-registry/cloud.md index ceb19dbf4e..0637765ac4 100644 --- a/docs/attributes-registry/cloud.md +++ b/docs/attributes-registry/cloud.md @@ -74,6 +74,8 @@ The following well-known definitions MUST be used if you set this attribute and | `gcp_kubernetes_engine` | Google Cloud Kubernetes Engine (GKE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gcp_openshift` | Red Hat OpenShift on Google Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `ibm_cloud_openshift` | Red Hat OpenShift on IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle_cloud_compute` | Compute on Oracle Cloud Infrastructure (OCI) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle_cloud_oke` | Kubernetes Engine (OKE) on Oracle Cloud Infrastructure (OCI) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud_cvm` | Tencent Cloud Cloud Virtual Machine (CVM) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -90,4 +92,5 @@ The following well-known definitions MUST be used if you set this attribute and | `gcp` | Google Cloud Platform | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `heroku` | Heroku Platform as a Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `ibm_cloud` | IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle_cloud` | Oracle Cloud Infrastructure (OCI) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud` | Tencent Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index 0abfe90b1a..0c5fc7cfea 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -78,6 +78,8 @@ The following well-known definitions MUST be used if you set this attribute and | `gcp_kubernetes_engine` | Google Cloud Kubernetes Engine (GKE) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gcp_openshift` | Red Hat OpenShift on Google Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `ibm_cloud_openshift` | Red Hat OpenShift on IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle_cloud_compute` | Compute on Oracle Cloud Infrastructure (OCI) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle_cloud_oke` | Kubernetes Engine (OKE) on Oracle Cloud Infrastructure (OCI) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud_cvm` | Tencent Cloud Cloud Virtual Machine (CVM) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -94,6 +96,7 @@ The following well-known definitions MUST be used if you set this attribute and | `gcp` | Google Cloud Platform | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `heroku` | Heroku Platform as a Service | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `ibm_cloud` | IBM Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `oracle_cloud` | Oracle Cloud Infrastructure (OCI) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `tencent_cloud` | Tencent Cloud | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/cloud/registry.yaml b/model/cloud/registry.yaml index 906092d52c..d248312297 100644 --- a/model/cloud/registry.yaml +++ b/model/cloud/registry.yaml @@ -32,6 +32,10 @@ groups: value: 'ibm_cloud' brief: 'IBM Cloud' stability: experimental + - id: 'oracle_cloud' + value: 'oracle_cloud' + brief: 'Oracle Cloud Infrastructure (OCI)' + stability: experimental - id: 'tencent_cloud' value: 'tencent_cloud' brief: 'Tencent Cloud' @@ -201,6 +205,14 @@ groups: value: 'ibm_cloud_openshift' brief: Red Hat OpenShift on IBM Cloud stability: experimental + - id: oracle_cloud_compute + value: 'oracle_cloud_compute' + brief: Compute on Oracle Cloud Infrastructure (OCI) + stability: experimental + - id: oracle_cloud_oke + value: 'oracle_cloud_oke' + brief: Kubernetes Engine (OKE) on Oracle Cloud Infrastructure (OCI) + stability: experimental - id: tencent_cloud_cvm value: 'tencent_cloud_cvm' brief: Tencent Cloud Cloud Virtual Machine (CVM) From 34b76907a5fa7cb0796933d3d1af9732b1c70462 Mon Sep 17 00:00:00 2001 From: Braydon Kains <93549768+braydonk@users.noreply.github.com> Date: Fri, 10 Jan 2025 14:31:43 -0500 Subject: [PATCH 03/39] [chore] System Semantic Conventions Non-Normative Guidance (#1618) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .github/CODEOWNERS | 1 + .prettierignore | 4 + .../groups/system/design-philosophy.md | 260 ++++++++++++++++++ docs/non-normative/groups/system/use-cases.md | 115 ++++++++ package.json | 13 +- 5 files changed, 392 insertions(+), 1 deletion(-) create mode 100644 docs/non-normative/groups/system/design-philosophy.md create mode 100644 docs/non-normative/groups/system/use-cases.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0f57fbc6be..608f31b696 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -53,6 +53,7 @@ /model/os/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers /model/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers /model/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/docs/non-normative/groups/system @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers # Mobile semantic conventions /docs/mobile/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers diff --git a/.prettierignore b/.prettierignore index c7137972a9..d71d790b75 100644 --- a/.prettierignore +++ b/.prettierignore @@ -7,6 +7,10 @@ !/docs/cloud*/** !/docs/attributes-registry* !/docs/attributes-registry*/** +!/docs/non-normative* +!/docs/non-normative/groups* +!/docs/non-normative/groups/system* +!/docs/non-normative/groups/system*/** /model /schemas CHANGELOG.md \ No newline at end of file diff --git a/docs/non-normative/groups/system/design-philosophy.md b/docs/non-normative/groups/system/design-philosophy.md new file mode 100644 index 0000000000..de26995447 --- /dev/null +++ b/docs/non-normative/groups/system/design-philosophy.md @@ -0,0 +1,260 @@ +# System Semantic Conventions: Instrumentation Design Philosophy + +The System Semantic Conventions are caught in a strange dichotomy that is unique +among other semconv groups. While we want to make sure we cover obvious generic +use cases, monitoring system health is a very old practice with lots of +different existing strategies. While we can cover the basic use cases in cross +platform ways, we want to make sure that users who specialize in certain +platforms aren't left in the lurch; if users aren't given recommendations for +particular types of data that isn't cross-platform and universal, they may come +up with their own disparate ideas for how that instrumentation should look, +leading to the kind of fracturing that the semantic conventions should be in +place to avoid. + +The following sections address some of the most common instrumentation design +questions, and how we as a working group have opted to address them. In some +cases they are unique to the common semantic conventions guidance due to our +unique circumstance, and those cases will be called out specifically. + +## Namespaces + +Relevant discussions: +[\#1161](https://github.com/open-telemetry/semantic-conventions/issues/1161) + +The System Semantic Conventions generally cover the following namespaces: + +- `system` +- `process` +- `host` +- `memory` +- `network` +- `disk` +- `memory` +- `os` + +Deciding on the namespace of a metric/attribute is generally informed by the +following belief: + +**The namespace of a metric/attribute should logically map to the Operating +System concept being considered as the instrumentation source.** + +The most obvious example of this is with language runtime metrics and `process` +namespace metrics. Many of these metrics are very similar; most language +runtimes provide some manner of `cpu.time`, `memory.usage` and similar metrics. +If we were considering de-duplication as the top value in our design, it would +follow that `process.cpu.time` and `process.memory.usage` should simply be +referenced by any language runtime that might produce those metrics. However, as +a working group we believe it is important that `process` namespace and runtime +namespace metrics remain separate, because `process` metrics are meant to +represent an **OS-level process as the instrumentation source**, whereas runtime +metrics represent **the language runtime as the instrumentation source**. + +In some cases this is simply a matter of making the instrumentation's purpose as +clear as possible, but there are cases where attempts to share definitions +across distinct instrumentation sources poses the potential for a clash. The +concrete example of a time we accepted this consequence is with `cpu.mode`; the +decision was to +[unify all separate instances of `*.cpu.state` attributes into one shared `cpu.mode` attribute](https://github.com/open-telemetry/semantic-conventions/issues/1139). +The consequence of this is that `cpu.mode` needs to have a broad enum in its +root definition, with special exemptions in each different `ref` of `cpu.mode`, +since `cpu.mode` used in `process.cpu.time` vs `container.cpu.time` vs +`system.cpu.time` etc. has different subsets of the overall enum values. We +decided as a group to accept the consequence in this case, however it isn't +something we're keen on dealing with all over system semconv, as the +instrumentation ends up polluted with so many edge cases in each namespace that +it defeats the purpose of sharing the attribute in the first place. + +## Two Class Design Strategy + +Relevant discussions: +[\#1403 (particular comment)](https://github.com/open-telemetry/semantic-conventions/issues/1403#issuecomment-2368815634) + +We are considering two personas for system semconv instrumentation. If we have a +piece of instrumentation, we decide which persona it is meant for and use that +to make the decision for how we should name/treat that piece of instrumentation. + +### General Class: A generalized cross-platform use case we want any user of instrumentation to be able to easily access + +When instrumentation is meant for the General Class, we will strive to make the +names and examples as prescriptive as possible. This instrumentation is what +will drive the most important use cases we really want to cover with the system +semantic conventions. Things like dashboards, alerts, and broader o11y setup +tutorials will largely feature General Class instrumentation covering the [basic +use cases][use cases doc] we have laid out as a group. We want this +instrumentation to be very clear exactly how and when they should be used. +General Class instrumentation will be recommended as **on by default**. + +### Specialist Class: A more specific use case that specialists could enable to get more in-depth information that they already understand how to use + +When instrumentation falls into the Specialist Class, we are assuming the target +audience is already familiar with the concept and knows exactly what they are +looking for and why. The goal for Specialist Class instrumentation is to ensure +that users who have very specific and detailed needs are still covered by our +semantic conventions so they don't need to go out of their way coming up with +their own, risking the same kind of disparate instrumentation problem that +semantic conventions are intended to solve. The main differences in how we +handle Speciialist Class instrumentation are: + +1. The names and resulting values will map directly to what a user would expect + hunting down the information themselves. We will rarely be prescriptive in + how the information should be used or how it should be broken down. For + example, a metric to represent a process's cgroup would have the resulting + value match exactly to what the result would be if the user called + `cat /proc/PID/cgroup`. +2. If a piece of instrumentation is specific to a particular operating system, + the name of the operating system will be in the instrumentation name. See + [Operating System in names](#operating-system-in-names) for more information. + For example, a metric for a process's cgroup would be `process.linux.cgroup`, + given that cgroups are a specific Linux kernel feature. + +### Examples + +Some General Class examples: + +- Memory/CPU usage and utilization metrics +- General disk and network metrics +- Universal system/process information (names, identifiers, basic specs) + +Some Specialist Class examples: + +- Particular Linux features like special process/system information in procfs + (see things like + [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc_meminfo.5.html) or + [cgroups](https://man7.org/linux/man-pages/man7/cgroups.7.html)) +- Particular Windows features like special process information (see things like + [Windows Handles](https://learn.microsoft.com/windows/win32/sysinfo/about-handles-and-objects), + [Process Working Set](https://learn.microsoft.com/windows/win32/procthread/process-working-set)) +- Niche process information like open file descriptors, page faults, etc. + +## Instrumentation Design Guide + +When designing new instrumentation we will follow these steps as closely as +possible: + +### Choosing Instrumentation Class + +In System Semantic Conventions, the most important questions when deciding +whether a piece of instrumentation is General or Specialist would be: + +- Is it cross-platform? +- Does it support our [most important use cases][use cases doc] then we will + make it general class + +The answer to both these questions will likely need to be "Yes" for the +instrumentation to be considered General Class. Since the General Class +instrumentation is what we expect the widest audience to use, we will need to +scrutinize it more closely to ensure all of it is as necessary and useful as +possible. + +If the answer to either one of these is "No", then we will likely consider it +Specialist Class. + +### Naming + +For General Class, choose a name that most accurately descibes the general +concept without biasing to a platform. Lean towards simplicity where possible, +as this is the instrumentation that will be used by the widest audience; we want +it to be as clear to understand and ergonomic to use as possible. + +For Specialist Class, choose a name that most directly matches the words +generally used to describe the concept in context. Since this instrumentation +will be optional, and likely sought out by the people who already know exactly +what they want out of it, we can prioritize matching the names as closely to +their definition as possible. For specialist class metrics that are platform +exclusive, we will include the OS in the namespace as a sub-namespace (not the +root namespace) if it is unlikely that the same metric name could ever be +applied in a cross-platform manner. See +[this section](#operating-system-in-names) for more details. + +### Value + +For General Class, the value we can be prescriptive with the value of the +instrumentation. We want to ensure General Class instrumentation most closely +matches our vision for our general use cases, and we want to ensure that users +who are not specialists and just want the most important basic information can +acquire it as easily as possible using out-of-the-box semconv instrumentation. +This means we are more likely within General Class instrumentation to make +judgements about exactly what the value should be, and whether the value should +be reshaped by instrumentation in any case when pulling the values from sources +if it serves general purpose use cases. + +For Specialist Class, we should strive not to be prescriptive and instead match +the concept being modeled as closely as possible. We expect specialist class +instrumentation to be enabled by the people who already understand it. In a +System Semconv context, these may be things a user previously gathered manually +or through existing OS tools that they want to model as OTLP. + +### Case study: `process.cgroup` + +Relevant discussions: +[\#1357](https://github.com/open-telemetry/semantic-conventions/issues/1357), +[\#1364 (particular thread)](https://github.com/open-telemetry/semantic-conventions/pull/1364#discussion_r1730743509) + +In the `hostmetricsreceiver`, there is a Resource Attribute called +`process.cgroup`. How should this attribute be adopted in System Semantic +Conventions? + +Based on our definitions, this attribute would fall under Specialist Class: + +- `cgroups` are a Linux-specific feature +- It is not directly part of any of the default out-of-the-box usecases we want + to cover + +In this attribute's case, there are two important considerations when deciding +on the name: + +- The attribute is specialist class +- It is Linux exclusive, and is unlikely to ever be introduced in other + operating systems since the other major platforms have their own versions of + it (Windows Job Objects, BSD Jails, etc) + +This means we should pick a name that matches the verbiage used by specialists +in context when referring to this concept. The way you would refer to this would +be "a process's cgroup, collected from `/proc//cgroup`". So we would start +with the name `process.cgroup`. We also determined that this attribute is +Linux-exclusive and are confident it will remain as such, so we land on the name +`process.linux.cgroup`. + +Since this metric falls under Specialist Class, we don't want to be too +prescriptive about the value. A user who needs to know the `cgroup` of a process +likely already has a pretty good idea of how to interpret it and use it further, +and it would not be worth it for this Working Group to try and come up with +every possible edge case for how it might be used. It is much simpler for this +attribute, insofar as it falls under our purview, to simply reflect the value +from the OS, i.e. the direct value from `cat /proc//cgroup`. With cgroups +in particular, there is high likelihood that more specialized semconv +instrumentation could be developed, particularly in support of more specialized +container runtime or systemd instrumentation. It's more useful for a working +group developing special instrumentation that leverages cgroups to be more +prescriptive about how the cgroup information should be interpreted and broken +down with more specificity. + +## Operating System in names + +Relevant discussions: +[\#1255](https://github.com/open-telemetry/semantic-conventions/issues/1255), +[\#1364](https://github.com/open-telemetry/semantic-conventions/pull/1364#discussion_r1852465994) + +Monitoring operating systems is an old practice, and there are numerous heavily +differing approaches within different platforms. There are lots of metrics, even +considering common stats like memory usage, where there are platform-exclusive +pieces of information that are only valuable to those who specialize in that +platform. + +Thus we have decided that any instrumentation that is: + +1. Specific to a particular operating system +2. Not meant to be part of what we consider our most important general use cases + +will have the Operating System name as part of the namespace. + +For example, there may be `process.linux`, `process.windows`, or `process.posix` +names for metrics and attributes. We will not have root `linux.*`, `windows.*`, +or `posix.*` namespaces. This is because of the principle we’re trying to uphold +from the [Namespaces section](#namespaces); we still want the instrumentation +source to be represented by the root namespace of the attribute/metric. If we +had OS root namespaces, different sources like `system`, `process`, etc. could +get very tangled within each OS namespace, defeating the intended design +philosophy. + +[use cases doc]: ./use-cases.md diff --git a/docs/non-normative/groups/system/use-cases.md b/docs/non-normative/groups/system/use-cases.md new file mode 100644 index 0000000000..99d8fabf1b --- /dev/null +++ b/docs/non-normative/groups/system/use-cases.md @@ -0,0 +1,115 @@ +# **System Semantic Conventions: General Use Cases** + +This document is a collection of the use cases that we want to cover with the +System Semantic Conventions. The use cases outlined here inform the working +group’s decisions around what instrumentation is considered **required**. Use +cases in this document will be stated in a generic way that does not refer to +any potentially existing instrumentation in semconv as of writing, such that +when we do dig into specific instrumentation, we understand their importance +based on our holistic view of expected use cases. + +## _Legend_ + +`General Information` \= The information that should be discoverable either +through the entity, metrics, or metric attributes. + +`Dashboard` \= The information that should be attainable through metrics to +create a comprehensive dashboard. + +`Alerts` \= Some examples of common alerts that should be creatable with the +available information. + +## **Host** + +A user should be able to monitor the health of a host, including monitoring +resource consumption, unexpected errors due to resource exhaustion or +malfunction of core components of a host or fleet of hosts (network stack, +memory, CPU, etc.). + +### General Information + +- Machine name +- ID (relevant to its context, could be a cloud provider ID or just base machine + ID) +- OS information (platform, version, architecture, etc) +- CPU Information +- Memory Capacity + +### Dashboard + +- Memory utilization +- CPU utilization +- Disk utilization +- Disk throughput +- Network traffic + +### Alerts + +- VM is down unexpectedly +- Network activity spikes unexpectedly +- Memory/CPU/Disk utilization goes above a % threshold + +## Notes + +The alerts in particular should be capable of being uniformly applied to a +heterogenous fleet of hosts. We will value the nature of cross-platform +instrumentation to allow for effective alerting across a fleet regardless of the +potential mixture of operating system platforms within it. + +The term `host` can mean different things in other contexts: + +- The term `host` in a network context, a central machine that many others are + networked to, or the term `host` in a virtualization context +- The term `host` in a virtualization context, something that is hosting virtual + guests such as VMs or containers + +In this context, a host is generally considered to be some individual machine, +physical or virtual. This can be extra confusing, because a unique machine +`host` can also be a network `host` or virtualization `host` at the same time. +This is a complexity we will have to accept due to the fact that the `host` +namespace is deeply embedded in existing OpenTelemetry instrumentation and +general verbiage. To the best of our ability, network and virtualization `host` +instrumentation will be kept distinct by being within other namespaces that +clearly denote which version of the term `host` is being referred to, while the +root `host` namespace will refer to an individual machine. + +## **Process** + +A user should be able to monitor the health of an arbitrary process using data +provided by the OS. Reasons a user may want this: + +1. The process they want to monitor doesn't have in-process runtime-specific + instrumentation enabled or is not instrumentable at all, such as an antivirus + or another background process. +2. They are monitoring lots of processes and want to have a set of uniform + instrumentation for all of them. +3. Personal preference/legacy reasons; they might already be using OS signals to + monitor stuff and it's an easier lift for them to move to basic process + instrumentation, then move to other specific semconv over time. + +### General Information + +- Process name +- Pid +- User/owner + +### Dashboard + +- Physical Memory usage and/or utilization +- Virtual Memory usage +- CPU usage and/or utilization +- Disk throughput +- Network throughput + +### Alert + +- Process stops unexpectedly +- Memory/CPU usage/utilization goes above a threshold +- Memory exclusively rises over a period of time (memory leak detection) + +### Notes + +On top of alerts and dashboards, we will also consider the basic benchmarking of +a process to be a general usecase. The basic cross platform stats that can be +provided in a cross-platform manner can also be effectively used for this, and +we will consider that when making decisions about process instrumentation. diff --git a/package.json b/package.json index 6e32c045d4..838e610634 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,17 @@ "prettier": "^3.0.0" }, "prettier": { - "proseWrap": "preserve" + "proseWrap": "preserve", + "overrides": [ + { + "files": [ + "**/non-normative/groups/system/**/*.md" + ], + "options": { + "printWidth": 80, + "proseWrap": "always" + } + } + ] } } From cb3a6db7ca115f6ef8400d10bb7f9b194ba8dcc9 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 10 Jan 2025 16:40:32 -0800 Subject: [PATCH 04/39] Add profiling approvers to CODEOWNERS (#1738) Co-authored-by: Liudmila Molkova --- .github/CODEOWNERS | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 608f31b696..015071eba4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -110,6 +110,10 @@ /docs/feature-flags/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-feature-flag-approvers /model/feature-flags/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-feature-flag-approvers +# Profiling semantic conventions +/docs/general/profiles.md @open-telemetry/specs-semconv-approvers @open-telemetry/profiling-approvers +/model/profile/ @open-telemetry/specs-semconv-approvers @open-telemetry/profiling-approvers + # Tooling /policies/ @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-approvers /policies_test/ @open-telemetry/specs-semconv-approvers @open-telemetry/weaver-approvers From 991d6caa40f5b25352ac3f772981662870e96faa Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 14 Jan 2025 11:28:13 +0000 Subject: [PATCH 05/39] Bump go.opentelemetry.io/build-tools/chloggen from 0.15.0 to 0.16.0 in /internal/tools (#1733) Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- internal/tools/go.mod | 3 ++- internal/tools/go.sum | 8 ++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/internal/tools/go.mod b/internal/tools/go.mod index 075a53d8c9..6958d76420 100644 --- a/internal/tools/go.mod +++ b/internal/tools/go.mod @@ -1,10 +1,11 @@ module github.com/open-telemetry/opentelemetry-specification/internal/tools go 1.22 +toolchain go1.22.5 require ( github.com/client9/misspell v0.3.4 - go.opentelemetry.io/build-tools/chloggen v0.15.0 + go.opentelemetry.io/build-tools/chloggen v0.16.0 ) require ( diff --git a/internal/tools/go.sum b/internal/tools/go.sum index 051099d8e8..3bd9909951 100644 --- a/internal/tools/go.sum +++ b/internal/tools/go.sum @@ -12,10 +12,10 @@ github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM= github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y= github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= -github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg= -github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= -go.opentelemetry.io/build-tools/chloggen v0.15.0 h1:G5UeYUgP6x4QXie0yNs/6TjK9nCuuVXgXeDWE9/cxQQ= -go.opentelemetry.io/build-tools/chloggen v0.15.0/go.mod h1:oovDPiOQS4iruTVH469/68hEYjWC48c8u+qJpWJc8Eg= +github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= +github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +go.opentelemetry.io/build-tools/chloggen v0.16.0 h1:iuotHxlcK46JJtQLdwQPsC5dcAygeOL116d2akCv8M8= +go.opentelemetry.io/build-tools/chloggen v0.16.0/go.mod h1:Wk92v9Wsv36sXYi7hOg3ndeeLKmKBu0/kgB7wcaeqJg= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= From 0da8d8ab7eec28ce81aed6a33bc2e9d8d2e16f9a Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 15 Jan 2025 10:26:49 +0100 Subject: [PATCH 06/39] [chore] Fix go mod in tools (#1746) --- internal/tools/go.mod | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/internal/tools/go.mod b/internal/tools/go.mod index 6958d76420..babd34a620 100644 --- a/internal/tools/go.mod +++ b/internal/tools/go.mod @@ -1,7 +1,8 @@ module github.com/open-telemetry/opentelemetry-specification/internal/tools -go 1.22 -toolchain go1.22.5 +go 1.22.0 + +toolchain go1.23.4 require ( github.com/client9/misspell v0.3.4 From 7bffed6dee8dc82e973e0e84b101ec62c699613a Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 15 Jan 2025 10:49:55 +0100 Subject: [PATCH 07/39] RabbitMQ: Specify how to populate `messaging.destination.name` (#1531) --- .chloggen/rabbitmq-destination-name.yaml | 4 ++ docs/messaging/rabbitmq.md | 47 +++++++++++++----------- model/messaging/spans.yaml | 16 ++++++++ 3 files changed, 46 insertions(+), 21 deletions(-) create mode 100755 .chloggen/rabbitmq-destination-name.yaml diff --git a/.chloggen/rabbitmq-destination-name.yaml b/.chloggen/rabbitmq-destination-name.yaml new file mode 100755 index 0000000000..2d795f1b44 --- /dev/null +++ b/.chloggen/rabbitmq-destination-name.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: messaging +note: "RabbitMQ: Specify how to populate `messaging.destination.name`" +issues: [1529] diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 2e00ee1954..779b3856b7 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -40,9 +40,6 @@ The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and ov ## RabbitMQ attributes -In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. -`messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used. - @@ -52,21 +49,34 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| +| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [1] | `direct_logs:warning`; `logs` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [2] | `MyQueue`; `MyTopic` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [3] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.destination.routing_key`](/docs/attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | `Conditionally Required` If not empty. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.message.delivery_tag`](/docs/attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | `Conditionally Required` When available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.message.conversation_id`](/docs/attributes-registry/messaging.md) | string | Message [correlation Id](https://www.rabbitmq.com/tutorials/tutorial-six-java#correlation-id) property. | `MyConversationId` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. [6] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. [5] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [8] | `1439` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [7] | `1439` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `messaging.destination.name`:** In RabbitMQ, the destination is defined by an *exchange*, a *routing key* and for consumers, a *queue*. + +`messaging.destination.name` SHOULD be set to: + +- **On the producer side**: `{exchange}:{routing key}` when both values are present and non-empty. +When only one is available, only that value SHOULD be used. E.g., `{exchange}` or `{routing key}`. +Otherwise: `amq.default` when the default exchange is used and no routing key is provided -**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. +- **On the consumer side**: `{exchange}:{routing key}:{queue}` when all values are present and non-empty. +If any has an empty value (e.g., the default exchange is used) it SHOULD be omitted. +For cases when `{routing key}` and `{queue}` are equal, only one of them SHOULD +be used, e.g., `{exchange}:{routing key}`. + +**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. When `error.type` is set to a type (e.g., an exception type), its canonical class name identifying the type within the artifact SHOULD be used. @@ -86,20 +96,15 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `messaging.destination.name`:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If -the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. - -**[3] `messaging.destination.name`:** If span describes operation on a single message or if the value applies to all messages in the batch. - -**[4] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality. +**[3] `messaging.operation.type`:** If a custom value is used, it MUST be of low cardinality. -**[5] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. +**[4] `server.address`:** Server domain name of the broker if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. -**[6] `network.peer.address`:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. +**[5] `network.peer.address`:** If an operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[8] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[7] `messaging.message.body.size`:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. The following attributes can be important for making sampling decisions diff --git a/model/messaging/spans.yaml b/model/messaging/spans.yaml index a5b76e0b0b..2055823d09 100644 --- a/model/messaging/spans.yaml +++ b/model/messaging/spans.yaml @@ -118,6 +118,22 @@ groups: Message [correlation Id](https://www.rabbitmq.com/tutorials/tutorial-six-java#correlation-id) property. - ref: messaging.message.body.size requirement_level: opt_in + - ref: messaging.destination.name + note: | + In RabbitMQ, the destination is defined by an *exchange*, a *routing key* and for consumers, a *queue*. + + `messaging.destination.name` SHOULD be set to: + + - **On the producer side**: `{exchange}:{routing key}` when both values are present and non-empty. + When only one is available, only that value SHOULD be used. E.g., `{exchange}` or `{routing key}`. + Otherwise: `amq.default` when the default exchange is used and no routing key is provided + + - **On the consumer side**: `{exchange}:{routing key}:{queue}` when all values are present and non-empty. + If any has an empty value (e.g., the default exchange is used) it SHOULD be omitted. + For cases when `{routing key}` and `{queue}` are equal, only one of them SHOULD + be used, e.g., `{exchange}:{routing key}`. + examples: ['direct_logs:warning', 'logs'] + requirement_level: required - id: messaging.kafka type: attribute_group From 527cb4e92a44351e082448b6c2962a0057d6690b Mon Sep 17 00:00:00 2001 From: Alexandra Konrad Date: Wed, 15 Jan 2025 16:08:14 +0100 Subject: [PATCH 08/39] [chore] update enum rule to include all stability types (#1731) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Co-authored-by: Liudmila Molkova --- policies/compatibility.rego | 9 ++- policies_test/compatibility_test.rego | 84 ++++++++++++++++++++++++++- 2 files changed, 87 insertions(+), 6 deletions(-) diff --git a/policies/compatibility.rego b/policies/compatibility.rego index f8483ca4b3..77d01a8b23 100644 --- a/policies/compatibility.rego +++ b/policies/compatibility.rego @@ -211,15 +211,14 @@ deny contains back_comp_violation(description, group_id, attr.name) if { description := sprintf("Enum '%s' had stable value '%s', but is now '%s'", [attr.name, member.value, nmember.value]) } -# Rule: Detect Stable Enum members missing +# Rule: Detect missing Enum members # -# This rule checks for enum values that were stable in the baseline registry -# but are no longer have the same values in the current registry. Once stable, -# enum values remain forever but may be deprecated. +# This rule checks for missing enum values that were present in the baseline registry +# but no longer exist in the current registry. Once added, regardless of their stability, +# enum values must remain in the registry but may be marked as deprecated. deny contains back_comp_violation(description, group_id, attr.name) if { # Find data we need to enforce: Enums in baseline/current. some attr in baseline_attributes - attr.stability == "stable" some nattr in registry_attributes attr.name == nattr.name is_enum(attr) diff --git a/policies_test/compatibility_test.rego b/policies_test/compatibility_test.rego index 5976e02c54..7f599b94f0 100644 --- a/policies_test/compatibility_test.rego +++ b/policies_test/compatibility_test.rego @@ -345,7 +345,7 @@ test_attribute_enum_member_value_change if { } } -# Check stable attribute enum member values changing +# Check enum member missing for attributes of any stability level test_attribute_enum_member_missing if { count(deny) > 0 with data.semconv as { "registry_baseline_groups": [{ @@ -429,6 +429,88 @@ test_attribute_enum_member_missing if { "test.missing": "registry.test" } } + count(deny) > 0 with data.semconv as { + "registry_baseline_groups": [{ + "id": "registry.test", + "type": "attribute_group", + "attributes": [{ + "name": "test.missing", + "stability": "stable", + "type": { + "members": [{ + "id": "test", + "value": "test", + "stability": "experimental", + }, { + "id": "missing", + "value": "missing", + "stability": "experimental", + }] + }, + }] + }], + "registry_groups": [{ + "id": "registry.test", + "type": "attribute_group", + "attributes": [{ + "name": "test.missing", + "stability": "stable", + "type": { + "members": [{ + "id": "test", + "value": "test", + "stability": "experimental", + }] + }, + }] + }], + "baseline_group_ids_by_attribute": { + "test.missing": "registry.test" + } + } + count(deny) == 0 with data.semconv as { + "registry_baseline_groups": [{ + "id": "registry.test", + "type": "attribute_group", + "attributes": [{ + "name": "test.missing", + "stability": "stable", + "type": { + "members": [{ + "id": "test", + "value": "test", + "stability": "experimental", + }, { + "id": "missing", + "value": "missing", + "stability": "experimental", + }] + }, + }] + }], + "registry_groups": [{ + "id": "registry.test", + "type": "attribute_group", + "attributes": [{ + "name": "test.missing", + "stability": "stable", + "type": { + "members": [{ + "id": "test", + "value": "test", + "stability": "experimental", + }, { + "id": "missing", + "value": "missing", + "stability": "experimental", + }] + }, + }] + }], + "baseline_group_ids_by_attribute": { + "test.missing": "registry.test" + } + } } # Check that metrics cannot be removed. From 8d9d4a1ce84b060e4d13b5f44b3495648767deb5 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 15 Jan 2025 08:52:55 -0800 Subject: [PATCH 09/39] Fix small typos (#1745) --- docs/database/README.md | 2 +- docs/database/database-metrics.md | 2 +- docs/database/database-spans.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/database/README.md b/docs/database/README.md index 361708dbe7..488621a3d4 100644 --- a/docs/database/README.md +++ b/docs/database/README.md @@ -24,7 +24,7 @@ database metrics and logs. > metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. -> If the list of values includes: +> The list of values includes: > * `database` - emit the new, stable database conventions, > and stop emitting the old experimental database conventions > that the instrumentation emitted previously. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index de86f04111..47412d1ac3 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -40,7 +40,7 @@ linkTitle: Metrics > metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. -> If the list of values includes: +> The list of values includes: > * `database` - emit the new, stable database conventions, > and stop emitting the old experimental database conventions > that the instrumentation emitted previously. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index ac7f2c1931..dcd4ec2202 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -33,7 +33,7 @@ linkTitle: Client Calls > metric and span names, and unit of measure. > * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` > in the existing major version which is a comma-separated list of values. -> If the list of values includes: +> The list of values includes: > * `database` - emit the new, stable database conventions, > and stop emitting the old experimental database conventions > that the instrumentation emitted previously. From bcb052e03ed76eb9e3f28b10ee9bb76ab967a409 Mon Sep 17 00:00:00 2001 From: Guangya Liu Date: Thu, 16 Jan 2025 08:23:27 -0500 Subject: [PATCH 10/39] [chore] updated changelog for gen-ai (#1750) Signed-off-by: Guangya Liu --- .chloggen/1655.yaml | 2 +- .chloggen/1719.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.chloggen/1655.yaml b/.chloggen/1655.yaml index d15da0a393..d833884e93 100644 --- a/.chloggen/1655.yaml +++ b/.chloggen/1655.yaml @@ -7,7 +7,7 @@ change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: genai +component: gen-ai # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: | diff --git a/.chloggen/1719.yaml b/.chloggen/1719.yaml index efcabfa174..74ed83fd35 100644 --- a/.chloggen/1719.yaml +++ b/.chloggen/1719.yaml @@ -7,7 +7,7 @@ change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: genai +component: gen-ai # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: Adds `mistral_ai` as a `gen_ai.system` attribute value. From 539ce854bf8814c01e3e53d75453648cff0cdeed Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 16 Jan 2025 11:54:10 -0800 Subject: [PATCH 11/39] Add common guidance on recording errors on spans and metrics, clarify DB conventions (#1716) Co-authored-by: Trask Stalnaker --- .chloggen/1716.yaml | 4 + docs/attributes-registry/exception.md | 27 ++-- docs/cli/cli-spans.md | 3 +- docs/database/cassandra.md | 3 +- docs/database/cosmosdb.md | 3 +- docs/database/couchdb.md | 5 +- docs/database/database-spans.md | 58 +------- docs/database/elasticsearch.md | 3 +- docs/database/hbase.md | 2 +- docs/database/mariadb.md | 38 +----- docs/database/mongodb.md | 3 +- docs/database/mssql.md | 1 + docs/database/mysql.md | 38 +----- docs/database/postgresql.md | 36 +---- docs/database/redis.md | 3 +- docs/database/sql.md | 2 +- docs/exceptions/README.md | 2 - docs/exceptions/exceptions-spans.md | 46 +------ docs/faas/faas-spans.md | 2 + docs/gen-ai/gen-ai-spans.md | 6 + docs/general/recording-errors.md | 129 ++++++++++++++++++ docs/http/http-spans.md | 5 +- docs/messaging/messaging-spans.md | 6 + docs/rpc/rpc-spans.md | 6 + model/database/spans.yaml | 42 +++++- .../deprecated/registry-deprecated.yaml | 14 ++ model/exceptions/registry.yaml | 23 ---- 27 files changed, 240 insertions(+), 270 deletions(-) create mode 100644 .chloggen/1716.yaml create mode 100644 docs/general/recording-errors.md create mode 100644 model/exceptions/deprecated/registry-deprecated.yaml diff --git a/.chloggen/1716.yaml b/.chloggen/1716.yaml new file mode 100644 index 0000000000..1c16bf56d1 --- /dev/null +++ b/.chloggen/1716.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: docs, db +note: Add common guidance for recording errors on spans and metrics, clarify DB conventions. +issues: [1516, 1536, 1716] diff --git a/docs/attributes-registry/exception.md b/docs/attributes-registry/exception.md index be9b732e15..201dc3bd75 100644 --- a/docs/attributes-registry/exception.md +++ b/docs/attributes-registry/exception.md @@ -6,30 +6,23 @@ # Exception +- [Exception Attributes](#exception-attributes) +- [Deprecated Exception Attributes](#deprecated-exception-attributes) + ## Exception Attributes This document defines the shared attributes used to report a single exception associated with a span or log. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span, -if that span is ended while the exception is still logically "in flight". -This may be actually "in flight" in some languages (e.g. if the exception -is passed to a Context manager's `__exit__` method in Python) but will -usually be caught at the point of recording the exception in most languages. - -It is usually not possible to determine at the point where an exception is thrown -whether it will escape the scope of a span. -However, it is trivial to know that an exception -will escape, if one checks for an active exception just before ending the span, -as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). - -It follows that an exception may still escape the scope of the span -even if the `exception.escaped` attribute was not set or set to false, -since the event might have been recorded at a time where it was not -clear whether the exception will escape. +## Deprecated Exception Attributes + +Deprecated exception attributes. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `exception.escaped` | boolean | Indicates that the exception is escaping the scope of the span. | | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | diff --git a/docs/cli/cli-spans.md b/docs/cli/cli-spans.md index be7e2a61b8..0540a9641b 100644 --- a/docs/cli/cli-spans.md +++ b/docs/cli/cli-spans.md @@ -13,7 +13,8 @@ Span kind SHOULD be `INTERNAL` when the traced program is the callee or `CLIENT` The span name SHOULD be set to `{process.executable.name}`. Instrumentations that have additional context about executed commands MAY use a different low-cardinality span name format and SHOULD document it. -Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. +Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +additional details on how to record span status. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 7ec690b232..cf3d2b3b68 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -69,8 +69,7 @@ system specific term if more applicable. **[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. -**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[6] `db.response.status_code`:** All Cassandra protocol error codes SHOULD be considered errors. **[7] `db.response.status_code`:** If the operation failed and status code is available. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 810967a907..679e1fde6c 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -193,8 +193,7 @@ additional values when introducing new operations. **[5] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. -**[6] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[6] `db.response.status_code`:** Response codes in the 4xx and 5xx range SHOULD be considered errors. **[7] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index b4eb826f75..873bd36565 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -23,7 +23,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | The HTTP response code returned by the Couch DB recorded as a string. [2] | `200`; `201`; `429` | `Conditionally Required` [3] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [7] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | @@ -31,8 +31,7 @@ The Semantic Conventions for [CouchDB](https://couchdb.apache.org/) extend and o **[1] `db.operation.name`:** In **CouchDB**, `db.operation.name` should be set to the HTTP method + the target REST route according to the API reference documentation. For example, when retrieving a document, `db.operation.name` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`](https://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). -**[2] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[2] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. **[3] `db.response.status_code`:** If response was received and the HTTP response code is available. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index dcd4ec2202..5e1b17d4a5 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -12,7 +12,6 @@ linkTitle: Client Calls - [Name](#name) - [Status](#status) - - [Recording exception events](#recording-exception-events) - [Common attributes](#common-attributes) - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Sanitization of `db.query.text`](#sanitization-of-dbquerytext) @@ -89,59 +88,11 @@ For example, for an operation describing SQL query on an anonymous table like `S ## Status -[Span Status Code][SpanStatus] MUST be left unset if the operation has ended without any errors. +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. -Instrumentation SHOULD consider the operation as failed if any of the following is true: - -- the `db.response.status_code` value indicates an error - - > [!NOTE] - > - > The classification of status code as an error depends on the context. - > For example, a SQL STATE `02000` (`no_data`) indicates an error when the application - > expected the data to be available. However, it is not an error when the - > application is simply checking whether the data exists. - > - > Instrumentations that have additional context about a specific operation MAY use - > this context to set the span status more precisely. - > Instrumentations that don't have any additional context MUST follow the - > guidelines in this section. - -- an exception is thrown by the instrumented method call -- the instrumented method returns an error in another way - -When the operation ends with an error, instrumentation: - -- SHOULD set the span status code to `Error` -- SHOULD set the `error.type` attribute -- SHOULD set the span status description when it has additional information - about the error which is not expected to contain sensitive details and aligns - with [Span Status Description][SpanStatus] definition. - - It's NOT RECOMMENDED to duplicate `db.response.status_code` or `error.type` - in span status description. - - When the operation fails with an exception, the span status description SHOULD be set to - the exception message. - -### Recording exception events - -**Status**: [Experimental][DocumentStatus] - -When the operation fails with an exception, instrumentation SHOULD record -an [exception event](../exceptions/exceptions-spans.md) by default if, and only if, -the span being recorded is a local root span (does not have a local parent). - -> [!NOTE] -> -> Exception stack traces could be very long and are expensive to capture and store. -> Exceptions which are not handled by instrumented libraries are likely to be handled -> and logged by the caller. -> Exceptions that are not handled will be recorded by the outermost (local root) -> instrumentation such as HTTP or gRPC server. - -Instrumentation MAY provide a configuration option to record exceptions that -escape the surface of the instrumented API. +Semantic conventions for individual systems SHOULD specify which values of `db.response.status_code` +classify as errors. ## Common attributes @@ -466,4 +417,3 @@ More specific Semantic Conventions are defined for the following database techno * [SQL](sql.md): Semantic Conventions for *SQL* databases. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 175cf43fab..da64ed62fa 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -82,8 +82,7 @@ When a query string value is redacted, the query string key SHOULD still be pres **[4] `db.elasticsearch.path_parts`:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. -**[5] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[5] `db.response.status_code`:** HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. **[6] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 6e8e2b03b9..37d4d29163 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -24,7 +24,7 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.namespace`](/docs/attributes-registry/db.md) | string | The HBase namespace. [2] | `mynamespace` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [3] | `findAndModify`; `HMSET`; `SELECT` | `Conditionally Required` If readily available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Protocol-specific response code recorded as string. [4] | `200`; `409`; `14` | `Conditionally Required` If response was received. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Protocol-specific response code recorded as a string. [4] | `200`; `409`; `14` | `Conditionally Required` If response was received. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [5] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | `Conditionally Required` [7] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [8] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index 58285321b5..e34fc231da 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -42,41 +42,9 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database -return code which is adopted by some database systems like PostgreSQL. -See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html) -for the details. - -Other systems like MySQL, Oracle, or MS SQL Server define vendor-specific -error codes. Database SQL drivers usually provide access to both properties. -For example, in Java, the [`SQLException`](https://docs.oracle.com/javase/8/docs/api/java/sql/SQLException.html) -class reports them with `getSQLState()` and `getErrorCode()` methods. - -Instrumentations SHOULD populate the `db.response.status_code` with the -the most specific code available to them. - -Here's a non-exhaustive list of databases that report vendor-specific -codes with granularity higher than SQLSTATE (or don't report SQLSTATE -at all): - -- [DB2 SQL codes](https://www.ibm.com/docs/db2-for-zos/12?topic=codes-sql). -- [Maria DB error codes](https://mariadb.com/kb/en/mariadb-error-code-reference/) -- [Microsoft SQL Server errors](https://docs.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) -- [MySQL error codes](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) -- [Oracle error codes](https://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm) -- [SQLite result codes](https://www.sqlite.org/rescode.html) - -These systems SHOULD set the `db.response.status_code` to a -known vendor-specific error code. If only SQLSTATE is available, -it SHOULD be used. - -When multiple error codes are available and specificity is unclear, -instrumentation SHOULD set the `db.response.status_code` to the -concatenated string of all codes with '/' used as a separator. - -For example, generic DB instrumentation that detected an error and has -SQLSTATE `"42000"` and vendor-specific `1071` should set -`db.response.status_code` to `"42000/1071"`." +**[2] `db.response.status_code`:** MariaDB uses vendor-specific error codes on all errors and reports [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) in some cases. +MariaDB error codes are more granular than SQLSTATE, so MariaDB instrumentations SHOULD set the `db.response.status_code` to this known error code. +When SQLSTATE is available, SQLSTATE of "Class 02" or higher SHOULD be considered errors. When SQLSTATE is not available, all MariaDB error codes SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 26f33c9afb..0c8dbe46ba 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -40,8 +40,7 @@ then that collection name SHOULD be used. **[2] `db.operation.name`:** See [MongoDB database commands](https://www.mongodb.com/docs/manual/reference/command/). -**[3] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[3] `db.response.status_code`:** All MongoDB error codes SHOULD be considered errors. **[4] `db.response.status_code`:** If the operation failed and error code is available. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index e6147cae1d..5b30b833fb 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -47,6 +47,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. **[2] `db.response.status_code`:** Microsoft SQL Server does not report SQLSTATE. +Instrumentations SHOULD use [error severity](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-error-severities) returned along with the status code to determine the status of the span. Response codes with severity 11 or higher SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/mysql.md b/docs/database/mysql.md index 99bb820e83..19b42520c0 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -22,7 +22,7 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) recorded as a string. [2] | `1005`; `MY-010016` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | @@ -42,41 +42,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the database provided It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database -return code which is adopted by some database systems like PostgreSQL. -See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html) -for the details. - -Other systems like MySQL, Oracle, or MS SQL Server define vendor-specific -error codes. Database SQL drivers usually provide access to both properties. -For example, in Java, the [`SQLException`](https://docs.oracle.com/javase/8/docs/api/java/sql/SQLException.html) -class reports them with `getSQLState()` and `getErrorCode()` methods. - -Instrumentations SHOULD populate the `db.response.status_code` with the -the most specific code available to them. - -Here's a non-exhaustive list of databases that report vendor-specific -codes with granularity higher than SQLSTATE (or don't report SQLSTATE -at all): - -- [DB2 SQL codes](https://www.ibm.com/docs/db2-for-zos/12?topic=codes-sql). -- [Maria DB error codes](https://mariadb.com/kb/en/mariadb-error-code-reference/) -- [Microsoft SQL Server errors](https://docs.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) -- [MySQL error codes](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) -- [Oracle error codes](https://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm) -- [SQLite result codes](https://www.sqlite.org/rescode.html) - -These systems SHOULD set the `db.response.status_code` to a -known vendor-specific error code. If only SQLSTATE is available, -it SHOULD be used. - -When multiple error codes are available and specificity is unclear, -instrumentation SHOULD set the `db.response.status_code` to the -concatenated string of all codes with '/' used as a separator. - -For example, generic DB instrumentation that detected an error and has -SQLSTATE `"42000"` and vendor-specific `1071` should set -`db.response.status_code` to `"42000/1071"`." +**[2] `db.response.status_code`:** MySQL error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) conventions. All MySQL error codes SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 545af7ae55..27c269ea39 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -49,41 +49,7 @@ Instrumentation SHOULD document if `db.namespace` reflects the user provided whe It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. -**[2] `db.response.status_code`:** SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database -return code which is adopted by some database systems like PostgreSQL. -See [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html) -for the details. - -Other systems like MySQL, Oracle, or MS SQL Server define vendor-specific -error codes. Database SQL drivers usually provide access to both properties. -For example, in Java, the [`SQLException`](https://docs.oracle.com/javase/8/docs/api/java/sql/SQLException.html) -class reports them with `getSQLState()` and `getErrorCode()` methods. - -Instrumentations SHOULD populate the `db.response.status_code` with the -the most specific code available to them. - -Here's a non-exhaustive list of databases that report vendor-specific -codes with granularity higher than SQLSTATE (or don't report SQLSTATE -at all): - -- [DB2 SQL codes](https://www.ibm.com/docs/db2-for-zos/12?topic=codes-sql). -- [Maria DB error codes](https://mariadb.com/kb/en/mariadb-error-code-reference/) -- [Microsoft SQL Server errors](https://docs.microsoft.com/sql/relational-databases/errors-events/database-engine-events-and-errors) -- [MySQL error codes](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) -- [Oracle error codes](https://docs.oracle.com/cd/B28359_01/server.111/b28278/toc.htm) -- [SQLite result codes](https://www.sqlite.org/rescode.html) - -These systems SHOULD set the `db.response.status_code` to a -known vendor-specific error code. If only SQLSTATE is available, -it SHOULD be used. - -When multiple error codes are available and specificity is unclear, -instrumentation SHOULD set the `db.response.status_code` to the -concatenated string of all codes with '/' used as a separator. - -For example, generic DB instrumentation that detected an error and has -SQLSTATE `"42000"` and vendor-specific `1071` should set -`db.response.status_code` to `"42000/1071"`." +**[2] `db.response.status_code`:** PostgreSQL follows SQL standard conventions for [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE). Response codes of "Class 02" or higher SHOULD be considered errors. **[3] `error.type`:** The `error.type` SHOULD match the `db.response.status_code` returned by the database or the client library, or the canonical name of exception that occurred. When using canonical exception type name, instrumentation SHOULD do the best effort to report the most relevant type. For example, if the original exception is wrapped into a generic one, the original exception SHOULD be preferred. diff --git a/docs/database/redis.md b/docs/database/redis.md index cd826850ff..8ef933e7a4 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -60,8 +60,7 @@ system specific term if more applicable. **[3] `db.operation.name`:** If readily available and if there is a single operation name that describes the database call. The operation name MAY be parsed from the query text, in which case it SHOULD be the single operation name found in the query. -**[4] `db.response.status_code`:** The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual database systems SHOULD document what `db.response.status_code` means in the context of that system. +**[4] `db.response.status_code`:** All Redis error prefixes SHOULD be considered errors. **[5] `db.response.status_code`:** If the operation failed and status code is available. diff --git a/docs/database/sql.md b/docs/database/sql.md index a66b348723..b935d68ee7 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -46,7 +46,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, fully qualified within the server address and port. [1] | `customers`; `test.users` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as string. [2] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`db.response.status_code`](/docs/attributes-registry/db.md) | string | Database response code recorded as a string. [2] | `ORA-17027`; `1052`; `2201B` | `Conditionally Required` If response has ended with warning or an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the operation failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Conditionally Required` [5] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`db.operation.batch.size`](/docs/attributes-registry/db.md) | int | The number of queries included in a batch operation. [6] | `2`; `3`; `4` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/exceptions/README.md b/docs/exceptions/README.md index bee2851df8..6c1c976e10 100644 --- a/docs/exceptions/README.md +++ b/docs/exceptions/README.md @@ -9,8 +9,6 @@ path_base_for_github_subdir: **Status**: [Stable][DocumentStatus] -This document defines semantic conventions for Exceptions. - Semantic conventions for Exceptions are defined for the following signals: * [Exceptions on spans](exceptions-spans.md): Semantic Conventions for Exceptions associated with *spans*. diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index afcb5a50c3..96ca6f49cd 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -11,33 +11,6 @@ exceptions associated with spans. -- [Recording an Exception](#recording-an-exception) -- [Exception event](#exception-event) - - [Stacktrace Representation](#stacktrace-representation) - - - -## Recording an Exception - -An exception SHOULD be recorded as an `Event` on the span during which it occurred. -The name of the event MUST be `"exception"`. - -A typical template for an auto-instrumentation implementing this semantic convention -using an [API-provided `recordException` method](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#record-exception) -could look like this (pseudo-Java): - -```java -Span span = myTracer.startSpan(/*...*/); -try { - // Code that does the actual work which the Span represents -} catch (Throwable e) { - span.recordException(e, Attributes.of("exception.escaped", true)); - throw e; -} finally { - span.end(); -} -``` - ## Exception event @@ -57,30 +30,13 @@ This event describes a single exception. |---|---|---|---|---|---| | [`exception.message`](/docs/attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`exception.type`](/docs/attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`exception.escaped`](/docs/attributes-registry/exception.md) | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [3] | | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`exception.escaped`](/docs/attributes-registry/exception.md) | boolean | Indicates that the exception is escaping the scope of the span. | | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | | [`exception.stacktrace`](/docs/attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. **[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. -**[3] `exception.escaped`:** An exception is considered to have escaped (or left) the scope of a span, -if that span is ended while the exception is still logically "in flight". -This may be actually "in flight" in some languages (e.g. if the exception -is passed to a Context manager's `__exit__` method in Python) but will -usually be caught at the point of recording the exception in most languages. - -It is usually not possible to determine at the point where an exception is thrown -whether it will escape the scope of a span. -However, it is trivial to know that an exception -will escape, if one checks for an active exception just before ending the span, -as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). - -It follows that an exception may still escape the scope of the span -even if the `exception.escaped` attribute was not set or set to false, -since the event might have been recorded at a time where it was not -clear whether the exception will escape. - diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index b49ee5766c..89b01428ba 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -36,6 +36,8 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. + If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index 99cfb96f8b..54ebc54f37 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -11,6 +11,7 @@ linkTitle: Generative AI traces - [Name](#name) + - [Status](#status) - [GenAI attributes](#genai-attributes) - [Capturing inputs and outputs](#capturing-inputs-and-outputs) @@ -30,6 +31,11 @@ GenAI spans MUST follow the overall [guidelines for span names](https://github.c The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. +### Status + +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. + ## GenAI attributes These attributes track input data and metadata for a request to a GenAI model. Each attribute represents a concept that is common to most Generative AI clients. diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md new file mode 100644 index 0000000000..b6ed152711 --- /dev/null +++ b/docs/general/recording-errors.md @@ -0,0 +1,129 @@ + + +# Recording errors + +**Status**: [Development][DocumentStatus]. + + + +- [What constitutes an error](#what-constitutes-an-error) +- [Recording errors on spans](#recording-errors-on-spans) +- [Recording errors on metrics](#recording-errors-on-metrics) +- [Recording exceptions](#recording-exceptions) + + + +This document provides recommendations to semantic convention and instrumentation authors +on how to record errors on spans and metrics. + +Individual semantic conventions are encouraged to provide additional guidance. + +## What constitutes an error + +An operation SHOULD be considered as failed if any of the following is true: + +- an exception is thrown by the instrumented method (API, block of code, or another instrumented unit) +- the instrumented method returns an error in another way, for example, via an error code + + Semantic conventions that define domain-specific status codes SHOULD specify + which status codes should be reported as errors by a general-purpose instrumentation. + +> [!NOTE] +> +> The classification of a status code as an error depends on the context. +> For example, an HTTP 404 "Not Found" status code indicates an error if the application +> expected the resource to be available. However, it is not an error when the +> application is simply checking whether the resource exists. +> +> Instrumentations that have additional context about a specific request MAY use +> this context to set the span status more precisely. + +Errors that were retried or handled (allowing an operation to complete gracefully) SHOULD NOT +be recorded on spans or metrics that describe this operation. + +## Recording errors on spans + +[Span Status Code][SpanStatus] MUST be left unset if the instrumented operation has +ended without any errors. + +When the operation ends with an error, instrumentation: + +- SHOULD set the span status code to `Error` +- SHOULD set the [`error.type`](/docs/attributes-registry/error.md#error-type) attribute +- SHOULD set the span status description when it has additional information + about the error which is not expected to contain sensitive details and aligns + with [Span Status Description][SpanStatus] definition. + + It's NOT RECOMMENDED to duplicate status code or `error.type` in span status description. + + When the operation fails with an exception, the span status description SHOULD be set to + the exception message. + +Refer to the [recording exceptions](#recording-errors) on capturing exception +details. + +## Recording errors on metrics + +Semantic conventions for operations usually define an operation duration histogram +metric. This metric SHOULD include the `error.type` attribute. This enables users to derive +throughput and error rates. + +Operations that complete successfully SHOULD NOT include the `error.type` attribute, +allowing users to filter out errors. + +Semantic conventions SHOULD include `error.type` on other metrics when it's applicable. +For example, `messaging.client.sent.messages` metric measures message throughput (one +messaging operation may involve sending multiple messages) and includes `error.type`. + +It's RECOMMENDED to report one metric that includes successes and failures as opposed +to reporting two (or more) metrics depending on the operation status. + +Instrumentation SHOULD ensure `error.type` is applied consistently across spans +and metrics when both are reported. A span and its corresponding metric for a single +operation SHOULD have the same `error.type` value if the operation failed and SHOULD NOT +include it if the operation succeeded. + +## Recording exceptions + +When an instrumented operation fails with an exception, instrumentation SHOULD record +this exception as a [span event](/docs/exceptions/exceptions-spans.md) or a [log record](/docs/exceptions/exceptions-logs.md). + +It's RECOMMENDED to use the `Span.recordException` API or logging library API that takes exception instance +instead of providing individual attributes. This enables the OpenTelemetry SDK to +control what information is recorded based on application configuration. + +It's NOT RECOMMENDED to record the same exception more than once. +It's NOT RECOMMENDED to record exceptions that are handled by the instrumented library. + +For example, in this code-snippet, `ResourceAlreadyExistsException` is handled and the corresponding +native instrumentation should not record it. Exceptions which are propagated +to the caller should be recorded (or logged) once. + +```java +public boolean createIfNotExists(String resourceId) throws IOException { + Span span = startSpan(); + try { + create(resourceId); + return true; + } catch (ResourceAlreadyExistsException e) { + // not recording exception and not setting span status to error - exception is handled + // but we can set attributes that capture additional details + span.setAttribute(AttributeKey.stringKey("acme.resource.create.status"), "already_exists"); + return false; + } catch (IOException e) { + // recording exception here (assuming it was not recorded inside `create` method) + span.recordException(e); + // or + // logger.warn(e); + + span.setAttribute(AttributeKey.stringKey("error.type"), e.getClass().getCanonicalName()) + span.setStatus(StatusCode.ERROR, e.getMessage()); + throw e; + } +} +``` + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 6d54263fcd..2ac016a237 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -91,7 +91,7 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. -> **Note:** +> [!NOTE] > > The classification of an HTTP status code as an error depends on the context. > For example, a 404 "Not Found" status code indicates an error if the application @@ -117,6 +117,9 @@ the client or server from sending/receiving the request/response fully. When instrumentation detects such errors it SHOULD set span status to `Error` and SHOULD set the `error.type` attribute. +**Status**: [Development][DocumentStatus] - Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +general considerations on how to record span status. + ## HTTP client This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 0d13af08bd..02cbbc2691 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -22,6 +22,7 @@ - [Span name](#span-name) - [Operation types](#operation-types) - [Span kind](#span-kind) + - [Span status](#span-status) - [Trace structure](#trace-structure) - [Producer spans](#producer-spans) - [Consumer spans](#consumer-spans) @@ -247,6 +248,11 @@ Span kind SHOULD be set according to the following table, based on the operation Setting span kinds according to this table allows analysis tools to interpret spans and relationships between them without the need for additional semantic hints. +### Span status + +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. + ### Trace structure #### Producer spans diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 9401826e9b..d73492be49 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -15,6 +15,7 @@ This document defines how to describe remote procedure calls - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - [Span name](#span-name) + - [Span status](#span-status) - [Service name](#service-name) - [Client attributes](#client-attributes) - [Server attributes](#server-attributes) @@ -79,6 +80,11 @@ Examples of span names: `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls - `MyServiceWithNoPackage/theMethod` +### Span status + +Refer to the [Recording Errors](/docs/general/recording-errors.md) document for +details on how to record span status. + ### Service name On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 476127d09c..b03a9cf9a1 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -148,6 +148,9 @@ groups: represented as a string. note: > Microsoft SQL Server does not report SQLSTATE. + + Instrumentations SHOULD use [error severity](https://learn.microsoft.com/sql/relational-databases/errors-events/database-engine-error-severities) + returned along with the status code to determine the status of the span. Response codes with severity 11 or higher SHOULD be considered errors. examples: ["102", "40020"] - id: span.db.postgresql.client @@ -183,8 +186,10 @@ groups: - ref: db.response.status_code brief: > [PostgreSQL error code](https://www.postgresql.org/docs/current/errcodes-appendix.html). + note: > + PostgreSQL follows SQL standard conventions for [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE). + Response codes of "Class 02" or higher SHOULD be considered errors. examples: ["08000", "08P01"] - - id: span.db.mysql.client type: span stability: experimental @@ -209,7 +214,10 @@ groups: examples: ["products", "customers"] - ref: db.response.status_code brief: > - [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html). + [MySQL error number](https://dev.mysql.com/doc/mysql-errors/9.0/en/error-reference-introduction.html) recorded as a string. + note: > + MySQL error codes are vendor specific error codes and don't follow [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) + conventions. All MySQL error codes SHOULD be considered errors. examples: ["1005", "MY-010016"] - id: span.db.mariadb.client @@ -238,8 +246,18 @@ groups: brief: > [Maria DB error code](https://mariadb.com/kb/en/mariadb-error-code-reference/) represented as a string. - examples: ["1008", "3058"] + note: > + MariaDB uses vendor-specific error codes on all errors and reports + [SQLSTATE](https://mariadb.com/kb/en/sqlstate/) in some cases. + + MariaDB error codes are more granular than SQLSTATE, so MariaDB instrumentations + SHOULD set the `db.response.status_code` to this known error code. + + When SQLSTATE is available, SQLSTATE of "Class 02" or higher SHOULD be + considered errors. When SQLSTATE is not available, all MariaDB error + codes SHOULD be considered errors. + examples: ["1008", "3058"] - id: span.db.cassandra.client type: span span_kind: client @@ -274,6 +292,8 @@ groups: - ref: db.response.status_code brief: > [Cassandra protocol error code](https://github.com/apache/cassandra/blob/cassandra-5.0/doc/native_protocol_v5.spec) represented as a string. + note: > + All Cassandra protocol error codes SHOULD be considered errors. examples: ["102", "40020"] - id: span.db.hbase.client type: span @@ -302,7 +322,7 @@ groups: conditionally_required: If readily available. - ref: db.response.status_code brief: > - Protocol-specific response code recorded as string. + Protocol-specific response code recorded as a string. examples: ["200", "409", "14"] requirement_level: conditionally_required: If response was received. @@ -334,7 +354,9 @@ groups: note: "" # overriding the base note - ref: db.response.status_code brief: > - The HTTP response code returned by the Couch DB. + The HTTP response code returned by the Couch DB recorded as a string. + note: > + HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. examples: ["200", "201", "429"] requirement_level: conditionally_required: If response was received and the HTTP response code is available. @@ -395,6 +417,8 @@ groups: brief: > The Redis [simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-errors) prefix. examples: ["ERR", "WRONGTYPE", "CLUSTERDOWN"] + note: > + All Redis error prefixes SHOULD be considered errors. - ref: db.operation.batch.size - ref: db.operation.parameter requirement_level: opt_in @@ -434,6 +458,8 @@ groups: - ref: db.response.status_code brief: > [MongoDB error code](https://www.mongodb.com/docs/manual/reference/error-codes/) represented as a string. + note: > + All MongoDB error codes SHOULD be considered errors. requirement_level: conditionally_required: If the operation failed and error code is available. examples: ["36", "11602"] @@ -492,6 +518,8 @@ groups: brief: > The HTTP response code returned by the Elasticsearch cluster. examples: ["200", "201", "429"] + note: > + HTTP response codes in the 4xx and 5xx range SHOULD be considered errors. requirement_level: conditionally_required: If response was received. - id: span.db.sql.client @@ -528,7 +556,7 @@ groups: It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. - ref: db.response.status_code brief: > - Database response code recorded as string. + Database response code recorded as a string. note: | SQL defines [SQLSTATE](https://wikipedia.org/wiki/SQLSTATE) as a database return code which is adopted by some database systems like PostgreSQL. @@ -607,6 +635,8 @@ groups: brief: > Cosmos DB status code. examples: ["200", "201"] + note: > + Response codes in the 4xx and 5xx range SHOULD be considered errors. requirement_level: conditionally_required: if response was received - ref: db.response.returned_rows diff --git a/model/exceptions/deprecated/registry-deprecated.yaml b/model/exceptions/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..ed9e57ac93 --- /dev/null +++ b/model/exceptions/deprecated/registry-deprecated.yaml @@ -0,0 +1,14 @@ +groups: + - id: registry.exception.deprecated + type: attribute_group + display_name: Deprecated Exception Attributes + brief: > + Deprecated exception attributes. + attributes: + - id: exception.escaped + type: boolean + stability: stable + deprecated: "It's no longer recommended to record exceptions that are handled + and do not escape the scope of a span." + brief: > + Indicates that the exception is escaping the scope of the span. diff --git a/model/exceptions/registry.yaml b/model/exceptions/registry.yaml index 1ebc90d854..7231a394de 100644 --- a/model/exceptions/registry.yaml +++ b/model/exceptions/registry.yaml @@ -31,26 +31,3 @@ groups: at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5) - - id: exception.escaped - type: boolean - stability: stable - brief: > - SHOULD be set to true if the exception event is recorded at a point where - it is known that the exception is escaping the scope of the span. - note: |- - An exception is considered to have escaped (or left) the scope of a span, - if that span is ended while the exception is still logically "in flight". - This may be actually "in flight" in some languages (e.g. if the exception - is passed to a Context manager's `__exit__` method in Python) but will - usually be caught at the point of recording the exception in most languages. - - It is usually not possible to determine at the point where an exception is thrown - whether it will escape the scope of a span. - However, it is trivial to know that an exception - will escape, if one checks for an active exception just before ending the span, - as done in the [example for recording span exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/#recording-an-exception). - - It follows that an exception may still escape the scope of the span - even if the `exception.escaped` attribute was not set or set to false, - since the event might have been recorded at a time where it was not - clear whether the exception will escape. From 4a395177b4927b84d4c6de95bf708929a584acf2 Mon Sep 17 00:00:00 2001 From: Guangya Liu Date: Fri, 17 Jan 2025 10:34:57 -0500 Subject: [PATCH 12/39] [chore] Added content for update toc (#1754) Signed-off-by: Guangya Liu --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 111d35baa9..68755d1cf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,6 +32,7 @@ requirements and recommendations. - [Auto formatting](#auto-formatting) - [Markdown style](#markdown-style) - [Misspell check](#misspell-check) + - [Update the tables of content](#update-the-tables-of-content) - [Markdown link check](#markdown-link-check) - [Updating the referenced specification version](#updating-the-referenced-specification-version) - [Making a Release](#making-a-release) @@ -343,6 +344,7 @@ You can also run these fixes individually. See: - [Misspell Correction](#misspell-check) +- [Update the tables of content](#update-the-tables-of-content) - [Update the markdown files](#2-update-the-markdown-files) ### Markdown style @@ -389,6 +391,14 @@ To quickly fix typos, use make misspell-correction ``` +### Update the tables of content + +To update the tables of content, run: + +```bash +make markdown-toc +``` + ### Markdown link check To check the validity of links in all markdown files, run the following command: From 4ede34198ecafa26fc84141c716c50283218772a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 17 Jan 2025 10:54:38 -0500 Subject: [PATCH 13/39] [editorial] Adjust link into in-toto attestation spec (#1753) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/attributes-registry/artifact.md | 2 +- model/artifact/registry.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/artifact.md b/docs/attributes-registry/artifact.md index 4006920b1c..0258573481 100644 --- a/docs/attributes-registry/artifact.md +++ b/docs/attributes-registry/artifact.md @@ -13,7 +13,7 @@ This group describes attributes specific to artifacts. Artifacts are files or ot | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `artifact.attestation.filename` | string | The provenance filename of the built attestation which directly relates to the build artifact filename. This filename SHOULD accompany the artifact at publish time. See the [SLSA Relationship](https://slsa.dev/spec/v1.0/distributing-provenance#relationship-between-artifacts-and-attestations) specification for more information. | `golang-binary-amd64-v0.1.0.attestation`; `docker-image-amd64-v0.1.0.intoto.json1`; `release-1.tar.gz.attestation`; `file-name-package.tar.gz.intoto.json1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `artifact.attestation.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the software attestation space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.attestation.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the [software attestation space](https://github.com/in-toto/attestation/tree/main/spec) also refer to this as the **digest**. | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `artifact.attestation.id` | string | The id of the build [software attestation](https://slsa.dev/attestation-model). | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `artifact.filename` | string | The human readable file name of the artifact, typically generated during build and release processes. Often includes the package name and version in the file name. [1] | `golang-binary-amd64-v0.1.0`; `docker-image-amd64-v0.1.0`; `release-1.tar.gz`; `file-name-package.tar.gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `artifact.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), often found in checksum.txt on a release of the artifact and used to verify package integrity. [2] | `9ff4c52759e2c4ac70b7d517bc7fcdc1cda631ca0045271ddd1b192544f8a3e9` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/artifact/registry.yaml b/model/artifact/registry.yaml index 4f6dd98419..7887d9775e 100644 --- a/model/artifact/registry.yaml +++ b/model/artifact/registry.yaml @@ -91,7 +91,7 @@ groups: stability: experimental brief: > The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), - of the built attestation. Some envelopes in the software attestation - space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). + of the built attestation. Some envelopes in the [software attestation + space](https://github.com/in-toto/attestation/tree/main/spec) also refer to this as the **digest**. examples: ["1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408"] From 3ea010382421807ddef2ea62cccf3e5dd4673262 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 17 Jan 2025 14:38:55 -0500 Subject: [PATCH 14/39] [editorial] Fix invalid link syntax in `system/hardware-metrics` (#1759) --- docs/system/hardware-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index fb5496deb7..6494ec696c 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -11,7 +11,7 @@ metrics in OpenTelemetry. Consider the [general metric semantic conventions](/do when creating instruments not explicitly defined in the specification. This document is being converted to specific hardware metrics, parts of this document that have already been -converted are now located in the [Hardware] (/docs/hardware/README.md) folder and are no longer present in this file. +converted are now located in the [Hardware](/docs/hardware/README.md) folder and are no longer present in this file. Please note that this is an [ongoing process](https://github.com/open-telemetry/semantic-conventions/issues/1309) and may take some time to complete. From 44fc8fa2f14526dfd54cffe3956bbbd678b39607 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 17 Jan 2025 15:51:42 -0800 Subject: [PATCH 15/39] Update specification version to 1.40.0 (#1763) --- README.md | 2 +- docs/database/cosmosdb.md | 2 +- docs/database/database-metrics.md | 4 ++-- docs/database/database-spans.md | 2 +- docs/dns/dns-metrics.md | 2 +- docs/dotnet/dotnet-aspnetcore-metrics.md | 4 ++-- docs/dotnet/dotnet-dns-metrics.md | 2 +- docs/dotnet/dotnet-http-metrics.md | 4 ++-- docs/dotnet/dotnet-kestrel-metrics.md | 4 ++-- docs/dotnet/dotnet-signalr-metrics.md | 2 +- docs/exceptions/exceptions-logs.md | 8 ++++---- docs/faas/aws-lambda.md | 4 ++-- docs/faas/faas-metrics.md | 6 +++--- docs/feature-flags/feature-flags-logs.md | 8 ++++---- docs/gen-ai/gen-ai-metrics.md | 2 +- docs/gen-ai/gen-ai-spans.md | 2 +- docs/general/events.md | 6 +++--- docs/general/logs.md | 4 ++-- docs/general/metrics.md | 4 ++-- docs/general/recording-errors.md | 2 +- docs/general/trace.md | 2 +- docs/http/http-metrics.md | 6 +++--- docs/http/http-spans.md | 6 +++--- docs/messaging/messaging-metrics.md | 4 ++-- docs/messaging/messaging-spans.md | 2 +- docs/resource/README.md | 6 +++--- docs/resource/cloudfoundry.md | 2 +- docs/rpc/connect-rpc.md | 2 +- docs/rpc/grpc.md | 4 ++-- docs/runtime/jvm-metrics.md | 2 +- docs/runtime/nodejs-metrics.md | 2 +- docs/runtime/v8js-metrics.md | 4 ++-- internal/tools/update_specification_version.sh | 6 +++--- 33 files changed, 61 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index ddba49fe5f..26d9ed7fdc 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Checks](https://github.com/open-telemetry/semantic-conventions/workflows/Checks/badge.svg?branch=main)](https://github.com/open-telemetry/semantic-conventions/actions?query=workflow%3A%22Checks%22+branch%3Amain) [![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/open-telemetry/semantic-conventions.svg?logo=opentelemetry&&color=f5a800&label=Latest%20release)](https://github.com/open-telemetry/semantic-conventions/releases/latest) -[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.39.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.39.0) +[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.40.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.40.0) Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 679e1fde6c..537f4ef778 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -316,7 +316,7 @@ This metric is [required][MetricRequired]. It captures the Request Units consumed by each operation in Azure Cosmos DB. Since Request Units serve as a form of throughput control within the Azure Cosmos DB database, monitoring their usage is crucial to avoid throttling. this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 1, 5, 10, 25, 50, 100, 250, 500, 1000]`. Explaining bucket configuration: diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 47412d1ac3..b966d52465 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -65,7 +65,7 @@ This metric is [required][MetricRequired]. When this metric is reported alongside a database operation span, the metric value SHOULD be the same as the database operation span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`. @@ -232,7 +232,7 @@ The following metric instruments describe database query response. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000]`. Explaining bucket configuration: diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 5e1b17d4a5..1f6dffa233 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -58,7 +58,7 @@ with all retries. ## Name -Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). The **span name** SHOULD be `{db.query.summary}` if a summary is available. diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md index 9cdec3122d..63c8dec891 100644 --- a/docs/dns/dns-metrics.md +++ b/docs/dns/dns-metrics.md @@ -24,7 +24,7 @@ This document defines semantic conventions to apply when instrumenting DNS queri This metric is optional. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index 76f65aa849..e34a449933 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -172,7 +172,7 @@ All rate-limiting metrics are reported by the `Microsoft.AspNetCore.RateLimiting ### Metric: `aspnetcore.rate_limiting.request_lease.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -228,7 +228,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ### Metric: `aspnetcore.rate_limiting.request.time_in_queue` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 43137549c8..638c6c728e 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -20,7 +20,7 @@ This article defines semantic conventions for DNS metrics emitted by .NET. ### Metric: `dns.lookup.duration` This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index fd1f9c99fa..6d0bd2f238 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -77,7 +77,7 @@ Notes: ### Metric: `http.client.connection.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. @@ -106,7 +106,7 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. ### Metric: `http.client.request.time_in_queue` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 5bbb8d5d34..51c32f64bf 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -93,7 +93,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ## Metric: `kestrel.connection.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. @@ -474,7 +474,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ## Metric: `kestrel.tls_handshake.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index e4b0d24cdd..5f3b0632f4 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -18,7 +18,7 @@ This article defines semantic conventions for SignalR metrics emitted by .NET co ## Metric: `signalr.server.connection.duration` this metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index b709aaf9d0..136a761e61 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -7,8 +7,8 @@ linkTitle: Logs **Status**: [Stable][DocumentStatus] This document defines semantic conventions for recording exceptions on -[logs](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md#emit-an-event) -emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger). +[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-a-logrecord) and [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-an-event) +emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#logger). @@ -21,7 +21,7 @@ emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry ## Recording an Exception Exceptions SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#logger) emit operations. Exceptions MAY be recorded on "logs" or "events" depending on the context. @@ -33,7 +33,7 @@ the language runtime. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index c61a9a7f2f..9b1ce60960 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -163,7 +163,7 @@ be ` process`. If there are multiple sources in the batch, the nam For every message in the event, the [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/context/api-propagators.md) and added as a link to the span. This means the span may have as many links as messages in the batch. See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. @@ -176,7 +176,7 @@ See [compatibility](../non-normative/compatibility/aws.md#context-propagation) f For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span corresponding to the SQS event. The [message system attributes][] (not message attributes, which are provided by the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/context/api-propagators.md) and +parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/context/api-propagators.md) and added as a link to the span. See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info. diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 32920096f0..bce085ebdb 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -46,7 +46,7 @@ The following metrics are recorded by the FaaS instance. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -86,7 +86,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -306,7 +306,7 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 1f601e9e71..12940ea8fe 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -7,8 +7,8 @@ linkTitle: Logs **Status**: [Experimental][DocumentStatus] This document defines semantic conventions for recording feature flag evaluations as -a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the -[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#emit-a-logrecord). +a [log record](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) emitted through the +[Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-a-logrecord). This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. @@ -32,14 +32,14 @@ This can be used to determine the impact a feature has on a request, enabling en ## Recording an Evaluation Feature flag evaluations SHOULD be recorded as attributes on the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/api.md#logger) emit +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#logger) emit operations. Evaluations MAY be recorded on "logs" or "events" depending on the context. ## Evaluation event The table below indicates which attributes should be added to the -[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. +[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 8efa2376e7..443a16e7f3 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -501,4 +501,4 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRequired]: /docs/general/metric-requirement-level.md#required [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended -[ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters +[ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index 54ebc54f37..df77481ecb 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -27,7 +27,7 @@ instrumented protocol such as HTTP. ## Name -GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. diff --git a/docs/general/events.md b/docs/general/events.md index 4e80862f13..15f0cf5207 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -15,7 +15,7 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t Examples of Events might include things like uncaught exceptions, button clicks, user logout, network connection severed, etc. -In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md) that conforms to the conventions included here. +In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md) that conforms to the conventions included here. In addition to a required name, an Event may contain a _payload_ (body) of any type permitted by the [LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body). @@ -32,7 +32,7 @@ structure and semantics will also be defined. * An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md). -* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) +* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the named event. @@ -47,7 +47,7 @@ structure and semantics will also be defined. Recommendations for defining events: * Use the _payload_ (body) to represent the details of the event instead of a - collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) + collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-an-event) diff --git a/docs/general/logs.md b/docs/general/logs.md index 030396b0d5..17bd676bbd 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -28,7 +28,7 @@ The following semantic conventions for logs are defined: * [Feature Flags](/docs/feature-flags/feature-flags-logs.md): Semantic attributes that may be used in describing feature flag evaluations in logs. Apart from semantic conventions for logs, [events](events.md), [traces](trace.md), and [metrics](metrics.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General log identification attributes @@ -61,7 +61,7 @@ The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID This section describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log. -**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) as `an immutable representation of the entity producing telemetry`. +**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) as `an immutable representation of the entity producing telemetry`. The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission. As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes. diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 961abaedf4..63a24f3179 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -36,7 +36,7 @@ The following semantic conventions surrounding metrics are defined: * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also -defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with +defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). ## General Guidelines @@ -87,7 +87,7 @@ usable. When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the -[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/compatibility/prometheus_and_openmetrics.md). +[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/compatibility/prometheus_and_openmetrics.md). ### Instrument Units diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md index b6ed152711..91246b7247 100644 --- a/docs/general/recording-errors.md +++ b/docs/general/recording-errors.md @@ -126,4 +126,4 @@ public boolean createIfNotExists(String resourceId) throws IOException { ``` [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status +[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#set-status diff --git a/docs/general/trace.md b/docs/general/trace.md index 591e306ad1..a83586d535 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -33,7 +33,7 @@ The following semantic conventions for spans are defined: * [RPC/RMI](/docs/rpc/rpc-spans.md): For remote procedure call (e.g., gRPC) spans. Apart from semantic conventions for traces, [metrics](metrics.md), [logs](logs.md), and [events](events.md), -OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with their own +OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 60c9b9f09e..6b7de43d56 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -64,7 +64,7 @@ This metric is required. When this metric is reported alongside an HTTP server span, the metric value SHOULD be the same as the HTTP server span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -511,7 +511,7 @@ This metric is required. When this metric is reported alongside an HTTP client span, the metric value SHOULD be the same as the HTTP client span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -864,7 +864,7 @@ This metric is optional. ### Metric: `http.client.connection.duration` This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. This metric is optional. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 2ac016a237..7b70586d03 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -64,7 +64,7 @@ and various HTTP versions like 1.1, 2 and SPDY. ## Name -HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). HTTP span names SHOULD be `{method} {target}` if there is a (low-cardinality) `target` available. If there is no (low-cardinality) `{target}` available, HTTP span names SHOULD be `{method}`. @@ -86,7 +86,7 @@ Instrumentation MUST NOT default to using URI path as a `{target}`. ## Status -[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the +[Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#set-status) MUST be left unset if HTTP status code was in the 1xx, 2xx or 3xx ranges, unless there was another error (e.g., network error receiving the response body; or 3xx codes with max redirects exceeded), in which case status MUST be set to `Error`. @@ -746,4 +746,4 @@ Span name: `POST /uploads/:document_id`. | `error.type` | `WebSocketDisconnect` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status -[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/sdk.md#span-processor +[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/sdk.md#span-processor diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index 87e6ff8467..3a2226e0cd 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -53,7 +53,7 @@ When this metric is reported alongside a messaging span, the metric value SHOULD This metric is [required][MetricRequired]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -367,7 +367,7 @@ When this metric is reported alongside a messaging process span, the metric valu This metric is [required][MetricRequired] for push-based message delivery and is [recommended][MetricRecommended] for processing operations instrumented for pull-based scenarios. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 02cbbc2691..182e363874 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -188,7 +188,7 @@ in such a way that it cannot be changed by intermediaries. ### Span name -Messaging spans SHOULD follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). +Messaging spans SHOULD follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#span). diff --git a/docs/resource/README.md b/docs/resource/README.md index b687ade923..7bd51bed02 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -9,7 +9,7 @@ path_base_for_github_subdir: **Status**: [Mixed][DocumentStatus] -This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from +This document defines standard attributes for resources. These attributes are typically used in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from [OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md). @@ -58,14 +58,14 @@ Given their significance some resource attributes are treated specifically as de ### Semantic Attributes with Dedicated Environment Variable These are the attributes which MAY be configurable via a dedicated environment variable -as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/configuration/sdk-environment-variables.md): +as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/configuration/sdk-environment-variables.md): - [`service.name`](#service) ### Semantic Attributes with SDK-provided Default Value These are the attributes which MUST be provided by the SDK -as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md#sdk-provided-resource-attributes): +as specified in the [Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md#sdk-provided-resource-attributes): - [`service.name`](#service) - [`telemetry.sdk` group](#telemetry-sdk) diff --git a/docs/resource/cloudfoundry.md b/docs/resource/cloudfoundry.md index 7149437f8f..d2876e1c58 100644 --- a/docs/resource/cloudfoundry.md +++ b/docs/resource/cloudfoundry.md @@ -201,4 +201,4 @@ should be used. The `system.instance.id` should be set to `spec.id`. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/document-status.md diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 57e1f3bd0c..03f7ae4658 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -65,6 +65,6 @@ Below is a table of attributes that SHOULD be included on client and server Conn ## Connect RPC Status -If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. +If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 11fbc5807f..bc1dd57361 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -65,10 +65,10 @@ Below is a table of attributes that SHOULD be included on client and server gRPC ## gRPC Status The table below describes when -the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#set-status) MUST be set +the [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#set-status) MUST be set to `Error` or remain unset depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) -and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#spankind). +and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/trace/api.md#spankind). | gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status | |---|---|---| diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 2536649713..241a2fce4c 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -206,7 +206,7 @@ This metric is obtained by subscribing to [`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.1, 1, 10 ]`. diff --git a/docs/runtime/nodejs-metrics.md b/docs/runtime/nodejs-metrics.md index ab4c498b63..8e2b385853 100644 --- a/docs/runtime/nodejs-metrics.md +++ b/docs/runtime/nodejs-metrics.md @@ -246,6 +246,6 @@ This metric is [recommended][MetricRecommended]. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/document-status.md [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended [Eventloop]: https://nodejs.org/api/perf_hooks.html#perf_hooksmonitoreventloopdelayoptions diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md index c26f429c16..f593a6bda3 100644 --- a/docs/runtime/v8js-metrics.md +++ b/docs/runtime/v8js-metrics.md @@ -32,7 +32,7 @@ This document describes semantic conventions for V8 JS Engine Runtime metrics in This metric is [recommended][MetricRecommended]. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/metrics/api.md#instrument-advisory-parameters) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.1, 1, 10 ]`. @@ -228,5 +228,5 @@ This metric is [recommended][MetricRecommended]. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/document-status.md [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index a57c766eb0..33b6650c5e 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -6,9 +6,9 @@ # Set this to the version number you want to CHANGE in URLs in the repository. -PREVIOUS_SPECIFICATION_VERSION="v1.37.0" +PREVIOUS_SPECIFICATION_VERSION="v1.39.0" # Set this to the version number you want to KEEP in URLs in the repository. -LATEST_SPECIFICATION_VERSION="v1.39.0" +LATEST_SPECIFICATION_VERSION="v1.40.0" # The specific pattern we look for when replacing URLs SPECIFICATION_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/tree/" SPECIFICATION_BLOB_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/blob/" @@ -30,6 +30,6 @@ fix_file() { important_files=("docs" "model" "README.md") # TODO - limit to markdown/yaml files? -find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do +find "${important_files[@]}" -type f -not -path '*/.*' -not -path '*.png' -print0 | while read -d $'\0' file; do fix_file "$file" done From f80534875ebeba7b009dc34bf1c5ea98996d37ed Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Sat, 18 Jan 2025 12:41:08 -0800 Subject: [PATCH 16/39] Fix website linking (#1766) --- docs/general/naming.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/general/naming.md b/docs/general/naming.md index 62921a4ae9..ad6587f97b 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -1,3 +1,7 @@ + + # Naming **Status**: [Stable][DocumentStatus], Unless otherwise specified. From f249173193c50bb985cd59116f76e753ed21f392 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 05:11:38 -0800 Subject: [PATCH 17/39] Add clarification about `OTEL_SEMCONV_STABILITY_OPT_IN` (#1758) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/non-normative/db-migration.md | 4 ++++ docs/non-normative/http-migration.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index 596a665a2c..bd6d2039bd 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -22,6 +22,10 @@ updated to the stable database semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable database conventions. +> [!NOTE] +> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating +> from an experimental semantic convention to its initial stable version. + ## Summary of changes This section summarizes the changes made to the HTTP semantic conventions diff --git a/docs/non-normative/http-migration.md b/docs/non-normative/http-migration.md index d0c70fe68f..959648b76c 100644 --- a/docs/non-normative/http-migration.md +++ b/docs/non-normative/http-migration.md @@ -29,6 +29,10 @@ updated to the stable HTTP semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable HTTP and networking conventions. +> [!NOTE] +> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating +> from an experimental semantic convention to its initial stable version. + ## Summary of changes This section summarizes the changes made to the HTTP semantic conventions From eae7a310558039380b3bbc15f28e3e606028df9a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 05:13:29 -0800 Subject: [PATCH 18/39] Fix link (#1761) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/general/recording-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md index 91246b7247..ea5189eadc 100644 --- a/docs/general/recording-errors.md +++ b/docs/general/recording-errors.md @@ -61,7 +61,7 @@ When the operation ends with an error, instrumentation: When the operation fails with an exception, the span status description SHOULD be set to the exception message. -Refer to the [recording exceptions](#recording-errors) on capturing exception +Refer to the [recording exceptions](#recording-exceptions) on capturing exception details. ## Recording errors on metrics From b810141201bb6b9b6e1c4e038f4d9d878056777d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 08:48:07 -0800 Subject: [PATCH 19/39] Move release instructions to RELEASING.md (#1762) --- CONTRIBUTING.md | 28 ---------------------------- RELEASING.md | 26 ++++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 28 deletions(-) create mode 100644 RELEASING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68755d1cf2..e2b4b153e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,6 @@ requirements and recommendations. - [Update the tables of content](#update-the-tables-of-content) - [Markdown link check](#markdown-link-check) - [Updating the referenced specification version](#updating-the-referenced-specification-version) -- [Making a Release](#making-a-release) - [Merging existing ECS conventions](#merging-existing-ecs-conventions) @@ -415,33 +414,6 @@ make markdown-link-check 4. Run the script from the root directory, e.g. `semantic-conventions$ ./internal/tools/update_specification_version.sh`. 5. Add all modified files to the change submit and submit a PR. -## Making a Release - -- Ensure the referenced specification version is up to date. Use - [tooling to update the spec](#updating-the-referenced-specification-version) - if needed. -- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) - against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. -- Create a staging branch for the release. - - Update `schema-next.yaml` file and move to `schemas/{version}` - - Ensure the `next` version is appropriately configured as the `{version}`. - - Copy `schema-next.yaml` to `schemas/{version}`. - - Add `next` as a version in `schema-next.yaml` version. - - Run `make chlog-update VERSION=v{version}` - - `make chlog-update` will clean up all the current `.yaml` files inside the - `.chloggen` folder automatically - - Double check that `CHANGELOG.md` is updated with the proper `v{version}` - - Send staging branch as PR for review. -- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): - - Set title and tag to `v{version}` - - Set target to the commit of the merged release PR - - Copy changelog to the release notes - - Verify that the release looks like expected - - Publish release - -New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR) -eventually results in new version of schema file being published. - ## Merging existing ECS conventions The Elastic Common Schema (ECS) is being merged into OpenTelemetry Semantic diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000000..18f54b3347 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,26 @@ +# Making a Release + +- Ensure the referenced specification version is up to date. Use + [tooling to update the spec](./CONTRIBUTING.md#updating-the-referenced-specification-version) + if needed. +- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) + against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. +- Create a staging branch for the release. + - Update `schema-next.yaml` file and move to `schemas/{version}` + - Ensure the `next` version is appropriately configured as the `{version}`. + - Copy `schema-next.yaml` to `schemas/{version}`. + - Add `next` as a version in `schema-next.yaml` version. + - Run `make chlog-update VERSION=v{version}` + - `make chlog-update` will clean up all the current `.yaml` files inside the + `.chloggen` folder automatically + - Double check that `CHANGELOG.md` is updated with the proper `v{version}` + - Send staging branch as PR for review. +- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): + - Set title and tag to `v{version}` + - Set target to the commit of the merged release PR + - Copy changelog to the release notes + - Verify that the release looks like expected + - Publish release + +New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR) +eventually results in new version of schema file being published. From 77f0b70d36c42f072ee1391afd681774cea4e39c Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 20 Jan 2025 10:20:16 -0800 Subject: [PATCH 20/39] Release automation (#1765) Co-authored-by: Liudmila Molkova --- .github/workflows/prepare-release.yml | 59 +++++++++++++++++++ .../scripts/use-cla-approved-github-bot.sh | 4 ++ 2 files changed, 63 insertions(+) create mode 100644 .github/workflows/prepare-release.yml create mode 100755 .github/workflows/scripts/use-cla-approved-github-bot.sh diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml new file mode 100644 index 0000000000..f53766c277 --- /dev/null +++ b/.github/workflows/prepare-release.yml @@ -0,0 +1,59 @@ +name: Prepare release +on: + workflow_dispatch: + inputs: + version: + description: 'The version to release, e.g. 1.30.0' + required: true + +jobs: + create-pull-request: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate version + run: | + version=${{ inputs.version }} + if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "unexpected version: $version" + exit 1 + fi + + - name: Use CLA approved github bot + run: .github/workflows/scripts/use-cla-approved-github-bot.sh + + - name: Update schema files + run: | + if ! grep -q "^ next:$" schema-next.yaml; then + echo "String 'next:' not found in the file" + exit 1 + fi + + version=${{ inputs.version }} + sed -i "0,/^ next:$/s// $version:/" schema-next.yaml + cp schema-next.yaml "schemas/$version" + git add "schemas/$version" + + sed -i "0,/^ $version:$/s// next:\n $version:/" schema-next.yaml + + - name: Update change log + run: | + make chlog-update VERSION=v${{ inputs.version }} + + - name: Create pull request + env: + # not using secrets.GITHUB_TOKEN since pull requests from that token do not run workflows + GH_TOKEN: ${{ secrets.OPENTELEMETRYBOT_GITHUB_TOKEN }} + run: | + version=${{ inputs.version }} + message="Prepare release v${version}" + body="Prepare release \`v${version}\`." + branch="opentelemetrybot/prepare-release-v${version}" + + git checkout -b $branch + git commit -a -m "$message" + git push --set-upstream origin $branch + gh pr create --title "$message" \ + --body "$body" \ + --base main diff --git a/.github/workflows/scripts/use-cla-approved-github-bot.sh b/.github/workflows/scripts/use-cla-approved-github-bot.sh new file mode 100755 index 0000000000..a4c68b0e30 --- /dev/null +++ b/.github/workflows/scripts/use-cla-approved-github-bot.sh @@ -0,0 +1,4 @@ +#!/bin/bash -e + +git config user.name opentelemetrybot +git config user.email 107717825+opentelemetrybot@users.noreply.github.com From 0e109d266238cbd2ca5025f54edd51d5f18019b3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 20 Jan 2025 13:56:50 -0800 Subject: [PATCH 21/39] Label all new issues with `triage:needs-triage` label (#1767) --- .github/ISSUE_TEMPLATE/bug_report.yaml | 2 +- .github/ISSUE_TEMPLATE/change_proposal.yaml | 2 +- .github/ISSUE_TEMPLATE/new-conventions.yaml | 2 +- .../workflows/scripts/prepare-new-issue.sh | 29 +++++++------------ 4 files changed, 14 insertions(+), 21 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 43a6c3c748..252669d92b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -1,6 +1,6 @@ name: Bug report description: Create a report to help us improve -labels: ["bug", "triage:needs-triage"] +labels: ["bug"] body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index bb0d28736a..6eab59ae69 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -1,6 +1,6 @@ name: Propose changes to existing conventions description: Propose changes you'd like to be added to existing conventions -labels: ["enhancement", "triage:needs-triage"] +labels: ["enhancement"] body: - type: dropdown id: area diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index eb43279195..f4e3498651 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -1,6 +1,6 @@ name: Propose new semantic conventions description: Propose new conventions you'd like to be part of the OpenTelemetry project -labels: ["enhancement", "triage:needs-triage", "experts needed"] +labels: ["enhancement", "experts needed"] body: - type: markdown attributes: diff --git a/.github/workflows/scripts/prepare-new-issue.sh b/.github/workflows/scripts/prepare-new-issue.sh index 6142e5b3b8..391fc698ab 100755 --- a/.github/workflows/scripts/prepare-new-issue.sh +++ b/.github/workflows/scripts/prepare-new-issue.sh @@ -28,7 +28,7 @@ if [[ -z "${ISSUE:-}" || -z "${BODY:-}" || -z "${OPENER:-}" ]]; then exit 0 fi -LABELS="" +LABELS="triage:needs-triage" AREAS_SECTION_START=$( (echo "${BODY}" | grep -n '### Area(s)' | awk '{ print $1 }' | grep -oE '[0-9]+') || echo '-1' ) BODY_AREAS="" @@ -45,26 +45,19 @@ for AREA in ${BODY_AREAS}; do continue fi - if [[ -n "${LABELS}" ]]; then - LABELS+="," - fi - LABELS+="${AREA}" + LABELS+=",${AREA}" done -if [[ -v PINGED_AREAS[@] ]]; then - echo "The issue was associated with areas:" "${!PINGED_AREAS[@]}" +if [[ -v BODY_AREAS[@] ]]; then + echo "The issue was associated with areas:" "${!BODY_AREAS[@]}" else echo "No related areas were given" fi -if [[ -n "${LABELS}" ]]; then - # Notes on this call: - # 1. Labels will be deduplicated by the GitHub CLI. - # 2. The call to edit the issue will fail if any of the - # labels doesn't exist. We can be reasonably sure that - # all labels will exist since they come from a known set. - echo "Adding the following labels: ${LABELS//,/ /}" - gh issue edit "${ISSUE}" --add-label "${LABELS}" || true -else - echo "No labels were found to add" -fi +# Notes on this call: +# 1. Labels will be deduplicated by the GitHub CLI. +# 2. The call to edit the issue will fail if any of the +# labels doesn't exist. We can be reasonably sure that +# all labels will exist since they come from a known set. +echo "Adding the following labels: ${LABELS//,/ /}" +gh issue edit "${ISSUE}" --add-label "${LABELS}" || true From c828bebb75977b2139b53c2a0aad89b9bff767e3 Mon Sep 17 00:00:00 2001 From: Christos Markou Date: Tue, 21 Jan 2025 12:54:27 +0200 Subject: [PATCH 22/39] Add k8s.namespace.phase metric and attribute (#1668) Signed-off-by: ChrsMark Co-authored-by: Jina Jain --- .chloggen/add_k8s_ns_phase.yaml | 22 ++++++++++++++ docs/attributes-registry/k8s.md | 25 ++++++++++++---- docs/non-normative/k8s-migration.md | 19 ++++++++++++ docs/system/k8s-metrics.md | 45 +++++++++++++++++++++++++++++ model/k8s/metrics.yaml | 15 ++++++++++ model/k8s/registry.yaml | 30 +++++++++++++++---- 6 files changed, 144 insertions(+), 12 deletions(-) create mode 100755 .chloggen/add_k8s_ns_phase.yaml diff --git a/.chloggen/add_k8s_ns_phase.yaml b/.chloggen/add_k8s_ns_phase.yaml new file mode 100755 index 0000000000..b7813687e3 --- /dev/null +++ b/.chloggen/add_k8s_ns_phase.yaml @@ -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: k8s + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add k8s.namespace.phase metric along with the respective attribute + +# 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: [1668] + +# (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: diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md index 784ab78b5e..ab3c706dc8 100644 --- a/docs/attributes-registry/k8s.md +++ b/docs/attributes-registry/k8s.md @@ -29,6 +29,7 @@ Kubernetes resource attributes. | `k8s.job.name` | string | The name of the Job. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.namespace.phase` | string | The phase of the K8s namespace. [2] | `active`; `terminating` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.node.name` | string | The name of the Node. | `node-1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.pod.annotation.` | string | The annotation key-value pairs placed on the Pod, the `` being the annotation name, the value being the annotation value. | `k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets=true`; `k8s.pod.annotation.mycompany.io/arch=x64`; `k8s.pod.annotation.data=` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -65,18 +66,30 @@ Which states: Therefore, UIDs between clusters should be extremely unlikely to conflict. +**[2] `k8s.namespace.phase`:** This attribute aligns with the `phase` field of the +[K8s NamespaceStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#namespacestatus-v1-core) + +--- + +`k8s.namespace.phase` 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 | +|---|---|---| +| `active` | Active namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `terminating` | Terminating namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + --- `k8s.volume.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 | |---|---|---| -| `configMap` | A [configMap](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `downwardAPI` | A [downwardAPI](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `emptyDir` | An [emptyDir](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `local` | A [local](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `persistentVolumeClaim` | A [persistentVolumeClaim](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `secret` | A [secret](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `configMap` | A [configMap](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `downwardAPI` | A [downwardAPI](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `emptyDir` | An [emptyDir](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `local` | A [local](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `persistentVolumeClaim` | A [persistentVolumeClaim](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `secret` | A [secret](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Deprecated Kubernetes Attributes diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index 39e7d464c5..022be1d594 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -51,6 +51,7 @@ and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then: - [K8s DaemonSet metrics](#k8s-daemonset-metrics) - [K8s Job metrics](#k8s-job-metrics) - [K8s Cronjob metrics](#k8s-cronjob-metrics) + - [K8s Namespace metrics](#k8s-namespace-metrics) @@ -234,3 +235,21 @@ The changes in their metric types are the following: | `k8s.cronjob.active_jobs` (type: `gauge`) | `k8s.cronjob.active_jobs` (type: `updowncounter`) | + +### K8s Namespace metrics + +The K8s Namespace metrics implemented by the Collector and specifically the +[k8scluster](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.115.0/receiver/k8sclusterreceiver/documentation.md) +receiver were introduced as semantic conventions in +[#1649](https://github.com/open-telemetry/semantic-conventions/pull/1668) (TODO: replace with SemConv version once +available). + +The changes in their metrics are the following: + + + +| Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | +|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| +| `k8s.namespace.phase` (type: `gauge`), 1 for active and 0 for terminating | `k8s.namespace.phase` (type: `updowncounter`), with the attribute `k8s.namespace.phase` indicating the phase | + + diff --git a/docs/system/k8s-metrics.md b/docs/system/k8s-metrics.md index e95ba7fec1..6211d31c6e 100644 --- a/docs/system/k8s-metrics.md +++ b/docs/system/k8s-metrics.md @@ -65,6 +65,8 @@ and therefore inherit its attributes, like `k8s.pod.name` and `k8s.pod.uid`. - [Metric: `k8s.job.max_parallel_pods`](#metric-k8sjobmax_parallel_pods) - [CronJob Metrics](#cronjob-metrics) - [Metric: `k8s.cronjob.active_jobs`](#metric-k8scronjobactive_jobs) +- [Namespace Metrics](#namespace-metrics) + - [Metric: `k8s.namespace.phase`](#metric-k8snamespacephase) @@ -1028,5 +1030,48 @@ This metric SHOULD, at a minimum, be reported against a +## Namespace Metrics + +**Description:** Namespace level metrics captured under the namespace `k8s.namespace`. + +### Metric: `k8s.namespace.phase` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `k8s.namespace.phase` | UpDownCounter | `{namespace}` | Describes number of K8s namespaces that are currently in a given phase. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This metric SHOULD, at a minimum, be reported against a +[`k8s.namespace`](../resource/k8s.md#namespace) resource. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`k8s.namespace.phase`](/docs/attributes-registry/k8s.md) | string | The phase of the K8s namespace. [1] | `active`; `terminating` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `k8s.namespace.phase`:** This attribute aligns with the `phase` field of the +[K8s NamespaceStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#namespacestatus-v1-core) + +--- + +`k8s.namespace.phase` 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 | +|---|---|---| +| `active` | Active namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `terminating` | Terminating namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/k8s/metrics.yaml b/model/k8s/metrics.yaml index 1301662270..c091a5e4a0 100644 --- a/model/k8s/metrics.yaml +++ b/model/k8s/metrics.yaml @@ -442,3 +442,18 @@ groups: This metric SHOULD, at a minimum, be reported against a [`k8s.cronjob`](../resource/k8s.md#cronjob) resource. + + # k8s.namespace.* metrics + - id: metric.k8s.namespace.phase + type: metric + metric_name: k8s.namespace.phase + stability: experimental + brief: "Describes number of K8s namespaces that are currently in a given phase." + instrument: updowncounter + unit: "{namespace}" + note: | + This metric SHOULD, at a minimum, be reported against a + [`k8s.namespace`](../resource/k8s.md#namespace) resource. + attributes: + - ref: k8s.namespace.phase + requirement_level: required diff --git a/model/k8s/registry.yaml b/model/k8s/registry.yaml index e1e0107fcc..c9b639b697 100644 --- a/model/k8s/registry.yaml +++ b/model/k8s/registry.yaml @@ -192,25 +192,43 @@ groups: members: - id: persistent_volume_claim value: 'persistentVolumeClaim' - brief: "A [persistentVolumeClaim](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume" + brief: "A [persistentVolumeClaim](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) volume" stability: experimental - id: config_map value: 'configMap' - brief: "A [configMap](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume" + brief: "A [configMap](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#configmap) volume" stability: experimental - id: downward_api value: 'downwardAPI' - brief: "A [downwardAPI](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume" + brief: "A [downwardAPI](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#downwardapi) volume" stability: experimental - id: empty_dir value: 'emptyDir' - brief: "An [emptyDir](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume" + brief: "An [emptyDir](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume" stability: experimental - id: secret value: 'secret' - brief: "A [secret](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume" + brief: "A [secret](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#secret) volume" stability: experimental - id: local value: 'local' - brief: "A [local](https://v1-29.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume" + brief: "A [local](https://v1-30.docs.kubernetes.io/docs/concepts/storage/volumes/#local) volume" + stability: experimental + - id: k8s.namespace.phase + stability: experimental + brief: > + The phase of the K8s namespace. + note: | + This attribute aligns with the `phase` field of the + [K8s NamespaceStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#namespacestatus-v1-core) + examples: [ "active", "terminating" ] + type: + members: + - id: active + value: 'active' + brief: "Active namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase)" + stability: experimental + - id: terminating + value: 'terminating' + brief: "Terminating namespace phase as described by [K8s API](https://pkg.go.dev/k8s.io/api@v0.31.3/core/v1#NamespacePhase)" stability: experimental From efd7f1ec352da4947f868256bfba986a95114931 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 21 Jan 2025 07:24:07 -0800 Subject: [PATCH 23/39] Check and close milestone if any as part of release steps (#1774) --- RELEASING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/RELEASING.md b/RELEASING.md index 18f54b3347..1cb7183309 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,5 +1,7 @@ # Making a Release +- Close the [release milestone](https://github.com/open-telemetry/semantic-conventions/milestones) + if there is one. - Ensure the referenced specification version is up to date. Use [tooling to update the spec](./CONTRIBUTING.md#updating-the-referenced-specification-version) if needed. From 2eb5802266c9cf141690aaeba6a4c5d8891bf271 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 21 Jan 2025 13:22:02 -0800 Subject: [PATCH 24/39] Update issue templates (simplify and clarify the process) (#1771) Co-authored-by: Trask Stalnaker --- .github/ISSUE_TEMPLATE/bug_report.yaml | 27 ++--- .github/ISSUE_TEMPLATE/change_proposal.yaml | 24 ++--- .github/ISSUE_TEMPLATE/new-conventions.yaml | 114 +++----------------- 3 files changed, 30 insertions(+), 135 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 252669d92b..9424ec95d2 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -15,8 +15,10 @@ body: description: Which area(s) does your bug report concern? If none fits, please select `area:other` multiple: true options: + - docs + - tooling + - schema - area:other - - area:docs # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` # DO NOT manually edit it. # Start semconv area list @@ -90,27 +92,12 @@ body: # End semconv area list - type: textarea attributes: - label: What happened? - description: Please provide as much detail as you reasonably can. - value: | - ## Description - - ## Steps to Reproduce (if any) - - ## Expected Result - - ## Actual Result - validations: - required: true - - - type: input - attributes: - label: Semantic convention version - description: What version did you use? (e.g., `v1.24.0`, `1eb551b`, etc) + label: What's the problem? + description: Please describe the problem as precisely as you reasonably can. validations: required: true - type: textarea attributes: - label: Additional context - description: Any additional information you think may be relevant to this issue. + label: Describe the solution you'd like + description: A clear and concise description of solution you'd like to see. diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 6eab59ae69..64ea39cecb 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -1,6 +1,5 @@ -name: Propose changes to existing conventions -description: Propose changes you'd like to be added to existing conventions -labels: ["enhancement"] +name: Propose enhancement to existing conventions +description: Propose changes you'd like to see body: - type: dropdown id: area @@ -9,6 +8,9 @@ body: description: Which area(s) does your change request concern? multiple: true options: + - docs + - tooling + - schema # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` # DO NOT manually edit it. # Start semconv area list @@ -82,21 +84,11 @@ body: # End semconv area list - type: textarea attributes: - label: Is your change request related to a problem? Please describe. - description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + label: What's missing? + description: Please describe the use-case or scenario that is not covered by the existing conventions. validations: required: true - type: textarea attributes: label: Describe the solution you'd like - description: A clear and concise description of what you want to happen. - validations: - required: true - - type: textarea - attributes: - label: Describe alternatives you've considered - description: A clear and concise description of any alternative solutions or features you've considered. - - type: textarea - attributes: - label: Additional context - description: Add any other context or screenshots about the feature request here. + description: A clear and concise description of solution you'd like to see. diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index f4e3498651..f1daf6eac4 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -1,111 +1,27 @@ name: Propose new semantic conventions -description: Propose new conventions you'd like to be part of the OpenTelemetry project +description: Propose new conventions you'd like to see in the OpenTelemetry project labels: ["enhancement", "experts needed"] body: - type: markdown attributes: value: | - Please make sure to fill out the entire form below, providing as much context as you can in order to help us triage the proposal as quickly as possible. + Thanks for your interest in contributing to the OpenTelemetry Semantic Conventions! - Before filing the proposal, please be sure you have searched through [existing issues](https://github.com/open-telemetry/semantic-conventions/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aenhancement+label%3Aarea:new) to see if an existing issue covers your proposal. + Substantial changes to the conventions follow [OTel project management] + (https://github.com/open-telemetry/community/blob/main/project-management.md) process + and usually require a group of people who are familiar with the domain, + are involved with instrumentation efforts, and are committed to be the point of contact for + pull requests, issues, and questions in this area. - Additionally, make sure to read and follow the guidelines on [Project Proposal](https://github.com/open-telemetry/community/blob/main/project-management.md#project-management), in case the proposal is for a new set of conventions/working group. - - type: dropdown - id: area - attributes: - label: Area(s) - description: Which area(s) does your new conventions concern? If none fits, please select `area:new` - multiple: true - options: - - area:new - # NOTE: The list below is autogenerated using `make generate-gh-issue-templates` - # DO NOT manually edit it. - # Start semconv area list - - area:android - - area:artifact - - area:aspnetcore - - area:aws - - area:azure - - area:browser - - area:cicd - - area:client - - area:cloud - - area:cloudevents - - area:cloudfoundry - - area:code - - area:container - - area:cpu - - area:db - - area:deployment - - area:destination - - area:device - - area:disk - - area:dns - - area:dotnet - - area:error - - area:exception - - area:faas - - area:feature-flag - - area:file - - area:gcp - - area:gen-ai - - area:geo - - area:go - - area:graphql - - area:hardware - - area:heroku - - area:host - - area:http - - area:jvm - - area:k8s - - area:linux - - area:log - - area:messaging - - area:network - - area:nodejs - - area:oci - - area:opentracing - - area:os - - area:otel - - area:peer - - area:process - - area:profile - - area:rpc - - area:security-rule - - area:server - - area:service - - area:session - - area:signalr - - area:source - - area:system - - area:telemetry - - area:test - - area:thread - - area:tls - - area:url - - area:user - - area:user-agent - - area:v8js - - area:vcs - - area:webengine - # End semconv area list - - type: textarea - attributes: - label: Is your change request related to a problem? Please describe. - description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - validations: - required: true + Creating a new issue here is a great first step to find others interested in collaborating. - type: textarea attributes: - label: Describe the solution you'd like - description: A clear and concise description of what you want to happen. + label: Propose new conventions + description: | + Please provide a brief description of the conventions, including + telemetry signals you'd like to define. + + Consider specifying which instrumentations or systems would implement these + conventions and the benefits they would bring to the ecosystem. validations: required: true - - type: textarea - attributes: - label: Describe alternatives you've considered - description: A clear and concise description of any alternative solutions or features you've considered. - - type: textarea - attributes: - label: Additional context - description: Add any other context or screenshots about the feature request here. From 8d43ef0bcc0886d5e9dbcdf884d9b0463b33f87e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 22 Jan 2025 09:18:47 -0800 Subject: [PATCH 25/39] Add warning to db migration guide (#1785) --- docs/non-normative/db-migration.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md index bd6d2039bd..91135a9299 100644 --- a/docs/non-normative/db-migration.md +++ b/docs/non-normative/db-migration.md @@ -1,5 +1,9 @@ # Database semantic convention stability migration guide +> [!WARNING] +> This document is a work in progress and the database semantic conventions +> have not been marked stable yet and changes are still being made. + Due to the significant number of modifications and the extensive user base affected by them, existing database instrumentations published by OpenTelemetry are required to implement a migration plan that will assist users in From 578c4bf60ba4c9f744a0745c29298197b8e51d07 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 22 Jan 2025 10:15:11 -0800 Subject: [PATCH 26/39] Update release instructions (#1778) --- RELEASING.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 1cb7183309..683e009dde 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,4 +1,6 @@ -# Making a Release +# Releasing + +## Preparing a new release - Close the [release milestone](https://github.com/open-telemetry/semantic-conventions/milestones) if there is one. @@ -7,17 +9,13 @@ if needed. - Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any. -- Create a staging branch for the release. - - Update `schema-next.yaml` file and move to `schemas/{version}` - - Ensure the `next` version is appropriately configured as the `{version}`. - - Copy `schema-next.yaml` to `schemas/{version}`. - - Add `next` as a version in `schema-next.yaml` version. - - Run `make chlog-update VERSION=v{version}` - - `make chlog-update` will clean up all the current `.yaml` files inside the - `.chloggen` folder automatically - - Double check that `CHANGELOG.md` is updated with the proper `v{version}` - - Send staging branch as PR for review. -- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): +- Run the [prepare release workflow](https://github.com/open-telemetry/semantic-conventions/actions/workflows/prepare-release.yml). + - Review and merge the pull request that it creates. + - Note: the PR will need to be closed and the workflow re-run if any non-chore PRs are merged to `main` while the PR is open. + +## Making the release + +- Create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new): - Set title and tag to `v{version}` - Set target to the commit of the merged release PR - Copy changelog to the release notes From 68b0afaf20c05933fe1ffc3a9cb498d6c97ea938 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 22 Jan 2025 10:45:29 -0800 Subject: [PATCH 27/39] Don't render deprecated enum members (#1764) --- docs/attributes-registry/db.md | 5 ----- docs/attributes-registry/messaging.md | 2 -- docs/attributes-registry/system.md | 1 - templates/registry/markdown/enum_macros.j2 | 2 +- 4 files changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 6877905356..76bebb23a1 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -88,12 +88,9 @@ Semantic conventions for individual database systems SHOULD document what `db.re | Value | Description | Stability | |---|---|---| | `adabas` | Adabas (Adaptable Database System) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cache` | Deprecated, use `intersystems_cache` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `intersystems_cache`. | | `cassandra` | Apache Cassandra | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `clickhouse` | ClickHouse | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cloudscape` | Deprecated, use `other_sql` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `other_sql`. | | `cockroachdb` | CockroachDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `coldfusion` | Deprecated, no replacement at this time. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | | `cosmosdb` | Microsoft Azure Cosmos DB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchbase` | Couchbase | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `couchdb` | CouchDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -104,7 +101,6 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `elasticsearch` | Elasticsearch | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `filemaker` | FileMaker | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `firebird` | Firebird | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `firstsql` | Deprecated, use `other_sql` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `other_sql`. | | `geode` | Apache Geode | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `h2` | H2 | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `hanadb` | SAP HANA | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -122,7 +118,6 @@ Semantic conventions for individual database systems SHOULD document what `db.re | `memcached` | Memcached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mongodb` | MongoDB | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `mssql` | Microsoft SQL Server (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | -| `mssqlcompact` | Deprecated, Microsoft SQL Server Compact is discontinued. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, use `other_sql` instead. | | `mysql` | MySQL (This value has stability level RELEASE CANDIDATE) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `neo4j` | Neo4j | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `netezza` | Netezza | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index b21661f4df..915a4989aa 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -66,9 +66,7 @@ size should be used. | Value | Description | Stability | |---|---|---| | `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch sending scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `deliver` | Deprecated. Use `process` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `process`. | | `process` | One or more messages are processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `publish` | Deprecated. Use `send` instead. | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `send`. | | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `send` | One or more messages are provided for sending to an intermediary. If a single message is sent, the context of the "Send" span can be used as the creation context and no "Create" span needs to be created. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/system.md b/docs/attributes-registry/system.md index 8a6f0166e6..9178e260e9 100644 --- a/docs/attributes-registry/system.md +++ b/docs/attributes-registry/system.md @@ -81,7 +81,6 @@ Describes System Memory attributes | `buffers` | buffers | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cached` | cached | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `free` | free | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `shared` | shared | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, report shared memory usage with `metric.system.memory.shared` metric | | `used` | used | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## System Paging Attributes diff --git a/templates/registry/markdown/enum_macros.j2 b/templates/registry/markdown/enum_macros.j2 index 8dbc583cdc..d20327e14b 100644 --- a/templates/registry/markdown/enum_macros.j2 +++ b/templates/registry/markdown/enum_macros.j2 @@ -1,5 +1,5 @@ {% import 'stability.j2' as stability %} -{% macro filter(member) %}{% if snippet_type is not defined or (member.deprecated is none or member.deprecated == "") %}{{ "True" }}{% else %}{{ "False" }}{% endif %}{% endmacro %} +{% macro filter(member) %}{% if (member.deprecated is none or member.deprecated == "") %}{{ "True" }}{% else %}{{ "False" }}{% endif %}{% endmacro %} {% macro table(enum, notes) %} --- From e2f8527758b01660049598ea5ccbbe25677d8f14 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 22 Jan 2025 10:48:15 -0800 Subject: [PATCH 28/39] Label PRs that contain breaking changes based on the changelog (#1769) Co-authored-by: Trask Stalnaker --- .github/workflows/prepare-new-issue.yml | 3 -- .github/workflows/prepare-new-pr.yml | 32 +++++++++++++++++ .github/workflows/scripts/prepare-new-pr.sh | 39 +++++++++++++++++++++ 3 files changed, 71 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/prepare-new-pr.yml create mode 100755 .github/workflows/scripts/prepare-new-pr.sh diff --git a/.github/workflows/prepare-new-issue.yml b/.github/workflows/prepare-new-issue.yml index 345b7dcd1e..f17a144fca 100644 --- a/.github/workflows/prepare-new-issue.yml +++ b/.github/workflows/prepare-new-issue.yml @@ -10,9 +10,6 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Run update permissions - run: chmod +x ./.github/workflows/scripts/prepare-new-issue.sh - - name: Run prepare-new-issue.sh run: ./.github/workflows/scripts/prepare-new-issue.sh env: diff --git a/.github/workflows/prepare-new-pr.yml b/.github/workflows/prepare-new-pr.yml new file mode 100644 index 0000000000..a8a00fe5eb --- /dev/null +++ b/.github/workflows/prepare-new-pr.yml @@ -0,0 +1,32 @@ +name: 'Prepare new PR' +on: + pull_request_target: + types: [opened, synchronize] + branches: [ 'main*' ] + paths: ['.chloggen/*'] + +jobs: + prepare-new-pr: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + if: ${{ github.repository_owner == 'open-telemetry' }} + steps: + # check out main + - uses: actions/checkout@v4 + # sparse checkout to only get the .chloggen directory + - uses: actions/checkout@v4 + with: + ref: ${{ github.head_ref }} + path: prchangelog + sparse-checkout: .chloggen + + # we're going to run prepare-new-pr script from the main branch + # to parse changelog record from the PR branch. + - name: Run prepare-new-pr.sh + run: ./.github/workflows/scripts/prepare-new-pr.sh + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR: ${{ github.event.pull_request.number }} + PR_CHANGELOG_PATH: prchangelog diff --git a/.github/workflows/scripts/prepare-new-pr.sh b/.github/workflows/scripts/prepare-new-pr.sh new file mode 100755 index 0000000000..dc369b80b4 --- /dev/null +++ b/.github/workflows/scripts/prepare-new-pr.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# +# Copyright The OpenTelemetry Authors +# SPDX-License-Identifier: Apache-2.0 +# +# This script uses chloggen file to get the change_type and adds it as a label to the PR. +# If there are none or multiple changelog files, it will ignore the PR. +# +# Notes: +# - label should exist in the repository in order to add it to the PR. +# - if label already exist, this is a no-op. +# - if any error happens, the script quietly exits with 0. + +if [ -z ${PR:-} ]; then + echo "PR number is required" + exit 1 +fi + +if [ -z ${PR_CHANGELOG_PATH:-} ]; then + echo "PR_CHANGELOG_PATH is required" + exit 1 +fi + +CHLOG="$(gh pr view $PR --json files --jq '.files.[].path | select (. | startswith(".chloggen/"))')" +echo "Change log file(s): ${CHLOG}" + +if [ -z "$CHLOG" ]; then + echo "No changelog found in the PR. Ignoring this change." + exit 0 +fi + +COUNT="$(echo "$CHLOG" | wc -l)" +if [ $COUNT -eq 1 ]; then + CHANGE_TYPE=$(awk -F': ' '/^change_type:/ {print $2}' "$PR_CHANGELOG_PATH/$CHLOG" | xargs) + echo $CHANGE_TYPE + gh pr edit "${PR}" --add-label "${CHANGE_TYPE}" || true +else + echo "Found multiple changelog files. Ignoring this change." +fi From 01bf5e44d2a451cbd94704faf1e94048a2674759 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 22 Jan 2025 12:26:48 -0800 Subject: [PATCH 29/39] Temporarily ignore failing link (#1786) --- .lychee.toml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.lychee.toml b/.lychee.toml index 38599eea36..c60f30a7f4 100644 --- a/.lychee.toml +++ b/.lychee.toml @@ -6,7 +6,9 @@ exclude = [ "^https://www.foo.bar", # excluding links to pull requests and issues is done for performance "^https://github.com/open-telemetry/semantic-conventions/(pull|issues)/\\d+$", - "^https://github.com/open-telemetry/opentelemetry-specification/(pull|issues)/\\d+$" + "^https://github.com/open-telemetry/opentelemetry-specification/(pull|issues)/\\d+$", + # TODO (trask) remove this exclusion after (hopefully) this page comes back up + "^https://docs.oracle.com/en/java/javase/17/docs/api/" ] # better to be safe and avoid failures From d571d3a92cf356e81493631406e5670e693141b3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 22 Jan 2025 18:04:48 -0800 Subject: [PATCH 30/39] Fix broken link to redis HMSET command (#1788) --- docs/database/redis.md | 2 +- model/database/spans.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/database/redis.md b/docs/database/redis.md index 8ef933e7a4..e0f85218a7 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -74,7 +74,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -**[10] `db.query.text`:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. +**[10] `db.query.text`:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. **[11] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../../docs/database/database-spans.md#sanitization-of-dbquerytext). diff --git a/model/database/spans.yaml b/model/database/spans.yaml index b03a9cf9a1..5fd82cef9f 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -403,7 +403,7 @@ groups: see [`db.operation.parameter.`](../../docs/attributes-registry/db.md)). note: > For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. - If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. + If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. - ref: network.peer.address brief: Peer address of the database node where the operation was performed. requirement_level: From 6e8cce5cb04d2f92b6de0cfcabe4774e72c3e958 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 22 Jan 2025 18:06:25 -0800 Subject: [PATCH 31/39] Bump go.opentelemetry.io/build-tools/chloggen from 0.16.0 to 0.17.0 in /internal/tools (#1789) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Liudmila Molkova --- internal/tools/go.mod | 2 +- internal/tools/go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/internal/tools/go.mod b/internal/tools/go.mod index babd34a620..5682490353 100644 --- a/internal/tools/go.mod +++ b/internal/tools/go.mod @@ -6,7 +6,7 @@ toolchain go1.23.4 require ( github.com/client9/misspell v0.3.4 - go.opentelemetry.io/build-tools/chloggen v0.16.0 + go.opentelemetry.io/build-tools/chloggen v0.17.0 ) require ( diff --git a/internal/tools/go.sum b/internal/tools/go.sum index 3bd9909951..801a8a613c 100644 --- a/internal/tools/go.sum +++ b/internal/tools/go.sum @@ -14,8 +14,8 @@ github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= -go.opentelemetry.io/build-tools/chloggen v0.16.0 h1:iuotHxlcK46JJtQLdwQPsC5dcAygeOL116d2akCv8M8= -go.opentelemetry.io/build-tools/chloggen v0.16.0/go.mod h1:Wk92v9Wsv36sXYi7hOg3ndeeLKmKBu0/kgB7wcaeqJg= +go.opentelemetry.io/build-tools/chloggen v0.17.0 h1:aOtA6MW67VoB1HYxcqYIlVxfiBypI/ZTxSb7SU/Jw8g= +go.opentelemetry.io/build-tools/chloggen v0.17.0/go.mod h1:Wk92v9Wsv36sXYi7hOg3ndeeLKmKBu0/kgB7wcaeqJg= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= From a5c879e7e0bbe32489639d373324f7b608184be9 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 22 Jan 2025 18:07:51 -0800 Subject: [PATCH 32/39] Fix PR CI check: specify forked repo (#1787) --- .github/workflows/prepare-new-pr.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/prepare-new-pr.yml b/.github/workflows/prepare-new-pr.yml index a8a00fe5eb..eccca9f12d 100644 --- a/.github/workflows/prepare-new-pr.yml +++ b/.github/workflows/prepare-new-pr.yml @@ -20,6 +20,7 @@ jobs: with: ref: ${{ github.head_ref }} path: prchangelog + repository: ${{ github.event.pull_request.head.repo.full_name }} sparse-checkout: .chloggen # we're going to run prepare-new-pr script from the main branch From bfe6e1ecde78246e5e2e02b03d5b48d26f59bfd0 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 22 Jan 2025 18:11:09 -0800 Subject: [PATCH 33/39] Add stability to `network.interface.name` and event fields, add temp policy check (#1781) --- model/device/events.yaml | 8 +++++ model/gen-ai/events.yaml | 2 ++ model/network/registry.yaml | 1 + policies/registry.rego | 19 ++++++++++ policies_test/registry_test.rego | 45 +++++++++++++++++++++--- policies_test/yaml_schema_test.rego | 9 ++--- templates/registry/markdown/stability.j2 | 4 ++- 7 files changed, 78 insertions(+), 10 deletions(-) diff --git a/model/device/events.yaml b/model/device/events.yaml index fc4a613202..494381c415 100644 --- a/model/device/events.yaml +++ b/model/device/events.yaml @@ -37,24 +37,29 @@ groups: value: 'active' brief: > The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. + stability: development - id: inactive value: 'inactive' brief: > The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. + stability: development - id: background value: 'background' brief: > The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. + stability: development - id: foreground value: 'foreground' brief: > The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. + stability: development - id: terminate value: 'terminate' brief: > The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + stability: development - id: android.state stability: experimental requirement_level: @@ -72,13 +77,16 @@ groups: brief: > Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. + stability: development - id: background value: 'background' brief: > Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state. + stability: development - id: foreground value: 'foreground' brief: > Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. + stability: development diff --git a/model/gen-ai/events.yaml b/model/gen-ai/events.yaml index ac97d5402c..f615bb8d7f 100644 --- a/model/gen-ai/events.yaml +++ b/model/gen-ai/events.yaml @@ -111,6 +111,7 @@ groups: - id: function value: 'function' brief: Function + stability: development stability: experimental brief: > The type of the tool. @@ -275,6 +276,7 @@ groups: - id: function value: 'function' brief: Function + stability: development stability: experimental brief: > The type of the tool. diff --git a/model/network/registry.yaml b/model/network/registry.yaml index 2dc0ce39a1..542381dba5 100644 --- a/model/network/registry.yaml +++ b/model/network/registry.yaml @@ -236,6 +236,7 @@ groups: type: string brief: 'The network interface name.' examples: [ 'lo', 'eth0' ] + stability: development - id: network.connection.state type: members: diff --git a/policies/registry.rego b/policies/registry.rego index 3e145c1afa..837d34c4ce 100644 --- a/policies/registry.rego +++ b/policies/registry.rego @@ -70,6 +70,25 @@ deny contains attr_registry_violation(description, group.id, attr.id) if { description := sprintf("Attribute definition '%s' has requirement_level set to %s. Only attribute references can set requirement_level.", [attr.id, attr.requirement_level]) } +# We require attribute definitions to have stability +deny contains attr_registry_violation(description, group.id, attr.id) if { + group := input.groups[_] + attr := group.attributes[_] + not attr.stability + description := sprintf("Attribute definition '%s' does not contain stability field. All attribute definitions must include stability level.", [attr.id]) +} + +# We require span, metrics, events, resources definitions to have stability +deny contains attr_registry_violation(description, group.id, "") if { + semconv_types := {"span", "metric", "event", "resource"} + group := input.groups[_] + + semconv_types[group.type] != null + + not group.stability + description := sprintf("Semconv group '%s' does not contain stability field. All semconv definitions must include stability level.", [group.id]) +} + get_attribute_name(attr, group) := name if { full_name := concat(".", [group.prefix, attr.id]) diff --git a/policies_test/registry_test.rego b/policies_test/registry_test.rego index ce715cde3b..f0503ee837 100644 --- a/policies_test/registry_test.rego +++ b/policies_test/registry_test.rego @@ -11,20 +11,55 @@ test_registry_attribute_groups if { test_attribute_ids if { # This requires a prefix for use with opa, but weaver will fill in. - count(before_resolution.deny) > 0 with input as {"groups": [{"id": "not_registry", "prefix": "", "attributes": [{"id": "foo.bar"}]}]} + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "not_registry", "prefix": "", "attributes": [{"id": "foo.bar", "stability": "rc"}]}]} count(before_resolution.deny) == 0 with input as {"groups": [ - {"id": "registry.test", "prefix": "", "attributes": [{"id": "foo.bar"}]}, - {"id": "not_registry", "prefix": "", "attributes": [{"ref": "foo.bar"}]}, + {"id": "registry.test", "prefix": "", "attributes": [{"id": "foo.bar", "stability": "rc"}]}, + {"id": "not_registry", "prefix": "", "attributes": [{"ref": "foo.bar", "stability": "rc"}]}, ]} } +test_attribute_without_stability if { + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.text", "attributes": [{"id": "foo.bar"}]}]} + count(before_resolution.deny) == 0 with input as {"groups": [ + {"id": "registry.test", "attributes": [{"id": "foo.bar", "stability": "alpha"}]}, + ]} +} + +test_span_without_stability if { + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "span.group", "type": "span"}]} + count(before_resolution.deny) == 0 with input as {"groups": [ + {"id": "span.group", "type": "span", "stability": "alpha"}] + } +} + +test_event_without_stability if { + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "event.foo", "type": "event", "name": "foo"}]} + count(before_resolution.deny) == 0 with input as {"groups": [ + {"id": "event.foo", "name": "foo", "type": "event", "stability": "alpha"}] + } +} + +test_metric_without_stability if { + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "metric.foo", "type": "metric", "name": "foo"}]} + count(before_resolution.deny) == 0 with input as {"groups": [ + {"id": "metric.foo", "name": "foo", "type": "metric", "stability": "development"}] + } +} + +test_resource_without_stability if { + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "resource.foo", "type": "resource", "name": "foo"}]} + count(before_resolution.deny) == 0 with input as {"groups": [ + {"id": "resource.foo", "name": "foo", "type": "resource", "stability": "stable"}] + } +} + test_attribute_refs if { count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"ref": "foo"}]}]} count(before_resolution.deny) == 0 with input as {"groups": [{"id": "not_registry", "attributes": [{"ref": "foo"}]}]} } test_attribute_requirement_levels if { - count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"id": "foo", "requirement_level": "required"}]}]} - count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"id": "foo", "requirement_level": {"recommended": "if available"}}]}]} + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"id": "foo", "requirement_level": "required", "stability": "rc"}]}]} + count(before_resolution.deny) > 0 with input as {"groups": [{"id": "registry.foo", "attributes": [{"id": "foo", "requirement_level": {"recommended": "if available"}, "stability": "rc"}]}]} count(before_resolution.deny) == 0 with input as {"groups": [{"id": "not_registry", "attributes": [{"ref": "foo", "requirement_level": "required"}]}]} } diff --git a/policies_test/yaml_schema_test.rego b/policies_test/yaml_schema_test.rego index 81dd0f2d55..b587855f36 100644 --- a/policies_test/yaml_schema_test.rego +++ b/policies_test/yaml_schema_test.rego @@ -52,6 +52,7 @@ test_fails_on_referenced_event_name_on_event if { event := [{ "id": "event.foo", "type": "event", "name": "foo", + "stability": "rc", "attributes": [{"ref": "event.name"}]}] count(deny) == 1 with input as {"groups": event} } @@ -101,22 +102,22 @@ test_fails_on_invalid_resource_id if { } create_attribute_group(attr) = json if { - json := [{"id": "yaml_schema.test", "attributes": [{"id": attr}]}] + json := [{"id": "yaml_schema.test", "attributes": [{"id": attr, "stability": "rc"}]}] } create_metric(name) = json if { id := sprintf("metric.%s", [name]) - json := [{"id": id, "type": "metric", "metric_name": name}] + json := [{"id": id, "type": "metric", "metric_name": name, "stability": "rc"}] } create_event(name) = json if { id := sprintf("event.%s", [name]) - json := [{"id": id, "type": "event", "name": name}] + json := [{"id": id, "type": "event", "name": name, "stability": "rc"}] } create_resource(name) = json if { id := sprintf("resource.%s", [name]) - json := [{"id": id, "type": "resource", "name": name}] + json := [{"id": id, "type": "resource", "name": name, "stability": "rc"}] } invalid_names := [ diff --git a/templates/registry/markdown/stability.j2 b/templates/registry/markdown/stability.j2 index 747b5a4446..c7169eae5f 100644 --- a/templates/registry/markdown/stability.j2 +++ b/templates/registry/markdown/stability.j2 @@ -4,6 +4,8 @@ {%- elif stability == "stable" %}![Stable](https://img.shields.io/badge/-stable-lightgreen) {%- elif stability == "release_candidate" %}![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) {%- elif stability == "deprecated" %}![Deprecated](https://img.shields.io/badge/-deprecated-red) -{%- else %}![Experimental](https://img.shields.io/badge/-experimental-blue) +{%- elif stability == "experimental" %}![Experimental](https://img.shields.io/badge/-experimental-blue) +{%- elif stability == "development" %}![Experimental](https://img.shields.io/badge/-experimental-blue) +{%- else %}{{ "Unknown stability." }} {%- endif %} {%- endmacro %} From e95f8fd116ef7d1ef32f87ac77efd33aea339fd3 Mon Sep 17 00:00:00 2001 From: Christos Markou Date: Thu, 23 Jan 2025 12:20:29 +0200 Subject: [PATCH 34/39] Add note about logical and physical cpu numbers calculation (#1780) Signed-off-by: ChrsMark Co-authored-by: Liudmila Molkova --- .chloggen/improve_cpu_brief.yaml | 22 ++++++++++++++++++++++ docs/system/system-metrics.md | 8 ++++++-- model/system/metrics.yaml | 2 ++ 3 files changed, 30 insertions(+), 2 deletions(-) create mode 100755 .chloggen/improve_cpu_brief.yaml diff --git a/.chloggen/improve_cpu_brief.yaml b/.chloggen/improve_cpu_brief.yaml new file mode 100755 index 0000000000..4642419f39 --- /dev/null +++ b/.chloggen/improve_cpu_brief.yaml @@ -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: system + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Adds note about how `system.cpu.physical.count` and `system.cpu.logical.count` are calculated + +# 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: [1780] + +# (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: diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 6194ae0e72..2f0983e24c 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -201,7 +201,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `system.cpu.physical.count` | UpDownCounter | `{cpu}` | Reports the number of actual physical processor cores on the hardware | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system.cpu.physical.count` | UpDownCounter | `{cpu}` | Reports the number of actual physical processor cores on the hardware [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Calculated by multiplying the number of sockets by the number of cores per socket @@ -221,7 +223,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `system.cpu.logical.count` | UpDownCounter | `{cpu}` | Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `system.cpu.logical.count` | UpDownCounter | `{cpu}` | Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Calculated by multiplying the number of sockets by the number of cores per socket, and then by the number of threads per core diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index 0e202d86b4..be1d6b6c0a 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -53,6 +53,7 @@ groups: metric_name: system.cpu.physical.count stability: experimental brief: "Reports the number of actual physical processor cores on the hardware" + note: "Calculated by multiplying the number of sockets by the number of cores per socket" instrument: updowncounter unit: "{cpu}" attributes: [] @@ -62,6 +63,7 @@ groups: metric_name: system.cpu.logical.count stability: experimental brief: "Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking" + note: "Calculated by multiplying the number of sockets by the number of cores per socket, and then by the number of threads per core" instrument: updowncounter unit: "{cpu}" attributes: [] From b0f39690ab1faf3c5022eb5f83d3546bba8456bb Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 23 Jan 2025 11:25:12 +0100 Subject: [PATCH 35/39] model/profile: add frame.type for Erlang (#1735) Signed-off-by: Florian Lehner Co-authored-by: Liudmila Molkova Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/profile-frame-type-beam.yaml | 22 ++++++++++++++++++++++ docs/attributes-registry/profile.md | 1 + docs/general/profiles.md | 1 + model/profile/registry.yaml | 5 +++++ 4 files changed, 29 insertions(+) create mode 100755 .chloggen/profile-frame-type-beam.yaml diff --git a/.chloggen/profile-frame-type-beam.yaml b/.chloggen/profile-frame-type-beam.yaml new file mode 100755 index 0000000000..ea16a6532b --- /dev/null +++ b/.chloggen/profile-frame-type-beam.yaml @@ -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: profile + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: 'Extend the list of known frame types with a value for Erlang' + +# 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: [1735] + +# (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: diff --git a/docs/attributes-registry/profile.md b/docs/attributes-registry/profile.md index 266d316f4b..67d48530c3 100644 --- a/docs/attributes-registry/profile.md +++ b/docs/attributes-registry/profile.md @@ -20,6 +20,7 @@ Describes the origin of a single frame in a Profile. | Value | Description | Stability | |---|---|---| +| `beam` | [Erlang](https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cpython` | [Python](https://wikipedia.org/wiki/Python_(programming_language)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `dotnet` | [.NET](https://wikipedia.org/wiki/.NET) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `jvm` | [JVM](https://wikipedia.org/wiki/Java_virtual_machine) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/general/profiles.md b/docs/general/profiles.md index ed7d59c9df..91a21eb3b1 100644 --- a/docs/general/profiles.md +++ b/docs/general/profiles.md @@ -36,6 +36,7 @@ They may be used in any Profiles record they apply to. | Value | Description | Stability | |---|---|---| +| `beam` | [Erlang](https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cpython` | [Python](https://wikipedia.org/wiki/Python_(programming_language)) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `dotnet` | [.NET](https://wikipedia.org/wiki/.NET) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `jvm` | [JVM](https://wikipedia.org/wiki/Java_virtual_machine) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/profile/registry.yaml b/model/profile/registry.yaml index d5d6649d0a..c3249368ea 100644 --- a/model/profile/registry.yaml +++ b/model/profile/registry.yaml @@ -61,3 +61,8 @@ groups: [V8JS](https://wikipedia.org/wiki/V8_(JavaScript_engine)) value: "v8js" stability: experimental + - id: beam + brief: > + [Erlang](https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine)) + value: "beam" + stability: experimental From 98244d9c1a1613ab43787dbcc76265ee2c5b4410 Mon Sep 17 00:00:00 2001 From: Christophe Kamphaus <44020965+christophe-kamphaus-jemmic@users.noreply.github.com> Date: Thu, 23 Jan 2025 11:29:42 +0100 Subject: [PATCH 36/39] Add CICD metrics (#1681) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Co-authored-by: Liudmila Molkova --- .chloggen/1600-cicd-metrics.yaml | 27 +++ .vscode/settings.json | 3 +- docs/attributes-registry/cicd.md | 39 +++++ docs/cicd/cicd-metrics.md | 275 +++++++++++++++++++++++++++++++ model/cicd/metrics.yaml | 69 ++++++++ model/cicd/registry.yaml | 86 ++++++++++ 6 files changed, 498 insertions(+), 1 deletion(-) create mode 100644 .chloggen/1600-cicd-metrics.yaml create mode 100644 model/cicd/metrics.yaml diff --git a/.chloggen/1600-cicd-metrics.yaml b/.chloggen/1600-cicd-metrics.yaml new file mode 100644 index 0000000000..fe134b1f5b --- /dev/null +++ b/.chloggen/1600-cicd-metrics.yaml @@ -0,0 +1,27 @@ +# 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: cicd + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add CICD metrics + +# 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: [1600] + +# (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: | + Makes the following changes: + + - Add metrics `cicd.pipeline.run.duration`, `cicd.pipeline.run.active`, `cicd.worker.count`, + `cicd.pipeline.run.errors` and `cicd.system.errors`. + - The CICD attributes `cicd.pipeline.run.state`, `cicd.pipeline.result`, `cicd.system.component`, `cicd.worker.state` have been added to the registry. diff --git a/.vscode/settings.json b/.vscode/settings.json index 069acb27c7..f1709edc98 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -14,5 +14,6 @@ "model/**/*.yaml" ] }, - "json.schemaDownload.enable": true + "json.schemaDownload.enable": true, + "markdown.extension.toc.levels": "2..6" } diff --git a/docs/attributes-registry/cicd.md b/docs/attributes-registry/cicd.md index 8b585d8fe4..4597df0283 100644 --- a/docs/attributes-registry/cicd.md +++ b/docs/attributes-registry/cicd.md @@ -13,11 +13,38 @@ This group describes attributes specific to pipelines within a Continuous Integr | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `cicd.pipeline.name` | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.result` | string | The result of a pipeline run. | `success`; `failure`; `timeout`; `skipped` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.run.id` | string | The unique identifier of a pipeline run within a CI/CD system. | `120912` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.run.state` | string | The pipeline run goes through these states during its lifecycle. | `pending`; `executing`; `finalizing` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.task.name` | string | The human readable name of a task within a pipeline. Task here most closely aligns with a [computing process](https://wikipedia.org/wiki/Pipeline_(computing)) in a pipeline. Other terms for tasks include commands, steps, and procedures. | `Run GoLang Linter`; `Go Build`; `go-test`; `deploy_binary` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.task.run.id` | string | The unique identifier of a task run within a pipeline. | `12097` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.task.run.url.full` | string | The [URL](https://wikipedia.org/wiki/URL) of the pipeline run providing the complete address in order to locate and identify the pipeline run. | `https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.task.type` | string | The type of the task within a pipeline. | `build`; `test`; `deploy` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.system.component` | string | The name of a component of the CICD system. | `controller`; `scheduler`; `agent` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.worker.state` | string | The state of a CICD worker / agent. | `idle`; `busy`; `down` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`cicd.pipeline.result` 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 | +|---|---|---| +| `cancellation` | The pipeline run was cancelled, eg. by a user manually cancelling the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `error` | The pipeline run failed due to an error in the CICD system, eg. due to the worker being killed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failure` | The pipeline run did not finish successfully, eg. due to a compile error or a failing test. Such failures are usually detected by non-zero exit codes of the tools executed in the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `skip` | The pipeline run was skipped, eg. due to a precondition not being met. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `success` | The pipeline run finished successfully. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timeout` | A timeout caused the pipeline run to be interrupted. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`cicd.pipeline.run.state` 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 | +|---|---|---| +| `executing` | The executing state spans the execution of any run tasks (eg. build, test). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `finalizing` | The finalizing state spans from when the run has finished executing (eg. cleanup of run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pending` | The run pending state spans from the event triggering the pipeline run until the execution of the run starts (eg. time spent in a queue, provisioning agents, creating run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | --- @@ -28,3 +55,15 @@ This group describes attributes specific to pipelines within a Continuous Integr | `build` | build | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `deploy` | deploy | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `test` | test | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`cicd.worker.state` 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 | +|---|---|---| +| `available` | The worker is not performing work for the CICD system. It is available to the CICD system to perform work on (online / idle). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `busy` | The worker is performing work for the CICD system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `offline` | The worker is not available to the CICD system (disconnected / down). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Pipelines might have conditions on which workers they are able to run so not every worker might be available to every pipeline. diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md index 687eb76e43..46bbd563c3 100644 --- a/docs/cicd/cicd-metrics.md +++ b/docs/cicd/cicd-metrics.md @@ -10,6 +10,12 @@ linkTitle: CICD metrics +- [CICD Metrics](#cicd-metrics) + - [Metric: `cicd.pipeline.run.duration`](#metric-cicdpipelinerunduration) + - [Metric: `cicd.pipeline.run.active`](#metric-cicdpipelinerunactive) + - [Metric: `cicd.worker.count`](#metric-cicdworkercount) + - [Metric: `cicd.pipeline.run.errors`](#metric-cicdpipelinerunerrors) + - [Metric: `cicd.system.errors`](#metric-cicdsystemerrors) - [VCS Metrics](#vcs-metrics) - [Metric: `vcs.change.count`](#metric-vcschangecount) - [Metric: `vcs.change.duration`](#metric-vcschangeduration) @@ -23,6 +29,275 @@ linkTitle: CICD metrics +## CICD Metrics + +The conventions described in this section are specific to Continuous Integration / Continuous Deployment (CICD) systems. + +**Disclaimer:** These are initial CICD metrics and attributes +but more may be added in the future. + +### Metric: `cicd.pipeline.run.duration` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `cicd.pipeline.run.duration` | Histogram | `s` | Duration of a pipeline run grouped by pipeline, state and result. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cicd.pipeline.name`](/docs/attributes-registry/cicd.md) | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cicd.pipeline.run.state`](/docs/attributes-registry/cicd.md) | string | The pipeline run goes through these states during its lifecycle. | `pending`; `executing`; `finalizing` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cicd.pipeline.result`](/docs/attributes-registry/cicd.md) | string | The result of a pipeline run. | `success`; `failure`; `timeout`; `skipped` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the pipeline run failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1] `cicd.pipeline.result`:** If and only if the pipeline run result has been set during that state. + +**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +--- + +`cicd.pipeline.result` 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 | +|---|---|---| +| `cancellation` | The pipeline run was cancelled, eg. by a user manually cancelling the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `error` | The pipeline run failed due to an error in the CICD system, eg. due to the worker being killed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failure` | The pipeline run did not finish successfully, eg. due to a compile error or a failing test. Such failures are usually detected by non-zero exit codes of the tools executed in the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `skip` | The pipeline run was skipped, eg. due to a precondition not being met. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `success` | The pipeline run finished successfully. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timeout` | A timeout caused the pipeline run to be interrupted. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`cicd.pipeline.run.state` 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 | +|---|---|---| +| `executing` | The executing state spans the execution of any run tasks (eg. build, test). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `finalizing` | The finalizing state spans from when the run has finished executing (eg. cleanup of run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pending` | The run pending state spans from the event triggering the pipeline run until the execution of the run starts (eg. time spent in a queue, provisioning agents, creating run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`error.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 | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + +### Metric: `cicd.pipeline.run.active` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `cicd.pipeline.run.active` | UpDownCounter | `{run}` | The number of pipeline runs currently active in the system by state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cicd.pipeline.name`](/docs/attributes-registry/cicd.md) | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`cicd.pipeline.run.state`](/docs/attributes-registry/cicd.md) | string | The pipeline run goes through these states during its lifecycle. | `pending`; `executing`; `finalizing` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`cicd.pipeline.run.state` 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 | +|---|---|---| +| `executing` | The executing state spans the execution of any run tasks (eg. build, test). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `finalizing` | The finalizing state spans from when the run has finished executing (eg. cleanup of run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pending` | The run pending state spans from the event triggering the pipeline run until the execution of the run starts (eg. time spent in a queue, provisioning agents, creating run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `cicd.worker.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `cicd.worker.count` | UpDownCounter | `{count}` | The number of workers on the CICD system by state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cicd.worker.state`](/docs/attributes-registry/cicd.md) | string | The state of a CICD worker / agent. | `idle`; `busy`; `down` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`cicd.worker.state` 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 | +|---|---|---| +| `available` | The worker is not performing work for the CICD system. It is available to the CICD system to perform work on (online / idle). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `busy` | The worker is performing work for the CICD system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `offline` | The worker is not available to the CICD system (disconnected / down). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Pipelines might have conditions on which workers they are able to run so not every worker might be available to every pipeline. + + + + + + +### Metric: `cicd.pipeline.run.errors` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `cicd.pipeline.run.errors` | Counter | `{error}` | The number of errors encountered in pipeline runs (eg. compile, test failures). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** There might be errors in a pipeline run that are non fatal (eg. they are suppressed) or in a parallel stage multiple stages could have a fatal error. +This means that this error count might not be the same as the count of metric `cicd.pipeline.run.duration` with run result `failure`. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cicd.pipeline.name`](/docs/attributes-registry/cicd.md) | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +--- + +`error.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 | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + +### Metric: `cicd.system.errors` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `cicd.system.errors` | Counter | `{error}` | The number of errors in a component of the CICD system (eg. controller, scheduler, agent). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Errors in pipeline run execution are explicitly excluded. Ie a test failure is not counted in this metric. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`cicd.system.component`](/docs/attributes-registry/cicd.md) | string | The name of a component of the CICD system. | `controller`; `scheduler`; `agent` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +--- + +`error.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 | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + ## VCS Metrics The conventions described in this section are specific to Version Control Systems. diff --git a/model/cicd/metrics.yaml b/model/cicd/metrics.yaml new file mode 100644 index 0000000000..7e4b5d54d6 --- /dev/null +++ b/model/cicd/metrics.yaml @@ -0,0 +1,69 @@ +groups: + - id: metric.cicd.pipeline.run.duration + type: metric + metric_name: cicd.pipeline.run.duration + brief: 'Duration of a pipeline run grouped by pipeline, state and result.' + instrument: histogram + unit: "s" + stability: experimental + attributes: + - ref: cicd.pipeline.name + requirement_level: required + - ref: cicd.pipeline.run.state + requirement_level: required + - ref: cicd.pipeline.result + requirement_level: + conditionally_required: If and only if the pipeline run result has been set during that state. + - ref: error.type + requirement_level: + conditionally_required: If and only if the pipeline run failed. + - id: metric.cicd.pipeline.run.active + type: metric + metric_name: cicd.pipeline.run.active + brief: 'The number of pipeline runs currently active in the system by state.' + instrument: updowncounter + unit: "{run}" + stability: experimental + attributes: + - ref: cicd.pipeline.name + requirement_level: required + - ref: cicd.pipeline.run.state + requirement_level: required + - id: metric.cicd.worker.count + type: metric + metric_name: cicd.worker.count + brief: 'The number of workers on the CICD system by state.' + instrument: updowncounter + unit: "{count}" + stability: experimental + attributes: + - ref: cicd.worker.state + requirement_level: required + - id: metric.cicd.pipeline.run.errors + type: metric + metric_name: cicd.pipeline.run.errors + brief: 'The number of errors encountered in pipeline runs (eg. compile, test failures).' + note: | + There might be errors in a pipeline run that are non fatal (eg. they are suppressed) or in a parallel stage multiple stages could have a fatal error. + This means that this error count might not be the same as the count of metric `cicd.pipeline.run.duration` with run result `failure`. + instrument: counter + unit: "{error}" + stability: experimental + attributes: + - ref: cicd.pipeline.name + requirement_level: required + - ref: error.type + requirement_level: required + - id: metric.cicd.system.errors + type: metric + metric_name: cicd.system.errors + brief: 'The number of errors in a component of the CICD system (eg. controller, scheduler, agent).' + note: 'Errors in pipeline run execution are explicitly excluded. Ie a test failure is not counted in this metric.' + instrument: counter + unit: "{error}" + stability: experimental + attributes: + - ref: cicd.system.component + requirement_level: required + - ref: error.type + requirement_level: required diff --git a/model/cicd/registry.yaml b/model/cicd/registry.yaml index a63903d2c6..4188bd1c58 100644 --- a/model/cicd/registry.yaml +++ b/model/cicd/registry.yaml @@ -31,6 +31,26 @@ groups: brief: > The unique identifier of a pipeline run within a CI/CD system. examples: ["120912"] + - id: cicd.pipeline.run.state + type: + members: + - id: pending + value: pending + brief: > + The run pending state spans from the event triggering the pipeline run until the execution of the run starts (eg. time spent in a queue, provisioning agents, creating run resources). + stability: experimental + - id: executing + value: executing + brief: The executing state spans the execution of any run tasks (eg. build, test). + stability: experimental + - id: finalizing + value: finalizing + brief: The finalizing state spans from when the run has finished executing (eg. cleanup of run resources). + stability: experimental + stability: experimental + brief: > + The pipeline run goes through these states during its lifecycle. + examples: ["pending", "executing", "finalizing"] - id: cicd.pipeline.task.name type: string stability: experimental @@ -75,3 +95,69 @@ groups: brief: > The type of the task within a pipeline. examples: ["build", "test", "deploy"] + - id: cicd.pipeline.result + type: + members: + - id: success + value: success + brief: "The pipeline run finished successfully." + stability: experimental + - id: failure + value: failure + brief: >- + The pipeline run did not finish successfully, eg. due to a compile error or a failing test. + Such failures are usually detected by non-zero exit codes of the tools executed in the pipeline run. + stability: experimental + - id: error + value: error + brief: >- + The pipeline run failed due to an error in the CICD system, eg. due to the worker being killed. + stability: experimental + - id: timeout + value: timeout + brief: "A timeout caused the pipeline run to be interrupted." + stability: experimental + - id: cancellation + value: cancellation + brief: "The pipeline run was cancelled, eg. by a user manually cancelling the pipeline run." + stability: experimental + - id: skip + value: skip + brief: "The pipeline run was skipped, eg. due to a precondition not being met." + stability: experimental + stability: experimental + brief: > + The result of a pipeline run. + examples: ["success", "failure", "timeout", "skipped"] + - id: cicd.worker.state + type: + members: + - id: available + value: available + brief: >- + The worker is not performing work for the CICD system. + It is available to the CICD system to perform work on (online / idle). + note: "Pipelines might have conditions on which workers they are able to run so not every worker might be available to every pipeline." + stability: experimental + - id: busy + value: busy + brief: "The worker is performing work for the CICD system." + stability: experimental + - id: offline + value: offline + brief: "The worker is not available to the CICD system (disconnected / down)." + stability: experimental + stability: experimental + brief: > + The state of a CICD worker / agent. + examples: ["idle", "busy", "down"] + - id: cicd.system.component + type: string + stability: experimental + brief: The name of a component of the CICD system. + examples: + [ + "controller", + "scheduler", + "agent", + ] From 35695e1ac5151f1b07a9e17136c157978538b891 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 23 Jan 2025 08:45:17 -0800 Subject: [PATCH 37/39] Fix TOC (#1801) --- docs/exceptions/exceptions-spans.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index 96ca6f49cd..e4134324b5 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -11,6 +11,11 @@ exceptions associated with spans. +- [Exception event](#exception-event) + - [Stacktrace Representation](#stacktrace-representation) + + + ## Exception event From 43654752b19b4207834b68e310e325111d0955ee Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 23 Jan 2025 15:02:50 -0500 Subject: [PATCH 38/39] [editorial] Fix alias in general/trace.md (#1805) --- docs/general/trace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/trace.md b/docs/general/trace.md index a83586d535..210882a12d 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -1,6 +1,6 @@ # Trace Semantic Conventions From 7bde041ce55bc61bf0ae2eb4220b5ac67b979885 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Thu, 23 Jan 2025 15:05:46 -0500 Subject: [PATCH 39/39] [vcs] add `vcs.change.time_to_merge` metric (#1685) Co-authored-by: Liudmila Molkova Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/vcs-ttm.yaml | 22 ++++ docs/attributes-registry/vcs.md | 64 ++++++---- docs/cicd/cicd-metrics.md | 215 ++++++++++++++++++++++++++------ model/vcs/metrics.yaml | 52 ++++++-- model/vcs/registry.yaml | 100 +++++++++------ 5 files changed, 342 insertions(+), 111 deletions(-) create mode 100755 .chloggen/vcs-ttm.yaml diff --git a/.chloggen/vcs-ttm.yaml b/.chloggen/vcs-ttm.yaml new file mode 100755 index 0000000000..25f2671a70 --- /dev/null +++ b/.chloggen/vcs-ttm.yaml @@ -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: vcs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add `vcs.change.time_to_merge` metric. + +# 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: [1685] + +# (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: diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md index b17426a93c..2e47a9f003 100644 --- a/docs/attributes-registry/vcs.md +++ b/docs/attributes-registry/vcs.md @@ -19,42 +19,62 @@ This group defines the attributes for [Version Control Systems (VCS)](https://wi | `vcs.change.state` | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vcs.change.title` | string | The human readable title of the change (pull request/merge request/changelist). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vcs.line_change.type` | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.ref.base.name` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.ref.base.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [1] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.ref.base.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.ref.head.name` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.ref.head.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.ref.head.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.base.name` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.base.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.base.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [3] | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.head.name` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [4] | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.head.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [5] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.head.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [6] | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vcs.ref.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.repository.name` | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [3] | `semantic-conventions`; `my-cool-repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.repository.url.full` | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [4] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.name` | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [7] | `semantic-conventions`; `my-cool-repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.url.full` | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [8] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vcs.revision_delta.direction` | string | The type of revision comparison. | `ahead`; `behind` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `vcs.ref.base.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +**[1] `vcs.ref.base.name`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. + +**[2] `vcs.ref.base.revision`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. The +revision can be a full [hash value (see +glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the recorded change to a ref within a repository pointing to a commit [commit](https://git-scm.com/docs/git-commit) object. It does -not necessarily have to be a hash; it can simply define a -[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +not necessarily have to be a hash; it can simply define a [revision +number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where -it is identical to the `ref.base.name`, it SHOULD still be included. It is -up to the implementer to decide which value to set as the revision -based on the VCS system and situational context. +it is identical to the `ref.base.name`, it SHOULD still be included. +It is up to the implementer to decide which value to set as the +revision based on the VCS system and situational context. + +**[3] `vcs.ref.base.type`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. -**[2] `vcs.ref.head.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +**[4] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a +given time. + +**[5] `vcs.ref.head.revision`:** `head` refers to where you are right now; the current reference at a +given time.The revision can be a full [hash value (see +glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the recorded change to a ref within a repository pointing to a commit [commit](https://git-scm.com/docs/git-commit) object. It does -not necessarily have to be a hash; it can simply define a -[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +not necessarily have to be a hash; it can simply define a [revision +number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where -it is identical to the `ref.head.name`, it SHOULD still be included. It is -up to the implementer to decide which value to set as the revision -based on the VCS system and situational context. +it is identical to the `ref.head.name`, it SHOULD still be included. +It is up to the implementer to decide which value to set as the +revision based on the VCS system and situational context. + +**[6] `vcs.ref.head.type`:** `head` refers to where you are right now; the current reference at a +given time. -**[3] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +**[7] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends. -**[4] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include +**[8] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include the `.git` extension. --- diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md index 46bbd563c3..81db6b6675 100644 --- a/docs/cicd/cicd-metrics.md +++ b/docs/cicd/cicd-metrics.md @@ -20,6 +20,7 @@ linkTitle: CICD metrics - [Metric: `vcs.change.count`](#metric-vcschangecount) - [Metric: `vcs.change.duration`](#metric-vcschangeduration) - [Metric: `vcs.change.time_to_approval`](#metric-vcschangetime_to_approval) + - [Metric: `vcs.change.time_to_merge`](#metric-vcschangetime_to_merge) - [Metric: `vcs.repository.count`](#metric-vcsrepositorycount) - [Metric: `vcs.ref.count`](#metric-vcsrefcount) - [Metric: `vcs.ref.lines_delta`](#metric-vcsreflines_delta) @@ -367,14 +368,17 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [2] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [3] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include +**[1] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a +given time. + +**[2] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include the `.git` extension. -**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +**[3] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends. @@ -407,21 +411,126 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `vcs.change.time_to_approval` | Gauge | `s` | The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.change.time_to_approval` | Gauge | `s` | The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [2] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [4] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.revision`](/docs/attributes-registry/vcs.md) | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [5] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.revision`](/docs/attributes-registry/vcs.md) | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [6] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include +**[1] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a +given time. + +**[2] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include the `.git` extension. -**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +**[3] `vcs.ref.base.name`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. + +**[4] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +repository if collecting telemetry across multiple orgs or groups in +the same backends. + +**[5] `vcs.ref.base.revision`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. The +revision can be a full [hash value (see +glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a [revision +number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +it is identical to the `ref.base.name`, it SHOULD still be included. +It is up to the implementer to decide which value to set as the +revision based on the VCS system and situational context. + +**[6] `vcs.ref.head.revision`:** `head` refers to where you are right now; the current reference at a +given time.The revision can be a full [hash value (see +glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a [revision +number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +it is identical to the `ref.head.name`, it SHOULD still be included. +It is up to the implementer to decide which value to set as the +revision based on the VCS system and situational context. + + + + + + +### Metric: `vcs.change.time_to_merge` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.change.time_to_merge` | Gauge | `s` | The amount of time since its creation it took a change (pull request/merge request/changelist) to get merged into the target(base) ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [2] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [4] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.revision`](/docs/attributes-registry/vcs.md) | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [5] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.revision`](/docs/attributes-registry/vcs.md) | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [6] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a +given time. + +**[2] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include +the `.git` extension. + +**[3] `vcs.ref.base.name`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. + +**[4] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends. +**[5] `vcs.ref.base.revision`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. The +revision can be a full [hash value (see +glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a [revision +number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +it is identical to the `ref.base.name`, it SHOULD still be included. +It is up to the implementer to decide which value to set as the +revision based on the VCS system and situational context. + +**[6] `vcs.ref.head.revision`:** `head` refers to where you are right now; the current reference at a +given time.The revision can be a full [hash value (see +glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a [revision +number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +it is identical to the `ref.head.name`, it SHOULD still be included. +It is up to the implementer to decide which value to set as the +revision based on the VCS system and situational context. + @@ -440,7 +549,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `vcs.repository.count` | UpDownCounter | `{repository}` | The number of repositories in an organization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.count` | UpDownCounter | `{repository}` | The number of repositories in an organization. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -460,7 +569,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `vcs.ref.count` | UpDownCounter | `{ref}` | The number of refs of type branch or tag in a repository | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.count` | UpDownCounter | `{ref}` | The number of refs of type branch or tag in a repository. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -502,7 +611,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `vcs.ref.lines_delta` | Gauge | `{line}` | The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.lines_delta` | Gauge | `{line}` | The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). @@ -511,18 +620,32 @@ If number of lines added/removed should be calculated from the start of time, th | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`vcs.line_change.type`](/docs/attributes-registry/vcs.md) | string | The type of line change being measured on a branch or change. | `added`; `removed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [2] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [4] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [5] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [6] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include +**[1] `vcs.ref.base.name`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. + +**[2] `vcs.ref.base.type`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. + +**[3] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a +given time. + +**[4] `vcs.ref.head.type`:** `head` refers to where you are right now; the current reference at a +given time. + +**[5] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include the `.git` extension. -**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +**[6] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends. @@ -578,19 +701,33 @@ instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [2] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [4] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [5] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.revision_delta.direction`](/docs/attributes-registry/vcs.md) | string | The type of revision comparison. | `ahead`; `behind` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.change.id`](/docs/attributes-registry/vcs.md) | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | `Conditionally Required` if a change is associate with the ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [6] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include +**[1] `vcs.ref.base.name`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. + +**[2] `vcs.ref.base.type`:** `base` refers to the starting point of a change. For example, `main` +would be the base reference of type branch if you've created a new +reference of type branch from it and created new commits. + +**[3] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a +given time. + +**[4] `vcs.ref.head.type`:** `head` refers to where you are right now; the current reference at a +given time. + +**[5] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include the `.git` extension. -**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +**[6] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends. @@ -643,15 +780,21 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [2] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [3] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [4] | `semantic-conventions`; `my-cool-repo` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include +**[1] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a +given time. + +**[2] `vcs.ref.head.type`:** `head` refers to where you are right now; the current reference at a +given time. + +**[3] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include the `.git` extension. -**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +**[4] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends. diff --git a/model/vcs/metrics.yaml b/model/vcs/metrics.yaml index 9bb3118942..bec7f48fde 100644 --- a/model/vcs/metrics.yaml +++ b/model/vcs/metrics.yaml @@ -5,7 +5,7 @@ groups: brief: 'The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged)' instrument: updowncounter unit: "{change}" - stability: experimental + stability: development attributes: - ref: vcs.change.state requirement_level: required @@ -19,7 +19,7 @@ groups: brief: 'The time duration a change (pull request/merge request/changelist) has been in a given state.' instrument: gauge unit: "s" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -32,10 +32,10 @@ groups: - id: metric.vcs.change.time_to_approval type: metric metric_name: vcs.change.time_to_approval - brief: 'The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval' + brief: 'The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval.' instrument: gauge unit: "s" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -43,21 +43,47 @@ groups: requirement_level: recommended - ref: vcs.ref.head.name requirement_level: required + - ref: vcs.ref.head.revision + requirement_level: opt_in + - ref: vcs.ref.base.name + requirement_level: recommended + - ref: vcs.ref.base.revision + requirement_level: opt_in + - id: metric.vcs.change.time_to_merge + type: metric + metric_name: vcs.change.time_to_merge + brief: 'The amount of time since its creation it took a change (pull request/merge request/changelist) to get merged into the target(base) ref.' + instrument: gauge + unit: "s" + stability: development + attributes: + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.repository.name + requirement_level: recommended + - ref: vcs.ref.head.name + requirement_level: required + - ref: vcs.ref.head.revision + requirement_level: opt_in + - ref: vcs.ref.base.name + requirement_level: recommended + - ref: vcs.ref.base.revision + requirement_level: opt_in - id: metric.vcs.repository.count type: metric metric_name: vcs.repository.count - brief: 'The number of repositories in an organization' + brief: 'The number of repositories in an organization.' instrument: updowncounter unit: "{repository}" - stability: experimental + stability: development attributes: [] - id: metric.vcs.ref.count type: metric metric_name: vcs.ref.count - brief: 'The number of refs of type branch or tag in a repository' + brief: 'The number of refs of type branch or tag in a repository.' instrument: updowncounter unit: "{ref}" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -68,14 +94,14 @@ groups: - id: metric.vcs.ref.lines_delta type: metric metric_name: vcs.ref.lines_delta - brief: 'The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute' + brief: 'The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute.' note: | This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). If number of lines added/removed should be calculated from the start of time, then `vcs.ref.base.name` SHOULD be set to an empty string. instrument: gauge unit: "{line}" - stability: experimental + stability: development attributes: - ref: vcs.change.id requirement_level: @@ -103,7 +129,7 @@ groups: instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`. instrument: gauge unit: "{revision}" - stability: experimental + stability: development attributes: - ref: vcs.change.id requirement_level: @@ -128,7 +154,7 @@ groups: brief: 'Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch`' instrument: gauge unit: "s" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -144,7 +170,7 @@ groups: brief: 'The number of unique contributors to a repository' instrument: gauge unit: "{contributor}" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required diff --git a/model/vcs/registry.yaml b/model/vcs/registry.yaml index d9e96deb9e..476b2746f9 100644 --- a/model/vcs/registry.yaml +++ b/model/vcs/registry.yaml @@ -8,7 +8,7 @@ groups: attributes: - id: vcs.repository.url.full type: string - stability: experimental + stability: development brief: > The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to @@ -23,7 +23,7 @@ groups: ] - id: vcs.repository.name type: string - stability: experimental + stability: development brief: > The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization @@ -39,11 +39,15 @@ groups: ] - id: vcs.ref.base.name type: string - stability: experimental + stability: development brief: > The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. + note: | + `base` refers to the starting point of a change. For example, `main` + would be the base reference of type branch if you've created a new + reference of type branch from it and created new commits. examples: ["my-feature-branch", "tag-1-test"] - id: vcs.ref.base.type type: @@ -51,31 +55,39 @@ groups: - id: branch value: branch brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" - stability: experimental + stability: development - id: tag value: tag brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. + note: | + `base` refers to the starting point of a change. For example, `main` + would be the base reference of type branch if you've created a new + reference of type branch from it and created new commits. examples: ["branch", "tag"] - id: vcs.ref.base.revision type: string - stability: experimental + stability: development brief: > The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. note: | - The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + `base` refers to the starting point of a change. For example, `main` + would be the base reference of type branch if you've created a new + reference of type branch from it and created new commits. The + revision can be a full [hash value (see + glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the recorded change to a ref within a repository pointing to a commit [commit](https://git-scm.com/docs/git-commit) object. It does - not necessarily have to be a hash; it can simply define a - [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) + not necessarily have to be a hash; it can simply define a [revision + number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where - it is identical to the `ref.base.name`, it SHOULD still be included. It is - up to the implementer to decide which value to set as the revision - based on the VCS system and situational context. + it is identical to the `ref.base.name`, it SHOULD still be included. + It is up to the implementer to decide which value to set as the + revision based on the VCS system and situational context. examples: [ "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", @@ -85,11 +97,14 @@ groups: ] - id: vcs.ref.head.name type: string - stability: experimental + stability: development brief: > The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. + note: | + `head` refers to where you are right now; the current reference at a + given time. examples: ["my-feature-branch", "tag-1-test"] - id: vcs.ref.head.type type: @@ -97,31 +112,36 @@ groups: - id: branch value: branch brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" - stability: experimental + stability: development - id: tag value: tag brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. + note: | + `head` refers to where you are right now; the current reference at a + given time. examples: ["branch", "tag"] - id: vcs.ref.head.revision type: string - stability: experimental + stability: development brief: > The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. note: | - The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + `head` refers to where you are right now; the current reference at a + given time.The revision can be a full [hash value (see + glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the recorded change to a ref within a repository pointing to a commit [commit](https://git-scm.com/docs/git-commit) object. It does - not necessarily have to be a hash; it can simply define a - [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) + not necessarily have to be a hash; it can simply define a [revision + number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where - it is identical to the `ref.head.name`, it SHOULD still be included. It is - up to the implementer to decide which value to set as the revision - based on the VCS system and situational context. + it is identical to the `ref.head.name`, it SHOULD still be included. + It is up to the implementer to decide which value to set as the + revision based on the VCS system and situational context. examples: [ "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", @@ -135,12 +155,12 @@ groups: - id: branch value: branch brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" - stability: experimental + stability: development - id: tag value: tag brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. examples: ["branch", "tag"] @@ -150,12 +170,12 @@ groups: - id: behind value: behind brief: "How many revisions the change is behind the target ref." - stability: experimental + stability: development - id: ahead value: ahead brief: "How many revisions the change is ahead of the target ref." - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of revision comparison. examples: ["ahead", "behind"] @@ -165,18 +185,18 @@ groups: - id: added value: added brief: "How many lines were added." - stability: experimental + stability: development - id: removed value: removed brief: "How many lines were removed." - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of line change being measured on a branch or change. examples: ["added", "removed"] - id: vcs.change.title type: string - stability: experimental + stability: development brief: > The human readable title of the change (pull request/merge request/changelist). This title is often a brief summary of the change and may get merged @@ -189,7 +209,7 @@ groups: ] - id: vcs.change.id type: string - stability: experimental + stability: development brief: > The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. @@ -200,22 +220,22 @@ groups: - id: open value: open brief: "Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments." - stability: experimental + stability: development - id: wip value: wip brief: "WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes." - stability: experimental + stability: development - id: closed value: closed brief: >- Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request. - stability: experimental + stability: development - id: merged value: merged brief: "Merged indicates that the change has been successfully integrated into the target codebase." - stability: experimental - stability: experimental + stability: development + stability: development brief: > The state of the change (pull request/merge request/changelist). examples: ["open", "closed", "merged"]