CHANGELOG.md

@@ -11,14 +11,24 @@ release.
 
 ### Traces
 
+- Rename `http.retry_count` to `http.resend_count` and clarify its meaning.
+  ([#2743](https://github.com/open-telemetry/opentelemetry-specification/pull/2743))
+
 ### Metrics
 
+- Handle duplicate description comments during Prometheus conversion.
+  ([#2890](https://github.com/open-telemetry/opentelemetry-specification/pull/2890))
+
 ### Logs
 
 ### Resource
 
 ### Semantic Conventions
 
+- Add gRPC request and response metadata semantic conventions
+  ([#2874](https://github.com/open-telemetry/opentelemetry-specification/pull/2874))
+- Add `process.paging.faults` metric to semantic conventions
+  ([#2827](https://github.com/open-telemetry/opentelemetry-specification/pull/2827))
 - Add `process.start_time` resource attribute to semantic conventions
   ([#2825](https://github.com/open-telemetry/opentelemetry-specification/pull/2825))
 

CONTRIBUTING.md

@@ -266,3 +266,41 @@ owner should bring it to the [OpenTelemetry Specification SIG
 meeting](https://github.com/open-telemetry/community#cross-language-specification).
 
 [nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating
+
+## Releasing
+
+Release Procedure:
+
+1. Prepare a [draft release here](https://github.com/open-telemetry/opentelemetry-specification/releases).
+   Don't publish it yet.
+2. Create a PR with updated [CHANGELOG.md](CHANGELOG.md). The CHANGELOG.md must have a
+   heading with the new version number. Ensure that no CHANGELOG entries are missing or
+   ended up in the wrong section (e.g., in the last released version rather than Unreleased).
+   The PR will fail the `schemas-check` Github action (all other actions must pass).
+   This is expected and will be fixed in the next steps. Have this PR reviewed and approved
+   and ready to be merged. While it is being reviewed you can work on step 3-4 in parallel.
+3. Prepare the schema file for the upcoming release. The schema file should be placed
+   in the `schemas` directory. If no changes to semantic conventions happened
+   since the last release which require a corresponding section in the schema file then
+   simply copy the previous schema file, rename it to the new version and add a section
+   with the new version number to the file. See for example the schema file for [1.9.0](
+   https://github.com/open-telemetry/opentelemetry-specification/blob/main/schemas/1.9.0)
+   that has no changes from 1.8.0.
+   The schema file may already exist if there were changes done to semantic conventions
+   and the schema file was created with corresponding changes.
+4. Create and merge the PR with the new schema file. Note the commit hash after merging.
+   If the schema file for the new release version previously existed then no new PR is
+   necessary, just note that latest commit hash of this repository.
+5. Once CHANGELOG.md PR is approved and ready to be merged we are ready to make the release.
+   Update the [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io)
+   repository: the [opentelemetry-specification](
+   https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules)
+   submodule points to this repository. Create a PR and update the submodule to point to
+   the commit hash from step 4. Merge this PR. This should update the
+   [https://opentelemetry.io/](https://opentelemetry.io/) website and the new schema file
+   should be downloadable at `https://opentelemetry.io/schemas/<version>`.
+6. Re-trigger the `schema-checks` Github action on the PR that updates the CHANGELOG.md.
+   The action should pass now. Merge the PR.
+7. Add the changelog entries from `CHANGELOG.md` to the description of the previously
+   created [draft release here](
+   https://github.com/open-telemetry/opentelemetry-specification/releases) and publish it.

experimental/serialization/json.md

@@ -73,12 +73,3 @@ This is an example showing logs:
 {"resourceLogs":[{"resource":{"attributes":[{"key":"resource-attr","value":{"stringValue":"resource-attr-val-1"}}]},"instrumentationLibraryLogs":[{"instrumentationLibrary":{},"logs":[{"timeUnixNano":"1581452773000005443","severityNumber":"SEVERITY_NUMBER_INFO","severityText":"Info","name":"logA","body":{"stringValue":"This is a log message"},"attributes":[{"key":"app","value":{"stringValue":"server"}},{"key":"instance_num","value":{"intValue":"1"}}],"droppedAttributesCount":1,"traceId":"08040201000000000000000000000000","spanId":"0102040800000000"},{"timeUnixNano":"1581452773000000789","severityNumber":"SEVERITY_NUMBER_INFO","severityText":"Info","name":"logB","body":{"stringValue":"something happened"},"attributes":[{"key":"customer","value":{"stringValue":"acme"}},{"key":"env","value":{"stringValue":"dev"}}],"droppedAttributesCount":1,"traceId":"","spanId":""}]}]}]}
 {"resourceLogs":[{"resource":{"attributes":[{"key":"resource-attr","value":{"stringValue":"resource-attr-val-1"}}]},"instrumentationLibraryLogs":[{"instrumentationLibrary":{},"logs":[{"timeUnixNano":"1581452773000009875","severityNumber":"SEVERITY_NUMBER_INFO","severityText":"Info","name":"logA","body":{"stringValue":"This is a log message"},"attributes":[{"key":"app","value":{"stringValue":"server"}},{"key":"instance_num","value":{"intValue":"1"}}],"droppedAttributesCount":1,"traceId":"08040201000000000000000000000000","spanId":"0102040800000000"},{"timeUnixNano":"1581452773000000789","severityNumber":"SEVERITY_NUMBER_INFO","severityText":"Info","name":"logB","body":{"stringValue":"something happened"},"attributes":[{"key":"customer","value":{"stringValue":"acme"}},{"key":"env","value":{"stringValue":"dev"}}],"droppedAttributesCount":1,"traceId":"","spanId":""}]}]}]}
 ```
-
-This is an example showing traces, metrics and logs together:
-
-```json lines
-{"resourceSpans":[{"resource":{"attributes":[{"key":"resource-attr","value":{"stringValue":"resource-attr-val-1"}}]},"instrumentationLibrarySpans":[{"instrumentationLibrary":{},"spans":[{"traceId":"","spanId":"","parentSpanId":"","name":"operationA","startTimeUnixNano":"1581452772000000321","endTimeUnixNano":"1581452773000000789","droppedAttributesCount":1,"events":[{"timeUnixNano":"1581452773000000123","name":"event-with-attr","attributes":[{"key":"span-event-attr","value":{"stringValue":"span-event-attr-val"}}],"droppedAttributesCount":2},{"timeUnixNano":"1581452773000000123","name":"event","droppedAttributesCount":2}],"droppedEventsCount":1,"status":{"deprecatedCode":"DEPRECATED_STATUS_CODE_UNKNOWN_ERROR","message":"status-cancelled","code":"STATUS_CODE_ERROR"}},{"traceId":"","spanId":"","parentSpanId":"","name":"operationB","startTimeUnixNano":"1581452772000000321","endTimeUnixNano":"1581452773000000789","links":[{"traceId":"","spanId":"","attributes":[{"key":"span-link-attr","value":{"stringValue":"span-link-attr-val"}}],"droppedAttributesCount":4},{"traceId":"","spanId":"","droppedAttributesCount":1}],"droppedLinksCount":3,"status":{}}]}]}]}
-{"resourceMetrics":[{"resource":{"attributes":[{"key":"resource-attr","value":{"stringValue":"resource-attr-val-1"}}]},"instrumentationLibraryMetrics":[{"instrumentationLibrary":{},"metrics":[{"name":"counter-int","unit":"1","sum":{"dataPoints":[{"attributes":[{"key":"label-1","value":{"stringValue":"label-value-1"}}],"startTimeUnixNano":"1581452773000001459","timeUnixNano":"1581452773000001459","asInt":"120"},{"attributes":[{"key":"label-2","value":{"stringValue":"label-value-2"}}],"startTimeUnixNano":"1581452773000001459","timeUnixNano":"1581452773000001459","asInt":"456"}],"aggregationTemporality":"AGGREGATION_TEMPORALITY_CUMULATIVE","isMonotonic":true}},{"name":"counter-int","unit":"1","sum":{"dataPoints":[{"attributes":[{"key":"label-1","value":{"stringValue":"label-value-1"}}],"startTimeUnixNano":"1581452773000001459","timeUnixNano":"1581452773000001459","asInt":"123"},{"attributes":[{"key":"label-2","value":{"stringValue":"label-value-2"}}],"startTimeUnixNano":"1581452773000001459","timeUnixNano":"1581452773000001459","asInt":"456"}],"aggregationTemporality":"AGGREGATION_TEMPORALITY_CUMULATIVE","isMonotonic":true}}]}]}]}
-{"resourceSpans":[{"resource":{"attributes":[{"key":"resource-attr","value":{"stringValue":"resource-attr-val-1"}}]},"instrumentationLibrarySpans":[{"instrumentationLibrary":{},"spans":[{"traceId":"","spanId":"","parentSpanId":"","name":"operationA","startTimeUnixNano":"1581452772000000321","endTimeUnixNano":"1581452773000000789","droppedAttributesCount":1,"events":[{"timeUnixNano":"1581452773000000826","name":"event-with-attr","attributes":[{"key":"span-event-attr","value":{"stringValue":"span-event-attr-val"}}],"droppedAttributesCount":2},{"timeUnixNano":"1581452773000000826","name":"event","droppedAttributesCount":2}],"droppedEventsCount":1,"status":{"deprecatedCode":"DEPRECATED_STATUS_CODE_UNKNOWN_ERROR","message":"status-cancelled","code":"STATUS_CODE_ERROR"}},{"traceId":"","spanId":"","parentSpanId":"","name":"operationB","startTimeUnixNano":"1581452772000200521","endTimeUnixNano":"1581452773000004789","links":[{"traceId":"","spanId":"","attributes":[{"key":"span-link-attr","value":{"stringValue":"span-link-attr-val"}}],"droppedAttributesCount":5},{"traceId":"","spanId":"","droppedAttributesCount":2}],"droppedLinksCount":3,"status":{}}]}]}]}
-{"resourceLogs":[{"resource":{"attributes":[{"key":"resource-attr","value":{"stringValue":"resource-attr-val-1"}}]},"instrumentationLibraryLogs":[{"instrumentationLibrary":{},"logs":[{"timeUnixNano":"1581452773000005443","severityNumber":"SEVERITY_NUMBER_INFO","severityText":"Info","name":"logA","body":{"stringValue":"This is a log message"},"attributes":[{"key":"app","value":{"stringValue":"server"}},{"key":"instance_num","value":{"intValue":"1"}}],"droppedAttributesCount":1,"traceId":"08040201000000000000000000000000","spanId":"0102040800000000"},{"timeUnixNano":"1581452773000000789","severityNumber":"SEVERITY_NUMBER_INFO","severityText":"Info","name":"logB","body":{"stringValue":"something happened"},"attributes":[{"key":"customer","value":{"stringValue":"acme"}},{"key":"env","value":{"stringValue":"dev"}}],"droppedAttributesCount":1,"traceId":"","spanId":""}]}]}]}
-```

internal/tools/schema_check.sh

@@ -31,6 +31,13 @@ grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while re
     echo "FAILED: $file does not exist. The schema file must exist because the version is declared in CHANGELOG.md."
     exit 3
   fi
+
+  curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver
+
+  diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \
+    || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3)
+
+  rm verify$ver
 done
 
 # Now check the content of all schema files in the ../shemas directory.

schemas/1.15.0

@@ -0,0 +1,34 @@
+file_format: 1.1.0
+schema_url: https://opentelemetry.io/schemas/1.15.0
+versions:
+  1.15.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2743
+        - rename_attributes:
+            attribute_map:
+              http.retry_count: http.resend_count
+  1.14.0:
+  1.13.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2614
+        - rename_attributes:
+            attribute_map:
+              net.peer.ip: net.sock.peer.addr
+              net.host.ip: net.sock.host.addr
+  1.12.0:
+  1.11.0:
+  1.10.0:
+  1.9.0:
+  1.8.0:
+    spans:
+      changes:
+        - rename_attributes:
+            attribute_map:
+              db.cassandra.keyspace: db.name
+              db.hbase.namespace: db.name
+  1.7.0:
+  1.6.1:
+  1.5.0:
+  1.4.0:

semantic_conventions/trace/http.yaml

@@ -113,10 +113,14 @@ groups:
         note: >
           When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match
           URI port identifier, otherwise it MUST match `Host` header port identifier.
-      - id: retry_count
+      - id: resend_count
         type: int
         brief: >
-          The ordinal number of request re-sending attempt.
+          The ordinal number of request resending attempt (for any reason, including redirects).
+        note: >
+          The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what
+          was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues,
+          or any other).
         requirement_level:
           recommended: if and only if request was retried.
         examples: 3