# Why
The example files do not follow the specification. 64 bit integers
must be [string
encoded](https://protobuf.dev/programming-guides/proto3/#json).
# What
- Fix the encoding in the examples
- Add an example for log `severityNumber` to point at the enum
encoding rules.
Other enum element names in this repo are prefixed by enum name in CAPITAL_CASE.
This change makes naming of LogRecordFlags and DataPointFlags elements consistent
with the rest of the enums.
Resolves https://github.com/open-telemetry/opentelemetry-proto/issues/473
Co-authored-by: Bogdan Drutu <bogdandrutu@gmail.com>
Resolves https://github.com/open-telemetry/opentelemetry-proto/issues/433
## Problem
The zero values defined in helper enums encourage incorrect usage of
the bitfields.
The typical incorrect code looks like this:
```proto
enum DataPointFlags {
FLAG_NONE = 0;
FLAG_NO_RECORDED_VALUE = 1;
// Bits 2-31 are reserved for future use.
}
```
```go
if datapoint.Flags == FLAG_NONE {
// do something when there is no recorded value
}
```
This is incorrect because it does not take into account that the Flags field can
be extended in the future to use the reserved bits. The `if` statement above will
be incorrect if any other bit is set.
The correct code looks like this:
```go
if (datapoint.Flags & FLAG_NO_RECORDED_VALUE) == 0 {
// do something when there is no recorded value
}
```
## Solution
To prevent this mistake the following changes are done:
- All bitfield mask enums are suffixed with a _MASK to signify their purpose.
- Zero value of the enum is prefixed with an underscore to discourage its use.
- Some additional comments are added to explain how bitfields and their enums should be used.
## Alternates Tried
I also tried to remove the zero values from enums altogether, but it turned out to be impossible.
I tried a few possible approaches and none worked.
Protobufs [require that enums start with a 0 value](https://protobuf.dev/programming-guides/proto3/#enum).
If you try to omit it you get a compilation error:
```
opentelemetry/proto/metrics/v1/metrics.proto:325:28: The first enum value must be zero in proto3.
```
Alternatively, trying to use a dummy name, e.g.:
```
enum DataPointFlags {
_ = 0;
FLAG_NO_RECORDED_VALUE = 1;
}
```
Fails Objective-C generator:
```
error: got empty string for making TextFormat data, input: "", desired: "_".
```
Also tried declaring it reserved as the doc says should be possible:
```
enum DataPointFlags {
reserved 0;
FLAG_NO_RECORDED_VALUE = 1;
}
```
but get an error again:
```
opentelemetry/proto/metrics/v1/metrics.proto:327:28: The first enum value must be zero in proto3.
```
Emily S
Emily Stolfo
Armin Ruech
Bogdan Drutu
Ben Blackmore
Yang Song
Tigran Najaryan
Joshua MacDonald
Tigran Najaryan
Jay DeLuca
Patrice Chalin
Tobias Andersen
Patrice Chalin
jack-berg
Ruslan Kovalov
Joao Grassi
Joao Grassi