Merge branch 'main' into deprecate_jaeger_exporter

CHANGELOG.md

@@ -11,6 +11,9 @@ release.
 
 ### Traces
 
+- Rename `http.retry_count` to `http.resend_count` and clarify its meaning.
+ ([#2743](https:/open-telemetry/opentelemetry-specification/pull/2743))
+
 ### Metrics
 
 ### Logs
@@ -19,10 +22,21 @@ release.
 
 ### Semantic Conventions
 
+- Add gRPC request and response metadata semantic conventions
+ ([#2874](https:/open-telemetry/opentelemetry-specification/pull/2874))
+- Add `process.paging.faults` metric to semantic conventions
+ ([#2827](https:/open-telemetry/opentelemetry-specification/pull/2827))
+
 ### Compatibility
 
+- Specify how Prometheus exporters and receivers handle instrumentation scope.
+ ([#2703](https:/open-telemetry/opentelemetry-specification/pull/2703)).
+
 ### OpenTelemetry Protocol
 
+- Clarify that lowerCamelCase field names MUST be used for OTLP/JSON
+ ([#2829](https:/open-telemetry/opentelemetry-specification/pull/2829))
+
 ### SDK Configuration
 
 ### Telemetry Schemas

CONTRIBUTING.md

@@ -266,3 +266,41 @@ owner should bring it to the [OpenTelemetry Specification SIG
 meeting](https:/open-telemetry/community#cross-language-specification).
 
 [nvm]: https:/nvm-sh/nvm/blob/master/README.md#installing-and-updating
+
+## Releasing
+
+Release Procedure:
+
+1. Prepare a [draft release here](https:/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:/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:/open-telemetry/opentelemetry.io)
+ repository: the [opentelemetry-specification](
+ https:/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:/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:/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:/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

specification/README.md

@@ -53,11 +53,17 @@ implementation of the [specification][] is compliant if it satisfies all the
 "MUST", "MUST NOT", "REQUIRED", "SHALL", and "SHALL NOT" requirements defined in
 the [specification][].
 
-## Acronym
+## Project Naming
 
-- The official acronym used by the OpenTelemetry project is "OTel".
-- Refrain from using "OT" in order to avoid confusion with the now deprecated
- "OpenTracing" project.
+- The official project name is "OpenTelemetry" (with no space between "Open" and
+ "Telemetry").
+- The official acronym used by the OpenTelemetry project is "OTel". Refrain from
+ using "OT" in order to avoid confusion with the now deprecated "OpenTracing"
+ project.
+- The official names for sub-projects, like language specific implementations,
+ follow the pattern of "OpenTelemetry {the name of the programming language,
+ runtime or component}", for example, "OpenTelemetry Python", "OpenTelemetry
+ .NET" or "OpenTelemetry Collector".
 
 ## About the project
 

specification/glossary.md

@@ -106,7 +106,8 @@ Coding against the OpenTelemetry API such as the [Tracing API](trace/api.md), [M
 ### Automatic Instrumentation
 
 Refers to telemetry collection methods that do not require the end-user to modify application's source code.
-Methods vary by programming language, and examples include bytecode injection or monkey patching.
+Methods vary by programming language, and examples include code manipulation (during compilation or at runtime),
+monkey patching, or running eBPF programs.
 
 Synonym: *Auto-instrumentation*.
 

specification/logs/data-model.md

@@ -474,70 +474,8 @@ If included, they MUST follow the OpenTelemetry
 
 ## Example Log Records
 
-Below are examples that show one possible representation of log records in JSON.
-These are just examples to help understand the data model. Don’t treat the
-examples as _the_ way to represent this data model in JSON.
-
-This document does not define the actual encoding and format of the log record
-representation. Format definitions will be done in separate OTEPs (e.g. the log
-records may be represented as msgpack, JSON, Protocol Buffer messages, etc).
-
-Example 1
-
-```javascript
-{
- "Timestamp": "1586960586000000000",
- "Attributes": {
- "http.status_code": 500,
- "http.url": "http://example.com",
- "my.custom.application.tag": "hello",
- },
- "Resource": {
- "service.name": "donut_shop",
- "service.version": "2.0.0",
- "k8s.pod.uid": "1138528c-c36e-11e9-a1a7-42010a800198",
- },
- "TraceId": "f4dbb3edd765f620", // this is a byte sequence
- // (hex-encoded in JSON)
- "SpanId": "43222c2d51a7abe3",
- "SeverityText": "INFO",
- "SeverityNumber": 9,
- "Body": "20200415T072306-0700 INFO I like donuts"
-}
-```
-
-Example 2
-
-```javascript
-{
- "Timestamp": "1586960586000000000",
- ...
- "Body": {
- "i": "am",
- "an": "event",
- "of": {
- "some": "complexity"
- }
- }
-}
-```
-
-Example 3
-
-```javascript
-{
- "Timestamp": "1586960586000000000",
- "Attributes":{
- "http.scheme":"https",
- "http.host":"donut.mycie.com",
- "http.target":"/order",
- "http.method":"post",
- "http.status_code":500,
- "http.flavor":"1.1",
- "http.user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
- }
-}
-```
+For example log records see
+[JSON File serialization](../../experimental/serialization/json.md).
 
 ## Appendix A. Example Mappings