Merge branch 'main' into old_short_name

CHANGELOG.md

@@ -13,16 +13,48 @@ release.
 
 ### Metrics
 
+### Logs
+
+### Resource
+
+### Semantic Conventions
+
+### Compatibility
+
+### OpenTelemetry Protocol
+
+### SDK Configuration
+
+### Telemetry Schemas
+
+### Common
+
+## v1.14.0 (2022-10-04)
+
+### Context
+
+- No changes.
+
+### Traces
+
+- No changes.
+
+### Metrics
+
 - Changed the default buckets for Explicit Bucket Histogram to better match the
   official Prometheus clients.
   ([#2770](https://github.com/open-telemetry/opentelemetry-specification/pull/2770)).
+- Fix OpenMetrics valid label keys, and specify prometheus conversion for metric name.
+  ([#2788](https://github.com/open-telemetry/opentelemetry-specification/pull/2788))
 - Specify how Prometheus exporters and receivers handle instrumentation scope.
   ([#2703](https://github.com/open-telemetry/opentelemetry-specification/pull/2703)).
 
 ### Logs
 
 - Add environment variables for configuring the `BatchLogRecordProcessor`.
   ([#2785](https://github.com/open-telemetry/opentelemetry-specification/pull/2785))
+- Fix inconsistencies in log README
+  ([#2800](https://github.com/open-telemetry/opentelemetry-specification/pull/2800)).
 
 ### Resource
 
@@ -34,25 +66,44 @@ 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
 
+- No changes.
+
 ### OpenTelemetry Protocol
 
 - Add user agent to OTLP exporter specification
   ([#2684](https://github.com/open-telemetry/opentelemetry-specification/pull/2684))
+- Prohibit usage of enum value name strings in OTLP/JSON
+  ([#2758](https://github.com/open-telemetry/opentelemetry-specification/pull/2758))
 - 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
 
+- Add the OTEL_SDK_DISABLED environment variable to the SDK configuration.
+  ([2679](https://github.com/open-telemetry/opentelemetry-specification/pull/2679))
 - Add the definition of a Boolean environment variable
   ([#2755](https://github.com/open-telemetry/opentelemetry-specification/pull/2755)).
 
 ### Telemetry Schemas
 
+- No changes.
+
 ### Common
 
+- No changes.
+
 ## v1.13.0 (2022-09-19)
 
 ### Context
@@ -153,9 +204,6 @@ release.
 
 ### SDK Configuration
 
-- Add the OTEL_SDK_DISABLED environment variable to the SDK configuration.
-  ([2679](https://github.com/open-telemetry/opentelemetry-specification/pull/2679))
-
 - Mark `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_METRIC_EXPORT_TIMEOUT`
   environment variables as Stable
   ([#2658](https://github.com/open-telemetry/opentelemetry-specification/pull/2658))

schemas/1.14.0

@@ -0,0 +1,27 @@
+file_format: 1.1.0
+schema_url: https://opentelemetry.io/schemas/1.14.0
+versions:
+  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/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"

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"

semantic_conventions/trace/exception.yaml → semantic_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: >

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] | -    | -      | -   | -    | -   | -    | -     |

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/README.md

@@ -124,14 +124,19 @@ languages have established standards for using particular logging libraries. For
 example in Java world there are several highly popular and widely used logging
 libraries, such as Log4j or Logback.
 
+OpenTelemetry defines [events](#events-and-logs) as a type of LogRecord with
+specific characteristics. This definition is not ubiquitous across existing
+libraries and languages. In some logging libraries, producing events aligned
+with the OpenTelemetry event definition is clunky or error-prone.
+
 There are also countless existing prebuilt applications or systems that emit
 logs in certain formats. Operators of such applications have no or limited
 control on how the logs are emitted. OpenTelemetry needs to support these logs.
 
 Given the above state of the logging space we took the following approach:
 
 - OpenTelemetry defines a [log data model](data-model.md). The purpose of the
-  data model is to have a common understanding of what a log record is, what
+  data model is to have a common understanding of what a LogRecord is, what
   data needs to be recorded, transferred, stored and interpreted by a logging
   system.
 
@@ -143,25 +148,28 @@ Given the above state of the logging space we took the following approach:
   OpenTelemetry log data model. OpenTelemetry Collector can read such logs and
   translate them to OpenTelemetry log data model.
 
-- Existing applications or logging libraries can be modified to emit logs
-  according to OpenTelemetry log data model. OpenTelemetry does not define a new
-  logging API that application developers are expected to call. Instead we opt
-  to make it easy to continue using the common logging libraries that already
-  exist. OpenTelemetry provides guidance on how applications or logging
-  libraries can be modified to become OpenTelemetry-compliant (link TBD). We
-  also provide SDKs for some languages (link TBD) that make it easy to modify
-  the existing logging libraries so that they emit OpenTelemetry-compliant logs.
+- OpenTelemetry defines an API
+  for [emitting LogRecords](./api.md#emit-logrecord). Application developers are
+  NOT encouraged to call this API directly. It is provided for library authors
+  to build [Appenders](./api.md#how-to-create-log4j-style-appender), which use
+  the API to bridge between existing logging libraries and the OpenTelemetry log
+  data model. Existing logging libraries generally provide a much richer set of
+  features than what is defined in OpenTelemetry. It is NOT a goal of
+  OpenTelemetry to ship a feature-rich logging library.
+
+- OpenTelemetry defines an API for [emitting Events](./api.md#emit-event).
+  Application developers are encouraged to call this API directly.
+
+- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md),
+  which enables configuration of [processing](./sdk.md#logrecordprocessor)
+  and [exporting](./sdk.md#logrecordexporter) LogRecords.
 
 This approach allows OpenTelemetry to read existing system and application logs,
 provides a way for newly built application to emit rich, structured,
 OpenTelemetry-compliant logs, and ensures that all logs are eventually
 represented according to a uniform log data model on which the backends can
 operate.
 
-In the future OpenTelemetry may define a new logging API and provide
-implementations for various languages (like we currently do for traces and
-metrics), but it is not an immediate priority.
-
 Later in this document we will discuss in more details
 [how various log sources are handled](#legacy-and-modern-log-sources) by
 OpenTelemetry, but first we need to describe in more details an important
@@ -179,15 +187,15 @@ Logs can be correlated with the rest of observability data in a few dimensions:
   standard practice to record the execution context (trace and span ids as well
   as user-defined context) in the spans. OpenTelemetry extends this practice to
   logs where possible by including [TraceId](data-model.md#field-traceid) and
-  [SpanId](data-model.md#field-spanid) in the log records. This allows to
+  [SpanId](data-model.md#field-spanid) in the LogRecords. This allows to
   directly correlate logs and traces that correspond to the same execution
   context. It also allows to correlate logs from different components of a
   distributed system that participated in the particular request execution.
 
 - By the **origin of the telemetry**, also known as the Resource context.
   OpenTelemetry traces and metrics contain information about the Resource they
   come from. We extend this practice to logs by including the
-  [Resource](data-model.md#field-resource) in log records.
+  [Resource](data-model.md#field-resource) in LogRecords.
 
 These 3 correlations can be the foundation of powerful navigational, filtering,
 querying and analytical capabilities. OpenTelemetry aims to record and collects
@@ -200,21 +208,15 @@ Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file):
 >In computing, a log file is a file that records either events that occur in an
 >operating system or other software runs.
 
-The notion of a log record used throughout OpenTelemetry is aligned with
-Wikipedia’s definition. We claim that in the observability realm there is no
-important distinction between log records and recorded events from a data
-modeling perspective.
-
-From OpenTelemetry's perspective Log Records and Events are different names for
-the same concept.
+From OpenTelemetry's perspective LogRecords and Events are both represented
+using the same [data model](./data-model.md).
 
-Some products may want to make a distinction between Events collected from
-certain sources and Logs collected from other sources. OpenTelemetry believes
-that there is nothing inherently different between log records and events from
-data modeling perspective, the differences are in the sources themselves. Thus
-where it matters the products should make that distinction based on the source
-of the data rather than attempt to arbitrarily categorize the data as events vs
-logs.
+However, OpenTelemetry does recognize a subtle semantic difference between
+LogRecords and Events: Events are LogRecords which have a `name` and `domain`.
+Within a particular `domain`, the `name` uniquely defines a particular class or
+type of event. Events with the same `domain` / `name` follow the same schema
+which assists in analysis in observability platforms. Events are described in
+more detail in the [semantic conventions](./semantic_conventions/events.md).
 
 ## Legacy and Modern Log Sources
 
@@ -323,7 +325,7 @@ collected from all applications that can be instrumented in this manner.
 Some logging libraries are designed to be extended in this manner relatively
 easily. There is no need to actually modify the libraries, instead we can
 implement "appender" or "exporter" components for such libraries and implement
-the additional log record enrichment in these components.
+the additional LogRecord enrichment in these components.
 
 There are typically 2 ways to collect logs from these applications.
 
@@ -383,14 +385,15 @@ highly structured format, removes all complexity associated with file logs, such
 as parsers, log tailing and rotation. It also enables the possibility to send
 logs directly to the logging backend without using a log collection agent.
 
-To facilitate both approaches described above OpenTelemetry provides SDKs, which
-can be used together with existing logging libraries and which automatically
-inject the request context in the emitted logs and provide an easy way to send
-the logs via OTLP. These SDKs do not require application developers to modify
-each logging statement in the source code and instead require the developer to
-enable the OpenTelemetry SDK's logging support at the application startup. After
-that the SDK intercepts all emitted logs and modifies the emitting behavior as
-configured.
+To facilitate both approaches described above OpenTelemetry provides
+an [API](./api.md) and [SDK](./sdk.md), which can be used together with existing
+logging libraries to automatically inject the request context in the emitted logs,
+and provide an easy way to send the logs via OTLP. Instead of
+modifying each logging statement, [Appenders](./api.md#how-to-create-log4j-style-appender)
+use the API to bridge logs from existing logging libraries to the OpenTelemetry
+data model, where the SDK controls how the logs are processed and exported.
+Application developers only need to configure the Appender and SDK at
+application startup.
 
 ### New First-Party Application Logs
 
@@ -408,10 +411,8 @@ augmented by application-specific resource context (e.g. process id, programming
 language, logging library name and version, etc). Full correlation across all
 context dimensions will be available for these logs.
 
-As noted earlier OpenTelemetry does not currently define a new logging API or
-create new user-facing logging libraries. Our initial goal is to enhance
-existing popular logging libraries as needed. This is how a typical new
-application uses OpenTelemetry API, SDK and the existing log libraries:
+This is how a typical new application uses OpenTelemetry API, SDK and the
+existing log libraries:
 
 ![Application, API, SDK Diagram](img/application-api-sdk.png)
 

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