Merge branch 'main' into getter-get-duplicates

open-telemetry · Sep 7, 2021 · 38e8faf · 38e8faf
2 parents eadf7b8 + 25b1451
commit 38e8faf
Show file tree

Hide file tree

Showing 18 changed files with 391 additions and 38 deletions.
diff --git a/.github/workflows/publish-schemas.yml b/.github/workflows/publish-schemas.yml
@@ -0,0 +1,35 @@
+name: Update Schema files at OpenTelemetry Website
+
+on:
+  # triggers only on a manual dispatch
+  workflow_dispatch:
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/[email protected]
+      - name: make-pr
+        env:
+          API_TOKEN_GITHUB: ${{secrets.DOC_UPDATE_TOKEN}}
+          # Destination repo should always be 'open-telemetry/opentelemetry.io'
+          DESTINATION_REPO: open-telemetry/opentelemetry.io
+          # Destination path should be the absolute path to directory to publish in
+          DESTINATION_PATH: static/schemas
+          # Source path should be 'schemas', all files and folders are copied from here to dest
+          SOURCE_PATH: schemas
+        run: |
+          TARGET_DIR=$(mktemp -d)
+          export GITHUB_TOKEN=$API_TOKEN_GITHUB
+          git config --global user.name austinlparker
+          git config --global user.email [email protected]
+          git clone "https://[email protected]/$DESTINATION_REPO.git" "$TARGET_DIR"
+          rsync -av --delete "$SOURCE_PATH/" "$TARGET_DIR/$DESTINATION_PATH/"
+          cd "$TARGET_DIR"
+          git checkout -b schemas-$GITHUB_REPOSITORY-$GITHUB_SHA
+          git add .
+          git commit -m "Schemas update from $GITHUB_REPOSITORY"
+          git push -u origin HEAD:schemas-$GITHUB_REPOSITORY-$GITHUB_SHA
+          gh pr create -t "Schemas Update from $GITHUB_REPOSITORY" -b "This is an automated pull request." -B main -H schemas-$GITHUB_REPOSITORY-$GITHUB_SHA
+          echo "done"
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -10,7 +10,7 @@
         "MD040": false,
     },
     "yaml.schemas": {
-        "https://raw.githubusercontent.com/open-telemetry/build-tools/main/semantic-conventions/semconv.schema.json": [
+        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.5.0/semantic-conventions/semconv.schema.json": [
             "semantic_conventions/**/*.yaml"
         ]
     },

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,13 +30,24 @@ release.
   ([#1863](https://github.com/open-telemetry/opentelemetry-specification/pull/1863))
 - Lambda instrumentations should check if X-Ray parent context is valid
   ([#1867](https://github.com/open-telemetry/opentelemetry-specification/pull/1867))
+- Update YAML definitions for events
+  ([#1843](https://github.com/open-telemetry/opentelemetry-specification/pull/1843)):
+  - Mark exception as semconv type "event".
+  - Add YAML definitions for grpc events.
+- Add `messaging.consumer_id` to differentiate between message consumers.
+  ([#1810](https://github.com/open-telemetry/opentelemetry-specification/pull/1810))
+- Clarifications for `http.client_ip` and `http.host`.
+  ([#1890](https://github.com/open-telemetry/opentelemetry-specification/pull/1890))
 
 ### Compatibility
 
 ### OpenTelemetry Protocol
 
 ### SDK Configuration
 
+- Change default value for OTEL_EXPORTER_JAEGER_AGENT_PORT to 6831.
+  ([#1812](https://github.com/open-telemetry/opentelemetry-specification/pull/1812))
+
 ## v1.6.0 (2021-08-06)
 
 ### Context

diff --git a/Makefile b/Makefile
@@ -7,8 +7,10 @@ MISSPELL_BINARY=bin/misspell
 MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
 MARKDOWN_LINK_CHECK=markdown-link-check
 MARKDOWN_LINT=markdownlint
+
 # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
-SEMCONVGEN_VERSION=0.4.1
+# Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
+SEMCONVGEN_VERSION=0.5.0
 
 .PHONY: install-misspell
 install-misspell:

diff --git a/schemas/1.6.1 b/schemas/1.6.1
@@ -0,0 +1,6 @@
+file_format: 1.0.0
+schema_url: https://opentelemetry.io/schemas/1.6.1
+versions:
+  1.6.1:
+  1.5.0:
+  1.4.0:
diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md
@@ -17,12 +17,12 @@ i.e.:
 Semantic conventions for the spec MUST adhere to the
 [attribute naming conventions](../specification/common/attribute-naming.md).
 
-Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions/syntax.md)
+Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.5.0/semantic-conventions/syntax.md)
 for how to write the YAML files for semantic conventions and what the YAML properties mean.
 
 A schema file for VS code is configured in the `/.vscode/settings.json` of this
 repository, enabling auto-completion and additional checks. Refer to
-[the generator README](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions/README.md) for what extension you need.
+[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.5.0/semantic-conventions/README.md) for what extension you need.
 
 ## Generating markdown
 
@@ -33,7 +33,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run
 make table-generation
 ```
 
-For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions)
+For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.5.0/semantic-conventions)
 in the OpenTelemetry build tools repository.
 Using this build tool, it is also possible to generate code for use in OpenTelemetry
 language projects.

diff --git a/semantic_conventions/trace/exception.yaml b/semantic_conventions/trace/exception.yaml
@@ -1,6 +1,7 @@
 groups:
   - id: exception
     prefix: exception
+    type: event
     brief: >
       This document defines the attributes used to
       report a single exception associated with a span.

diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml
@@ -28,7 +28,13 @@ groups:
         type: string
         brief: >
             The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4).
-            When the header is empty or not present, this attribute should be the same.
+            An empty Host header should also be reported, see note.
+        note: >
+          When the header is present but empty the attribute SHOULD be set to
+          the empty string. Note that this is a valid situation that is expected
+          in certain cases, according the aforementioned
+          [section of RFC 7230](https://tools.ietf.org/html/rfc7230#section-5.4).
+          When the header is not set the attribute MUST NOT be set.
         examples: ['www.example.org']
       - id: scheme
         type: string
@@ -134,8 +140,18 @@ groups:
         brief: >
             The IP address of the original client behind all proxies, if
             known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)).
-        note: >
-            This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy.
+        note: |
+            This is not necessarily the same as `net.peer.ip`, which would
+            identify the network-level peer, which may be a proxy.
+
+            This attribute should be set when a source of information different
+            from the one used for `net.peer.ip`, is available even if that other
+            source just confirms the same value as `net.peer.ip`.
+            Rationale: For `net.peer.ip`, one typically does not know if it
+            comes from a proxy, reverse proxy, or the actual client. Setting
+            `http.client_ip` when it's the same as `net.peer.ip` means that
+            one is at least somewhat confident that the address is not that of
+            the closest proxy.
         examples: '83.164.160.102'
     constraints:
       - any_of:

diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml
@@ -112,6 +112,14 @@ groups:
           [Operation names](#operation-names) section above.
           If the operation is "send", this attribute MUST NOT be set, since the
           operation can be inferred from the span kind in that case.
+      - id: consumer_id
+        type: string
+        brief: >
+          The identifier for the consumer receiving a message. For Kafka, set it to
+          `{messaging.kafka.consumer_group} - {messaging.kafka.client_id}`, if both are present, or only
+          `messaging.kafka.consumer_group`. For brokers, such as RabbitMQ and Artemis, set it to the `client_id`
+          of the client consuming the message.
+        examples: 'mygroup - client-6'
 
   - id: messaging.consumer.synchronous
     prefix: messaging

diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml
@@ -2,6 +2,7 @@ groups:
   - id: rpc
     prefix: rpc
     brief: 'This document defines semantic conventions for remote procedure calls.'
+    events: [rpc.grpc.message]
     attributes:
       - id: system
         type: string
@@ -141,3 +142,26 @@ groups:
         note: >
           This is always required for jsonrpc. See the note in the general
           RPC conventions for more information.
+  - id: rpc.grpc.message
+    prefix: "message"  # TODO: Change the prefix to rpc.grpc.message?
+    type: event
+    brief: "gRPC received/sent message."
+    attributes:
+      - id: type
+        type:
+          members:
+            - id: sent
+              value: "SENT"
+            - id: received
+              value: "RECEIVED"
+        brief: "Whether this is a received or sent message."
+      - id: id
+        type: int
+        brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message."
+        note: "This way we guarantee that the values will be consistent between different implementations."
+      - id: compressed_size
+        type: int
+        brief: "Compressed size of the message in bytes."
+      - id: uncompressed_size
+        type: int
+        brief: "Uncompressed size of the message in bytes."
diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -163,9 +163,9 @@ Note: Support for environment variables is optional.
 | In-memory (mock exporter)                                                      |          | +  | + | +  | +           | +    | +      | -   | -    | +   | +    | +     |
 | [OTLP](specification/protocol/otlp.md)                                         |          |    |   |    |             |      |        |     |      |     |      |       |
 | OTLP/gRPC Exporter                                                             | *        | +  | + | +  | +           |      | +      |     | +    | +   | +    | +     |
-| OTLP/HTTP binary Protobuf Exporter                                             | *        | +  | - | +  | [-][py1106] | +    | +      |     |      | -   | -    | -     |
+| OTLP/HTTP binary Protobuf Exporter                                             | *        | +  | + | +  | [-][py1106] | +    | +      |     |      | -   | -    | -     |
 | OTLP/HTTP JSON Protobuf Exporter                                               |          | +  | - | +  | [-][py1003] |      | -      |     |      | -   | -    | -     |
-| OTLP/HTTP gzip Content-Encoding support                                        | X        | +  | - | +  | +           | +    | -      |     |      | -   | -    | -     |
+| OTLP/HTTP gzip Content-Encoding support                                        | X        | +  | + | +  | +           | +    | -      |     |      | -   | -    | -     |
 | Concurrent sending                                                             |          | -  | + | +  | [-][py1108] |      | -      |     | +    | -   | -    | -     |
 | Honors retryable responses with backoff                                        | X        | +  |   | +  | +           | +    | -      |     |      | -   | -    | -     |
 | Honors non-retryable responses                                                 | X        | +  |   | -  | +           | +    | -      |     |      | -   | -    | -     |

diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md
@@ -101,7 +101,7 @@ in order to preserve any previously existing valid value.
 Required arguments:
 
 - A `Context`.
-- The carrier that holds the propagation fields. For example, an incoming message or http response.
+- The carrier that holds the propagation fields. For example, an incoming message or HTTP request.
 
 Returns a new `Context` derived from the `Context` passed as argument,
 containing the extracted value, which can be a `SpanContext`,

diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md
@@ -668,6 +668,8 @@ Rest of SDIDs -> Attributes["syslog.*"]</td>
 
 ### Splunk HEC
 
+We apply this mapping from HEC to the unified model:
+
 <table>
   <tr>
     <td>Field</td>
@@ -719,6 +721,35 @@ Rest of SDIDs -> Attributes["syslog.*"]</td>
   </tr>
 </table>
 
+When mapping from the unified model to HEC, we apply this additional mapping:
+
+<table>
+  <tr>
+    <td>Unified model element</td>
+    <td>Type</td>
+    <td>Description</td>
+    <td>Maps to HEC</td>
+  </tr>
+  <tr>
+    <td>SeverityText</td>
+    <td>string</td>
+    <td>The severity of the event as a human-readable string.</td>
+    <td>fields['otel.log.severity.text']</td>
+  </tr>
+    <tr>
+    <td>SeverityNumber</td>
+    <td>string</td>
+    <td>The severity of the event as a number.</td>
+    <td>fields['otel.log.severity.number']</td>
+  </tr>
+  <tr>
+    <td>Name</td>
+    <td>string</td>
+    <td>Short event identifier that does not contain varying parts.</td>
+    <td>fields['otel.log.name']</td>
+  </tr>
+</table>
+
 ### Log4j
 
 <table>