Merge branch 'main' into rabbitmq-destination-name

.chloggen/code-rename.yaml

@@ -0,0 +1,26 @@
+# 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: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: code
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: rename `code.function`, `code.lineno`, `code.column` and `code.filepath`
+
+# 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: [ 1377, 1599 ]
+
+# (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: |
+  `code.function` renamed to `code.function.name`
+  `code.lineno` renamed to `code.line.number`
+  `code.column` renamed to `code.column.number`
+  `code.filepath` renamed to `code.file.path`

.github/workflows/changelog.yml

@@ -75,9 +75,7 @@ jobs:
             || { echo "New ./.chloggen/*.yaml file failed validation."; exit 1; }
 
       # In order to validate any links in the yaml file, render the config to markdown
-      - name: Render .chloggen changelog entries
+      - name: Run markdown-link-check on the changelog
         run: |
-          make chlog-preview 2> changelog_preview.md
-          cat changelog_preview.md
-      - name: Run markdown-link-check
-        run: make markdown-link-check-changelog-preview
+          make chlog-preview &> changelog_preview.md
+          make markdown-link-check-changelog-preview

.lychee.toml

@@ -0,0 +1,16 @@
+include_fragments = true
+
+accept = ["200..=299", "403"]
+
+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+$"
+]
+
+# better to be safe and avoid failures
+max_retries = 6
+
+# insecure is currently needed for https://osi-model.com
+insecure = true

CONTRIBUTING.md

@@ -169,7 +169,23 @@ You can also take examples from past changes inside the `schemas` folder.
 ### 2. Update the markdown files
 
 After updating the YAML file(s), you need to update
-the respective markdown files. For this, run the following commands:
+the respective markdown files.
+If you want to update existing tables, just run the following commands:
+
+```bash
+make table-generation attribute-registry-generation
+```
+
+When defining new telemetry signals (spans, metrics, events, resources) in YAML,
+make sure to add a new markdown section describing them. Add the following
+code-snippet into the markdown file:
+
+```
+<!-- semconv new-group-id -->
+<!-- endsemconv -->
+```
+
+Then run markdown generation commands:
 
 ```bash
 make table-generation attribute-registry-generation

Makefile

@@ -68,16 +68,23 @@ misspell-correction:	$(MISSPELL)
 
 .PHONY: markdown-link-check
 markdown-link-check:
-	@if ! npm ls markdown-link-check; then npm install; fi
-	@for f in $(ALL_DOCS); do \
-		npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json $$f \
-			|| exit 1; \
-	done
+	docker run --rm \
+		--mount 'type=bind,source=$(PWD),target=/home/repo' \
+		lycheeverse/lychee \
+		--config home/repo/.lychee.toml \
+		--root-dir /home/repo \
+		--verbose \
+		home/repo
 
 .PHONY: markdown-link-check-changelog-preview
 markdown-link-check-changelog-preview:
-	@if ! npm ls markdown-link-check; then npm install; fi
-	npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json changelog_preview.md;
+	docker run --rm \
+		--mount 'type=bind,source=$(PWD),target=/home/repo' \
+		lycheeverse/lychee \
+		--config /home/repo/.lychee.toml \
+		--root-dir /home/repo \
+		--verbose \
+		home/repo/changelog_preview.md
 
 # This target runs markdown-toc on all files that contain
 # a comment <!-- tocstop -->.

docs/README.md

@@ -22,6 +22,7 @@ Semantic Conventions are defined for the following areas:
 
 * **[General](general/README.md): General Semantic Conventions**.
 * [CICD](cicd/cicd-metrics.md): Semantic Conventions for CICD systems.
+* [Code](code/README.md): Semantic Conventions for code.
 * [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries.
 * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
 * [Database](database/README.md): Semantic Conventions for database operations.

docs/attributes-registry/code.md

@@ -6,15 +6,29 @@
 
 # Code
 
+- [Code Attributes](#code-attributes)
+- [Deprecated Code Attributes](#deprecated-code-attributes)
+
 ## Code Attributes
 
-These attributes allow to report this unit of code and therefore to provide more context about the span.
+These attributes provide context about source code
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="code-column" href="#code-column">`code.column`</a> | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="code-filepath" href="#code-filepath">`code.filepath`</a> | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="code-function" href="#code-function">`code.function`</a> | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="code-lineno" href="#code-lineno">`code.lineno`</a> | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="code-namespace" href="#code-namespace">`code.namespace`</a> | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="code-column-number" href="#code-column-number">`code.column.number`</a> | int | The column number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. | `16` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="code-file-path" href="#code-file-path">`code.file.path`</a> | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="code-function-name" href="#code-function-name">`code.function.name`</a> | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="code-line-number" href="#code-line-number">`code.line.number`</a> | int | The line number in `code.file.path` best representing the operation. It SHOULD point within the code unit named in `code.function.name`. | `42` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="code-namespace" href="#code-namespace">`code.namespace`</a> | string | The "namespace" within which `code.function.name` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function.name` form a unique identifier for the code unit. | `com.example.MyHttpService` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="code-stacktrace" href="#code-stacktrace">`code.stacktrace`</a> | 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. | `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)` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+## Deprecated Code Attributes
+
+These deprecated attributes provide context about source code
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| <a id="code-column" href="#code-column">`code.column`</a> | int | Deprecated, use `code.column.number` | `16` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `code.column.number` |
+| <a id="code-filepath" href="#code-filepath">`code.filepath`</a> | string | Deprecated, use `code.file.path` instead | `/usr/local/MyApplication/content_root/app/index.php` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="code-function" href="#code-function">`code.function`</a> | string | Deprecated, use `code.function.name` instead | `serveRequest` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `code.function.name` |
+| <a id="code-lineno" href="#code-lineno">`code.lineno`</a> | int | Deprecated, use `code.line.number` instead | `42` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `code.line.number` |

docs/attributes-registry/faas.md

@@ -42,7 +42,7 @@ FaaS attributes
 **[6] `faas.name`:** This is the name of the function as configured/deployed on the FaaS
 platform and is usually different from the name of the callback
 function (which may be stored in the
-[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes)
+[`code.namespace`/`code.function.name`](/docs/general/attributes.md#source-code-attributes)
 span attributes).
 
 For some cloud providers, the above definition is ambiguous. The following

docs/attributes-registry/rpc.md

@@ -43,7 +43,7 @@ This document defines attributes for remote procedure calls.
 
 **[5] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations.
 
-**[6] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[6] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
 
 **[7] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
 

docs/cloud-providers/aws-sdk.md

@@ -39,7 +39,7 @@ with the naming guidelines for RPC client spans.
 | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+**[1] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
 
 **[2] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
 

docs/code/README.md

@@ -0,0 +1,23 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Code
+path_base_for_github_subdir:
+  from: tmp/semconv/docs/code/_index.md
+  to: code/README.md
+--->
+
+# Semantic Conventions for Code
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for source code.
+
+> **Warning**
+>
+> Existing code instrumentations that are using
+> [v1.29.0 of `code` conventions](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/attributes-registry/code.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the `code` conventions that they emit by default
+    >   until the `code` semantic conventions are marked stable.
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status