doc/anomaly: describe unknown_ether_type in anomaly records

Describe the top-level "unknown_ether_type" field that anomaly records
for a packet with the decoder.ethernet.unknown_ethertype event now
carry, list it with the anomaly record fields, and explain how it
differs from "ether.ether_type" when the ethertype follows a tag. Add
an upgrade note for the new field.

Issue: 7849
Issue: 8142

doc/userguide/output/eve/eve-json-format.rst

@@ -527,6 +527,16 @@ Fields
 * "code" If "type" is "unknown", than "code" contains the unrecognized event
   code. Otherwise, this field is not present.
 
+Every anomaly record for a packet with the
+``decoder.ethernet.unknown_ethertype`` event, including the
+``decoder.vlan.unknown_type``, ``decoder.etag.unknown_type`` or
+``decoder.vntag.unknown_type`` record raised with it, has a top-level field
+outside the "anomaly" object:
+
+* "unknown_ether_type" The ethertype the decoder could not handle. When that
+  ethertype follows a VLAN, 802.1ah, E-Tag or VN-Tag header, the field differs
+  from "ether.ether_type", which holds the ethernet header's type.
+
 The following field is included when "type" has the value "applayer":
 
 * "layer" Indicates the handling layer that detected the event. This will be
@@ -562,6 +572,21 @@ Examples
       "event": "stream.pkt_invalid_timestamp"
     }
 
+    {
+      "event_type": "anomaly",
+      "vlan": [
+        100
+      ],
+      "ether": {
+        "ether_type": 33024
+      },
+      "anomaly": {
+        "type": "decode",
+        "event": "decoder.ethernet.unknown_ethertype"
+      },
+      "unknown_ether_type": 32821
+    }
+
     {
       "timestamp": "1969-12-31T16:04:21.000000-0800",
       "pcap_cnt": 9262,

doc/userguide/output/eve/eve-json-output.rst

@@ -176,6 +176,16 @@ Anomalies are reported by and configured by type:
 - Stream
 - Application layer
 
+Decode anomaly records for a packet with the
+``decoder.ethernet.unknown_ethertype`` event include the ethertype the decoder
+could not handle in a top-level ``unknown_ether_type`` field. Decoding stops at
+that ethertype, so a packet has at most one. When that ethertype follows a
+VLAN, 802.1ah, E-Tag or VN-Tag header, ``ether.ether_type`` (logged with
+``ethernet: yes``) holds the ethernet header's type, such as 0x8100 for VLAN,
+not the unknown one. After a VLAN, E-Tag or VN-Tag header the decoder also
+raises ``decoder.vlan.unknown_type``, ``decoder.etag.unknown_type`` or
+``decoder.vntag.unknown_type``, and that record carries the same field.
+
 Metadata::
 
     - anomaly:

doc/userguide/upgrade.rst

@@ -57,6 +57,10 @@ Logging Changes
   E.g., previously, ``ether_type`` values were logged in host order;  an ethertype value of ``0xfbb7``
   (network order) was logged as `47099`` (``0xb7fb``). This ethertype value will be logged as ``64439``.
 
+- Anomaly records for a packet with the ``decoder.ethernet.unknown_ethertype``
+  event now include the ethertype the decoder could not handle in a top-level
+  ``unknown_ether_type`` field.
+
 - Alert verdict key is changed from to ``reject-target`` to ``reject_target``
 
 - App-layer stats protocols names replace dash by underscore, meaning