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.
```
- Fix some out-of-date urls which link to [specification](https://github.com/open-telemetry/opentelemetry-specification).
- .../metrics/datamodel.md -> .../metrics/data-model.md
- .../common/common.md#attributes -> .../common/README.md#attribute
* Add field presence flag to proto build.
* Fix#314 - Cannot distinguish between sum being 0 and undefined.
* remove gogo from Makefile
Co-authored-by: Josh Suereth <joshuasuereth@google.com>
This applies changes described in spec PR https://github.com/open-telemetry/opentelemetry-specification/pull/2276
This is not a breaking change for OTLP. The wire format does not change.
The change is done in a way that the transition can be handled gracefully for OTLP/JSON and for the generated code. See the comments for explanation on how to do it in the senders and receivers.
As far as I know this is currently not used by anyone.
We prefer to delete this code instead of maintaining it.
It can be added back when there is sufficient interest
and a person who will maintain it.
The main motivation for this is to ensure that other protocols can use it to
send/receive OTLP data, as well as for persistent storages such as kafka, disk, etc.
Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>
* moved deprecated messages to the bottom of metrics.proto to help with
readability (especially for newbies!)
* Declare Logs Beta (#311)
The Log SIG discussed and made a decision to declare Log data model and Log part of OTLP Beta.
(See SIG meeting notes here https://docs.google.com/document/d/1cX5fWXyWqVVzYHSFUymYUfWxUK5hT97gc23w595LmdM/edit#heading=h.28y76as82bvu)
* incorporated feedback from PR review
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
* Refine descriptions of Histogram+Summary for explicit OpenMetrics compatibility
Fixes#187.
- Summary data points must record non-negative values
- Histogram sum can only be present if underlying measurements are non-negative. (Opening a bug to expand our API to allow this to present in more scenarios later)
* Update CHANGELOG.md
* Update CHANGELOG.md
Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>
* Call out openmetrics specification
* Update metrics.proto
Co-authored-by: Bogdan Drutu <bogdandrutu@gmail.com>
Co-authored-by: Bogdan Drutu <lazy@splunk.com>
Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>
* Add comments about StartTimeUnixNano
* Apply suggestions from code review
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
* From review feedback
* more text about unbroken sequence of observations
* Gauge overlap: delta or cumulative
* Update for gauges
* Fixes
* Remove detail text as being for the data model spec
* Remove 134-154
Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
Co-authored-by: Bogdan Drutu <bogdandrutu@gmail.com>
This move is explicitly a nod to the OpenMetrics form of Exemplar, which support a similar oneof form, allowing both integer and gauge values to co-exist in a Exemplar.
Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>
In other protos "dropped" is used to refer to counts of
how many of an item were discarded because did not meet
the spec (such as an attribute key being too long) or
because there is a limit on the total number.
This field is not labels dropped for not conforming to
a spec but labels filtered out because they were not
included in the aggregations definition of labels to
include. So this commit renames to `filtered` instead
of `dropped` to avoid confusion.
Krisztian Fekete
David Ashpole
Tigran Najaryan
Tigran Najaryan
Ruslan Kovalov
Bogdan Drutu
Joshua MacDonald
taloric
Alan West
Alex Boten
Victor Lu
Vamsee Lakamsani
Josh Suereth
Josh Suereth
Gianluca
Tristan Sloughter