Merge branch 'open-telemetry:main' into MSNev/AttributeSupport

open-telemetry · Oct 3, 2022 · 8b0ba0b · 8b0ba0b
2 parents a592a50 + ce32f94
commit 8b0ba0b
Show file tree

Hide file tree

Showing 11 changed files with 199 additions and 61 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,9 @@ release.
 
 ### Logs
 
+- Add environment variables for configuring the `BatchLogRecordProcessor`.
+  ([#2785](https://github.com/open-telemetry/opentelemetry-specification/pull/2785))
+
 ### Resource
 
 - Add `browser.mobile` and `browser.language` resource attributes
@@ -29,13 +32,24 @@ release.
 - Add `process.context_switches`, and `process.open_file_descriptors`, to the
   metrics semantic conventions
   ([#2706](https://github.com/open-telemetry/opentelemetry-specification/pull/2706))
+- Add exceptions to the logs semantic conventions
+  ([#2819](https://github.com/open-telemetry/opentelemetry-specification/pull/2819))
+- Make context propagation requirements explicit for messaging semantic conventions
+  ([#2750](https://github.com/open-telemetry/opentelemetry-specification/pull/2750)).
+- Update http metrics to use `http.route` instead of `http.target` for servers,
+  drop `http.url` for clients
+  ([#2818](https://github.com/open-telemetry/opentelemetry-specification/pull/2818)).
 
 ### Compatibility
 
 ### OpenTelemetry Protocol
 
 - Add user agent to OTLP exporter specification
   ([#2684](https://github.com/open-telemetry/opentelemetry-specification/pull/2684))
+- Clarify that unknown fields must be ignored when receiving OTLP/JSON
+  ([#2816](https://github.com/open-telemetry/opentelemetry-specification/pull/2816))
+- Add OTLP exporter user agent to the spec compliance matrix
+  ([#2842](https://github.com/open-telemetry/opentelemetry-specification/pull/2842)).
 
 ### SDK Configuration
 
@@ -94,8 +108,6 @@ release.
   ([#2768](https://github.com/open-telemetry/opentelemetry-specification/pull/2768)).
 - Add the signal-specific OTEL_EXPORTER_OTLP_LOGS_* environment variables
   ([#2782](https://github.com/open-telemetry/opentelemetry-specification/pull/2782)).
-- Add environment variables for configuring the `BatchLogRecordProcessor`.
-  ([#2785](https://github.com/open-telemetry/opentelemetry-specification/pull/2785))
 
 ### Resource
 

diff --git a/semantic_conventions/exception.yaml b/semantic_conventions/exception.yaml
@@ -0,0 +1,32 @@
+groups:
+  - id: exception
+    prefix: exception
+    brief: >
+      This document defines the shared attributes used to
+      report a single exception associated with a span or log.
+    attributes:
+      - id: type
+        type: string
+        brief: >
+          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.
+        examples: ["java.net.ConnectException", "OSError"]
+      - id: message
+        type: string
+        brief: The exception message.
+        examples: ["Division by zero", "Can't convert 'int' object to str implicitly"]
+      - id: stacktrace
+        type: string
+        brief: >
+          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.
+        examples: '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)'
+
+    constraints:
+      - any_of:
+          - "exception.type"
+          - "exception.message"
diff --git a/semantic_conventions/logs/log-exception.yaml b/semantic_conventions/logs/log-exception.yaml
@@ -0,0 +1,15 @@
+groups:
+  - id: log-exception
+    prefix: exception
+    brief: >
+      This document defines attributes for exceptions represented using Log
+      Records.
+    attributes:
+      - ref: exception.type
+      - ref: exception.message
+      - ref: exception.stacktrace
+
+    constraints:
+      - any_of:
+          - "exception.type"
+          - "exception.message"
diff --git a/semantic_conventions/trace/exception.yaml → ...ic_conventions/trace/trace-exception.yaml b/semantic_conventions/trace/exception.yaml → ...ic_conventions/trace/trace-exception.yaml
@@ -1,31 +1,14 @@
 groups:
-  - id: exception
+  - id: trace-exception
     prefix: exception
     type: event
     brief: >
       This document defines the attributes used to
       report a single exception associated with a span.
     attributes:
-      - id: type
-        type: string
-        brief: >
-          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.
-        examples: ["java.net.ConnectException", "OSError"]
-      - id: message
-        type: string
-        brief: The exception message.
-        examples: ["Division by zero", "Can't convert 'int' object to str implicitly"]
-      - id: stacktrace
-        type: string
-        brief: >
-          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.
-        examples: '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)'
+      - ref: exception.type
+      - ref: exception.message
+      - ref: exception.stacktrace
       - id: escaped
         type: boolean
         brief: >

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -316,6 +316,7 @@ Note: Support for environment variables is optional.
 | SchemaURL in ResourceSpans and ScopeSpans                                      |          | +  | +    |    | +           |      | +      |     |      |     | -    |       |
 | SchemaURL in ResourceMetrics and ScopeMetrics                                  |          |    | +    |    | +           |      | -      |     |      |     | -    |       |
 | SchemaURL in ResourceLogs and ScopeLogs                                        |          |    | +    |    | +           |      | -      |     |      |     | -    |       |
+| Honors the [user agent spec](specification/protocol/exporter.md#user-agent)    |          |    |      |    |             |      |        |     |      |     |      |       |
 | **[Zipkin](specification/trace/sdk_exporters/zipkin.md)**                      | Optional | Go  | Java | JS  | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
 | Zipkin V1 JSON                                                                 | X        | -  | +    |    | +           | -    | -      | -   | -    | -   | -    | -     |
 | Zipkin V1 Thrift                                                               | X        | -  | +    |    | [-][py1174] | -    | -      | -   | -    | -   | -    | -     |

diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md
@@ -470,7 +470,7 @@ Additional information about errors and/or exceptions that are associated with
 a log record MAY be included in the structured data in the `Attributes` section
 of the record.
 If included, they MUST follow the OpenTelemetry
-[semantic conventions for exception-related attributes](../trace/semantic_conventions/exceptions.md#attributes).
+[semantic conventions for exception-related attributes](./semantic_conventions/exceptions.md#attributes).
 
 ## Example Log Records
 

diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md
@@ -0,0 +1,50 @@
+# Semantic Conventions for Exceptions
+
+**Status**: [Experimental](../../document-status.md)
+
+This document defines semantic conventions for recording exceptions on
+[logs](../api.md#emit-logrecord) and [events](../api.md#emit-event) emitted
+through the [Logger API](../api.md#logger).
+
+<!-- toc -->
+
+- [Recording an Exception](#recording-an-exception)
+- [Attributes](#attributes)
+  * [Stacktrace Representation](#stacktrace-representation)
+
+<!-- tocstop -->
+
+## Recording an Exception
+
+Exceptions SHOULD be recorded as attributes on the
+[LogRecord](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit
+operations. Exceptions MAY be recorded on "logs" or "events" depending on the
+context.
+
+To encapsulate proper handling of exceptions API authors MAY provide a
+constructor, `RecordException` method/extension, or similar helper mechanism on
+the `LogRecord` class/structure or wherever it makes the most sense depending on
+the language runtime.
+
+## Attributes
+
+The table below indicates which attributes should be added to the
+[LogRecord](../api.md#logrecord) and their types.
+
+<!-- semconv log-exception -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
+| `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)` | Recommended |
+| `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` | See below |
+
+**Additional attribute requirements:** At least one of the following sets of attributes is required:
+
+* `exception.type`
+* `exception.message`
+<!-- endsemconv -->
+
+### Stacktrace Representation
+
+Same as [Trace Semantic Conventions for Exceptions - Stacktrace
+Representation](../../trace/semantic_conventions/exceptions.md#stacktrace-representation).
diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
@@ -43,17 +43,20 @@ Below is a table of HTTP client metric instruments.
 Below is a table of the attributes that SHOULD be included on `duration` and `size` metric events
 and whether they should be on server, client, or both types of HTTP metric events:
 
-| Name               | Type                | Requirement Level                                            | Notes and examples                                                                                                                                                                                                  |
-|----------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `http.method`        | `client` & `server` | Required                                                                     | The HTTP request method. E.g. `"GET"`                                                                                                                                |
-| `http.scheme`        | `server`            | Required                                                                     | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"`                                                                                                                              |
-| `http.status_code`   | `client` & `server` | Conditionally Required: if and only if one was received/sent.                | [HTTP response status code][]. E.g. `200` (String)                                                                                                                               |
-| `http.flavor`        | `client` & `server` | Recommended                                                                  | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`.                                                                                                                              |
-| `net.peer.name`      | `client`            | Required                                                                     | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.                                                                                         |
-| `net.peer.port`      | `client`            | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.                                                                                         |
-| `net.sock.peer.addr` | `client`            | Recommended                                                                  | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
-| `net.host.name`      | `server`            | Required                                                                     | Host of the local HTTP server that received the request.                                                                                                                               |
-| `net.host.port`      | `server`            | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request. |
+| Name                 | Type                | Requirement Level                                                            | Notes and examples                                                                                                                      |
+|----------------------|---------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
+| `http.method`        | `client` & `server` | Required                                                                     | The HTTP request method. E.g. `"GET"`                                                                                                   |
+| `http.scheme`        | `server`            | Required                                                                     | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"`                                                        |
+| `http.route`         | `server`            | Conditionally Required: If and only if it's available                        | The matched route (path template in the format used by the respective server framework). See note below [1]. E.g. `"/path/{id}/?q={}"`. |
+| `http.status_code`   | `client` & `server` | Conditionally Required: if and only if one was received/sent.                | [HTTP response status code][]. E.g. `200` (String)                                                                                      |
+| `http.flavor`        | `client` & `server` | Recommended                                                                  | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`.                                                              |
+| `net.peer.name`      | `client`            | Required                                                                     | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.             |
+| `net.peer.port`      | `client`            | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.             |
+| `net.sock.peer.addr` | `client`            | Recommended                                                                  | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)     |
+| `net.host.name`      | `server`            | Required                                                                     | Host of the local HTTP server that received the request.                                                                                |
+| `net.host.port`      | `server`            | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request.                                                                                |
+
+**[1]:** 'http.route' MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
 
 The following attributes SHOULD be included in the `http.server.active_requests` observation:
 
@@ -67,26 +70,3 @@ The following attributes SHOULD be included in the `http.server.active_requests`
 [HTTP host header]: https://www.rfc-editor.org/rfc/rfc9110.html#name-host-and-authority
 [HTTP response status code]: https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes
 [HTTP reason phrase]: https://www.rfc-editor.org/rfc/rfc9110.html#section-15.1
-
-### Parameterized attributes
-
-To avoid high cardinality the following attributes SHOULD substitute any parameters when added as attributes to http metric events as described below:
-
-| Attribute name | Type    | Requirement Level | Notes and examples                                                                                     |
-|----------------|---------|-------------------|--------------------------------------------------------------------------------------------------------|
-| `http.url`     | `client` | Required         | The originally requested URL                                                                           |
-| `http.target`  | `server` | Required         | The full request target as passed in a [HTTP request target][] or equivalent, e.g. `"/path/{id}/?q={}"`. |
-
-[Http request target]: https://www.rfc-editor.org/rfc/rfc9110.html#name-determining-the-target-reso
-
-Many REST APIs encode parameters into the URI path, e.g. `/api/users/123` where `123`
-is a user id, which creates high cardinality value space not suitable for attributes on metric events.
-In case of HTTP servers, these endpoints are often mapped by the server
-frameworks to more concise _HTTP routes_, e.g. `/api/users/{user_id}`, which are
-recommended as the low cardinality attribute values. However, the same approach usually
-does not work for HTTP client attributes, especially when instrumentation is provided
-by a lower-level middleware that is not aware of the specifics of how the URIs
-are formed. Therefore, HTTP client attributes SHOULD be using conservative, low
-cardinality names formed from the available parameters of an HTTP request,
-such as `"HTTP {METHOD_NAME}"`. These attributes MUST NOT default to using URI
-path.
diff --git a/specification/protocol/otlp.md b/specification/protocol/otlp.md
@@ -419,6 +419,11 @@ for mapping between Protobuf and JSON, with the following deviations from that m
   represented like this:
   { "kind": 2, ... }
 
+- OTLP/JSON receivers MUST ignore message fields with unknown names and MUST unmarshal the
+  message as if the unknown field was not present in the payload.
+  This aligns with the behavior of the Binary Protobuf unmarshaler and ensures that adding
+  new fields to OTLP messages does not break existing receivers.
+
 Note that according to [Protobuf specs](
 https://developers.google.com/protocol-buffers/docs/proto3#json) 64-bit integer
 numbers in JSON-encoded payloads are encoded as decimal strings, and either