[chore] Add documenation for severity parser's 'overwrite_with' setting (#35074)

See
#35049 (comment)

Author: djaglowski

pkg/stanza/docs/operators/severity_parser.md

@@ -4,16 +4,16 @@ The `severity_parser` operator sets the severity on an entry by parsing a value
 
 ### Configuration Fields
 
-| Field         | Default           | Description |
-| ---           | ---               | ---         |
-| `id`          | `severity_parser` | A unique identifier for the operator. |
-| `output`      | Next in pipeline  | The `id` for the operator to send parsed entries to. |
-| `parse_from`  | required          | The [field](../types/field.md) from which the value will be parsed. |
-| `on_error`    | `send`            | The behavior of the operator if it encounters an error. See [on_error](../types/on_error.md). |
-| `preset`      | `default`         | A predefined set of values that should be interpreted at specific severity levels. |
-| `mapping`     |                   | A formatted set of values that should be interpreted as severity levels. |
-| `if`          |                   | An [expression](../types/expression.md) that, when set, will be evaluated to determine whether this operator should be used for the given entry. This allows you to do easy conditional parsing without branching logic with routers. |
-
+| Field            | Default           | Description |
+| ---              | ---               | ---         |
+| `id`             | `severity_parser` | A unique identifier for the operator. |
+| `output`         | Next in pipeline  | The `id` for the operator to send parsed entries to. |
+| `parse_from`     | required          | The [field](../types/field.md) from which the value will be parsed. |
+| `on_error`       | `send`            | The behavior of the operator if it encounters an error. See [on_error](../types/on_error.md). |
+| `preset`         | `default`         | A predefined set of values that should be interpreted at specific severity levels. |
+| `mapping`        |                   | A formatted set of values that should be interpreted as severity levels. |
+| `overwrite_with` | `false`           | If `true`, the severity text will be set to the [standard short name](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#displaying-severity) corresponding to the severity number. |
+| `if`             |                   | An [expression](../types/expression.md) that, when set, will be evaluated to determine whether this operator should be used for the given entry. This allows you to do easy conditional parsing without branching logic with routers. |
 
 ### Example Configurations
 

pkg/stanza/docs/types/severity.md

@@ -8,12 +8,14 @@ Severity is represented as a number from 1 to 24. The meaning of these severity
 
 Parser operators can parse a severity and attach the resulting value to a log entry.
 
-| Field          | Default   | Description |
-| ---            | ---       | ---         |
-| `parse_from`   | required  | The [field](../types/field.md) from which the value will be parsed. |
-| `preset`       | `default` | A predefined set of values that should be interpretted at specific severity levels. |
-| `mapping`      |           | A custom set of values that should be interpretted at designated severity levels. |
-
+| Field            | Default   | Description |
+| ---              | ---       | ---         |
+| `parse_from`     | required  | The [field](../types/field.md) from which the value will be parsed. |
+| `preset`         | `default` | A predefined set of values that should be interpretted at specific severity levels. |
+| `mapping`        |           | A custom set of values that should be interpretted at designated severity levels. |
+| `overwrite_with` | `false`   | If `true`, the severity text will be set to the [recommeneded short name](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#displaying-severity) corresponding to the severity number. |
+
+Note that by default the severity _text_ will be set to the original value which was interpreted into a severity number. In order to set the severity text to a standard short name (e.g. `ERROR`, `INFO3`, etc.), set `overwrite_with` to `true`.
 
 ### How severity `mapping` works