Repository navigation
attribute: add String method for KeyValue - #8205
Conversation
Codecov Reportโ
All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #8205 +/- ##
=====================================
Coverage 89.1% 89.1%
=====================================
Files 338 338
Lines 22269 22270 +1
=====================================
+ Hits 19850 19851 +1
Misses 2419 2419
๐ New features to boost your workflow:
|
|
Is there precedence in OTel for this form of a key-value encoding? |
There is some precedence, but I would frame it as debug-output precedent rather than a spec-defined canonical encoding. Inside this repo, I also checked a couple of other SDKs: .NETโs and Python console exporters prints attributes as From the spec side, there it is not defined how a attribute pair should be formatted to a string. Yet, for maps the current spec actually says they SHOULD be represented as JSON objects. This was what we originally used as inspiration. I think this also makes biggest sense for us since e.g. Given that, I think the safest justification is: However, I also started to think if we should not follow https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#maps more closely and have something like I also checked a couple of other SDKs: .NETโs and Python console exporters prints attributes as Key:Value, while Java has internal key-value debug encodings that use = or JSON depending on the structure. Therefore, that is no single canonical cross-SDK string form. If we think it is worth standardizing, I would be open to a small spec follow-up to define a recommended string form for an attribute pair in non-OTLP / debug contexts. |
|
@open-telemetry/go-approvers, can you make a high-level review this PR? For sure a benchmark is missing (added in TODO). There is no need to "approve", but I want to have an agreement on the direction. Please also check #8205 (comment) |
|
I like standardizing this, and I think JSON is readable and universal. Do we want to go further, and able to print out a slice of attribute.KeyVal as |
The thing that came to mind was metricdatatest |
I created #8210 |
โฆemetry#5028) ### What Adds in-development guidance for representing a single OpenTelemetry attribute as a string in non-OTLP protocols. The recommended form is a single-entry JSON object, for example: ```json {"http.request.method":"GET"} ``` **Implementation:** - open-telemetry/opentelemetry-go#8205 in OTel Go we are using non-OTLP string represnetation for debugging ### Why - open-telemetry/opentelemetry-go#7810 The narrower purpose is to fill a gap in the existing non-OTLP string representation guidance. The specification already has stable guidance for representing `AnyValue` values as strings when a non-OTLP protocol cannot represent some `AnyValue` types natively. What is missing is the corresponding representation for a single `Attribute`, which is a key plus an `AnyValue`. This PR proposes that the single attribute is represented as a single-member JSON object, with the member value following the existing non-OTLP `AnyValue` representation rules. I originally thought about `key:value` (and even `key=value` beforehand), but it is ambiguous when `:` appears in keys or string values and is not a robust debugging representation. Using a JSON object improves clarity for debugging output by: - aligning with existing non-OTLP, JSON-based guidance for complex `AnyValue` types - making the representation easier to read and copy when needed This also is consistent with how OTel Java, .NET, Python, Go are representing attributes in standard output exporters. Therefore, I think it would be most familiar representation for the users. Why not OTLP/JSON? For the OTel Go use case, the compact (lossy) non-OTLP representation is practical for human-readable output such as test failures. `String()` is intended for debugging and logging, and its output is not expected to be lossless nor suitable for deserialization. A canonical OTLP JSON `KeyValue` would need wrapper fields such as `{"key":"http.request.method","value":{"stringValue":"GET"}}`, which is much more verbose than `{"http.request.method":"GET"}` and harder to scan in failure messages. Moreover, OTel Go `attribute.Value.String()` already follows the non-OTLP `AnyValue` rules: <open-telemetry/opentelemetry-go#8142> (as OTel Go maintainers, we want to use an OTel-wide representation even for debugging output). We want `attribute.KeyValue.String()` to follow the same rules, but the string representation of a single attribute is not yet specified; this PR fills that gap and is currently blocking <open-telemetry/opentelemetry-go#8205>.
โฆemetry#5028) ### What Adds in-development guidance for representing a single OpenTelemetry attribute as a string in non-OTLP protocols. The recommended form is a single-entry JSON object, for example: ```json {"http.request.method":"GET"} ``` **Implementation:** - open-telemetry/opentelemetry-go#8205 in OTel Go we are using non-OTLP string represnetation for debugging ### Why - open-telemetry/opentelemetry-go#7810 The narrower purpose is to fill a gap in the existing non-OTLP string representation guidance. The specification already has stable guidance for representing `AnyValue` values as strings when a non-OTLP protocol cannot represent some `AnyValue` types natively. What is missing is the corresponding representation for a single `Attribute`, which is a key plus an `AnyValue`. This PR proposes that the single attribute is represented as a single-member JSON object, with the member value following the existing non-OTLP `AnyValue` representation rules. I originally thought about `key:value` (and even `key=value` beforehand), but it is ambiguous when `:` appears in keys or string values and is not a robust debugging representation. Using a JSON object improves clarity for debugging output by: - aligning with existing non-OTLP, JSON-based guidance for complex `AnyValue` types - making the representation easier to read and copy when needed This also is consistent with how OTel Java, .NET, Python, Go are representing attributes in standard output exporters. Therefore, I think it would be most familiar representation for the users. Why not OTLP/JSON? For the OTel Go use case, the compact (lossy) non-OTLP representation is practical for human-readable output such as test failures. `String()` is intended for debugging and logging, and its output is not expected to be lossless nor suitable for deserialization. A canonical OTLP JSON `KeyValue` would need wrapper fields such as `{"key":"http.request.method","value":{"stringValue":"GET"}}`, which is much more verbose than `{"http.request.method":"GET"}` and harder to scan in failure messages. Moreover, OTel Go `attribute.Value.String()` already follows the non-OTLP `AnyValue` rules: <open-telemetry/opentelemetry-go#8142> (as OTel Go maintainers, we want to use an OTel-wide representation even for debugging output). We want `attribute.KeyValue.String()` to follow the same rules, but the string representation of a single attribute is not yet specified; this PR fills that gap and is currently blocking <open-telemetry/opentelemetry-go#8205>.
โฆTLP (open-telemetry#5149) This is needed to unblock: - open-telemetry/opentelemetry-go#8146 - open-telemetry/opentelemetry-go#8209 Prototypes: - open-telemetry/opentelemetry-go#8205 - open-telemetry/opentelemetry-go#8347 - open-telemetry/opentelemetry-java#8768 I think that this sections are not controversial and could be stabilized without having more prototypes. Please double-check the sections that are being stabilized in this PR.
|
@open-telemetry/go-approvers, this is ready for review as open-telemetry/opentelemetry-specification#5149 is merged. |
There was a problem hiding this comment.
๐ก Changes recommended
Benchmark results should retain v.String() in the package-level sink on lines 44 and 53.
Get a fresh assessment by requesting another Copilot review.
Review details
Suppressed comments (1)
attribute/benchmark_test.go:53
- Please keep the returned string alive in this benchmark too. Discarding
kv.String()can let the compiler eliminate or simplify the formatting work, making the newKeyValueStringnumbers unreliable; use the package-level sink as the other string benchmark does.
kv.String()
- Files reviewed: 4/4 changed files
- Comments generated: 1
- Review effort level: Lite
Fix three issues reported by OSS-Fuzz in fuzz test harnesses: 1. `attribute.FuzzHashKVs` (OSS-Fuzztimeout): - Problem: `FuzzHashKVs` copies `kvs` to `modifiedKvs` and mutates `modifiedKvs[0]` to check for hash collisions (`h1 == h3 && !reflect.DeepEqual(kvs, modifiedKvs)`). However, several `modifiedKvs[0]` value types were either unhandled or left unmodified by the switch statement (e.g., `FLOAT64` when `NaN`, `ยฑInf`, or large values where `val + 1.0 == val`; `BOOLSLICE`, `INT64SLICE`, `FLOAT64SLICE`, `STRINGSLICE`, `BYTESLICE`; and empty `SLICE`/`MAP`). When `modifiedKvs[0]` went unmodified (`h1 == h3`) and `kvs` also contained a `Float64Slice` with `math.NaN()`, `!reflect.DeepEqual(kvs, modifiedKvs)` evaluated to `true` because `reflect.DeepEqual(NaN, NaN)` is `false` in Go. - Impact: Under OSS-Fuzz's `go-118-fuzz-build` adapter, `t.Logf` unconditionally prints to `stdout`. After open-telemetry#8205 added `KeyValue.String()` (which serializes `SliceValue`/`MapValue` via JSON), falsely triggering `t.Logf("Potential hash collision detected: original=%v, modified=%v...")` on a 263 KB invalid-UTF-8 string formatted 8 copies of the string (~18 MB of `\ufffd`-escaped JSON) under `-gcflags=all=-d=libfuzzer` instrumentation, taking ~150s for a single input and exceeding the 60s timeout. - Fix: Ensure `modifiedKvs[0]` is mutated across all value types and edge cases (replacing non-finite floats with `0.0`, using `math.Nextafter` when `val + 1.0 == val`, handling all slice types and empty `SLICE`/`MAP` values), and avoid formatting the full `kvs` slices in `t.Logf`. 2. `sdk/metric/internal/aggregate.FuzzGetBin` (Closes open-telemetry#7576): - Problem: `FuzzGetBin` passed arbitrary `float64` values directly to `getBin(v)`, whereas `expoHistogram.measure` filters out `ยฑInf` and `NaN` beforehand, and `lowerBound(bin, scale)` loses precision in the subnormal `float64` range (`v < 0x1p-1022`) where IEEE-754 floats have fewer than 53 significand bits (e.g. `lowerBound(getBin(0x1p-1069), 6)` rounds up to `0x1p-1069`, violating `lowerBound < v`). - Fix: Skip `v < smallestNonZeroNormalFloat64 || math.IsInf(v, 0) || math.IsNaN(v)` in `FuzzGetBin`. 3. `trace.FuzzSpanIDFromHex` and `trace.FuzzTraceIDFromHex`: - Problem: `regexp.MustCompile` was called inside `FuzzSpanIDFromHex(f *testing.F)` and `FuzzTraceIDFromHex(f *testing.F)` outside `f.Fuzz(...)`. While standard `go test -fuzz` executes the outer `Fuzz*(f)` setup once, OSS-Fuzz's `go-118-fuzz-build` wrapper invokes `Fuzz*(fuzzer)` from the top on every single fuzz iteration. Re-compiling the regular expressions on every input generated heavy heap allocation, GC churn, and `SIGURG` async preemption pressure in the Go `c-archive` + `libFuzzer`/`ASAN` runtime. - Fix: Hoist `validTraceIDRe` and `validSpanIDRe` to package-level variables so they are compiled once at package initialization.
โฆ#8996) Fix three issues reported by OSS-Fuzz in fuzz test harnesses. None of the fixes represent real issues. 1. **`attribute.FuzzHashKVs` (OSS-Fuzz `564808681` โ >60s Timeout)** - **Problem:** `FuzzHashKVs` copies `kvs` into `modifiedKvs` and mutates `modifiedKvs[0]` to check for hash collisions via `if h1 == h3 && !reflect.DeepEqual(kvs, modifiedKvs)`. However, several `modifiedKvs[0]` types and values were left unmodified by the `switch` statement: - `FLOAT64` when `f1` is `NaN`, `ยฑInf` (`NaN + 1.0` is still `NaN` with identical bits, `ยฑInf + 1.0 == ยฑInf`), or a large float (`|f1| >= 2^53`, where `f1 + 1.0 == f1`). - `BOOLSLICE`, `INT64SLICE`, `FLOAT64SLICE`, `STRINGSLICE`, and `BYTESLICE` (omitted from the `switch`). - `SLICE` and `MAP` when empty (`len == 0`). - **Why it timed out:** Whenever `modifiedKvs[0]` was left unmodified (`h1 == h3`) **and** `kvs` also contained a `Float64Slice` with `math.NaN()` (which `FuzzHashKVs` unconditionally constructs when `b` has `0x7ff8...` bytes), `reflect.DeepEqual(kvs, modifiedKvs)` returned `false` because `reflect.DeepEqual(NaN, NaN)` is always `false` in Go. This falsely triggered `t.Logf("Potential hash collision detected: original=%v, modified=%v, hash=%d", kvs, modifiedKvs, h1)`. Under OSS-Fuzz's `go-118-fuzz-build` adapter, `t.Logf` unconditionally prints to `stdout`. After #8205 added `KeyValue.String()` (which serializes `SliceValue` and `MapValue` as JSON via `appendJSONString`), formatting both `kvs` and `modifiedKvs` with a 263 KB invalid-UTF-8 string `s` serialized 8 copies of `s` (~18 MB of `\ufffd`-escaped JSON) under `-gcflags=all=-d=libfuzzer` comparison instrumentation, taking ~150 seconds for a single input. - **Fix:** Ensure `modifiedKvs[0]` is mutated across all value types and edge cases (replacing non-finite floats with `0.0`, using `math.Nextafter` when `val + 1.0 == val`, handling all primitive slice types, and mutating empty `SLICE`/`MAP` values), and avoid formatting the full `kvs` slices in `t.Logf`. 2. **`sdk/metric/internal/aggregate.FuzzGetBin` (OSS-Fuzz `458865858`, Closes #7576)** - **Problem:** `FuzzGetBin` passed arbitrary `float64` values directly to `getBin(v)`. In production, `expoHistogram.measure` filters out `ยฑInf` and `NaN` before recording values, and `lowerBound(bin, scale)` loses precision in the subnormal `float64` range (`v < 0x1p-1022`) where IEEE-754 subnormal numbers have fewer than 53 significand bits (e.g., `0x1p-1069` has only 5 bits of precision, causing `lowerBound(getBin(0x1p-1069), 6)` to round up to `0x1p-1069` and fail the `lowerBound < v` assertion). - **Fix:** Skip `v < smallestNonZeroNormalFloat64 || math.IsInf(v, 0) || math.IsNaN(v)` in `FuzzGetBin`. 3. **`trace.FuzzSpanIDFromHex` & `trace.FuzzTraceIDFromHex` (OSS-Fuzz `498709184`)** - **Problem:** `validTraceIDRe := regexp.MustCompile(...)` and `validSpanIDRe := regexp.MustCompile(...)` were placed inside `FuzzTraceIDFromHex(f *testing.F)` and `FuzzSpanIDFromHex(f *testing.F)` outside `f.Fuzz(...)`. While standard `go test -fuzz` runs the outer `Fuzz*(f)` setup once per process, OSS-Fuzz's `go-118-fuzz-build` adapter (`LLVMFuzzerTestOneInput` -> `LibFuzzerFuzzSpanIDFromHex`) calls `FuzzSpanIDFromHex(fuzzer)` from the top on **every single fuzz input**. Re-parsing and compiling the regular expression on every iteration caused unnecessary heap allocation, GC churn, and `SIGURG` async preemption signal pressure in the Go `c-archive` + `libFuzzer`/`ASAN` runtime. - **Fix:** Hoist `validTraceIDRe` and `validSpanIDRe` to package-level variables so they are compiled once at package initialization.
This release contains the first stable release of the OpenTelemetry Go Logs API and SDK. Our project stability guarantees now apply to the following modules: - `go.opentelemetry.io/otel/log` - `go.opentelemetry.io/otel/sdk/log` See our [versioning policy](https://github.com/open-telemetry/opentelemetry-go/blob/main/VERSIONING.md) for more information about these stability guarantees. ### Added - Add `String` method for `KeyValue` type in `go.opentelemetry.io/otel/attribute`. (#8205) - Add `String` method for `Set` type in `go.opentelemetry.io/otel/attribute`. (#8347) - Add `WithMaxExportBatchSize` to `go.opentelemetry.io/otel/sdk/metric` to configure the maximum export batch size for `PeriodicReader`. (#8960) - Add `WithAttributeValueDepthLimit`, `DefaultAttributeValueDepthLimit`, and `SpanLimits.AttributeValueDepthLimit` in `go.opentelemetry.io/otel/sdk/trace` to configure the maximum depth of span, event, link, and instrumentation scope attribute values. (#8938) - Add `WithAttributeValueDepthLimit` in `go.opentelemetry.io/otel/sdk/log` to configure the maximum depth of log record and instrumentation scope attribute values. (#8938) - Add `WithMaxResponseSize` to `go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp`, `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp`, and `go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp`. (#8941) - Add experimental `ProbabilitySampler` in `go.opentelemetry.io/otel/sdk/trace/x` that conforms to the [OpenTelemetry specification's threshold-based sampling algorithm](https://opentelemetry.io/docs/specs/otel/trace/sdk/#probabilitysampler). (#8123) - Add experimental `*Binder` extension interfaces in `go.opentelemetry.io/otel/metric/x` for instruments that support binding attributes ahead of time. (#8760) - Add the experimental `Finisher` synchronous metric instrument extension interface to `go.opentelemetry.io/otel/metric/x`. (#8906) ### Changed - Use the [OpenTelemetry Attribute Collection representation for non-OTLP protocols](https://opentelemetry.io/docs/specs/otel/common/#attribute-collection-representation-for-non-otlp) for metric data diffs in `go.opentelemetry.io/otel/sdk/metric/metricdata/metricdatatest`. (#8993) - Apply a maximum depth of 64 by default to span, event, link, log record, and instrumentation scope attribute values in `go.opentelemetry.io/otel/sdk/trace` and `go.opentelemetry.io/otel/sdk/log`. (#8938) - Reduce allocations when applying attribute value length limits in `go.opentelemetry.io/otel/sdk/trace` and `go.opentelemetry.io/otel/sdk/log` by rebuilding composite values only when truncation is needed. (#8912) - Decode `traceparent` using a hex lookup table in `go.opentelemetry.io/otel/propagation`, which rejects the specification-disallowed upper-case characters without a separate scan of the header. (#8739) - Decode all characters at constant indices in `TraceIDFromHex` and `SpanIDFromHex` in `go.opentelemetry.io/otel/trace` to eliminate bounds checks. (#8740) ### Fixed - Count valid U+FFFD replacement characters toward attribute value length limits in `go.opentelemetry.io/otel/trace`, `go.opentelemetry.io/otel/sdk/trace`, and `go.opentelemetry.io/otel/sdk/log`. - Truncate string attribute values to empty strings when the configured length limit is zero, including malformed UTF-8, in `go.opentelemetry.io/otel/trace`, `go.opentelemetry.io/otel/sdk/trace`, and `go.opentelemetry.io/otel/sdk/log`. (#9054) - Fix a data race in `NewPeriodicReader` where `r.inst` was assigned after the background goroutine was launched in `go.opentelemetry.io/otel/sdk/metric`. (#9028) - Prevent precision loss for large `int64` values in `Sum`, `Histogram`, and `ExponentialHistogram` aggregations in `go.opentelemetry.io/otel/sdk/metric`. (#8981) - Ensure `grpc.DialOption` values passed via `WithDialOption` take precedence over conflicting internally-computed defaults in `go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc`, `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc`, and `go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc`. (#8805, #8834, #8836) - Treat overflowing `OTEL_METRIC_EXPORT_INTERVAL` and `OTEL_METRIC_EXPORT_TIMEOUT` values as invalid in `go.opentelemetry.io/otel/sdk/metric`. (#8800) - Prevent a panic in `NewFixedSizeReservoir` and `FixedSizeReservoirProvider` when given a negative size in `go.opentelemetry.io/otel/sdk/metric/exemplar`; negative sizes are now clamped to zero, consistent with a size of zero. (#8832) - Preserve exponential histogram `ZeroThreshold` during OTLP metric export in `go.opentelemetry.io/otel/exporters/otlp/otlpmetric`. (#8801) - Ensure metric helpers in `go.opentelemetry.io/otel/semconv/v1.32.0`, `go.opentelemetry.io/otel/semconv/v1.33.0`, and `go.opentelemetry.io/otel/semconv/v1.34.0` record measurements only once when no attributes are provided. (#8849) - Treat empty `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG` values as unset in `go.opentelemetry.io/otel/sdk/trace`. (#8873) - Normalize global `OTEL_EXPORTER_OTLP_ENDPOINT` path joining in `go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp` so trailing-slash base URLs do not produce double-slash log export paths. (#8864) - Prevent a deadlock when formatting an error passed to `RecordError` calls back into the span in `go.opentelemetry.io/otel/sdk/trace`. (#8815) - Prevent `SimpleSpanProcessor.Shutdown` from panicking when constructed with a nil exporter in `go.opentelemetry.io/otel/sdk/trace`. (#8844) - Propagate invalid exponential histogram scale errors to Prometheus exporter self-observability metrics in `go.opentelemetry.io/otel/exporters/prometheus`. (#8839) - Retain instrument advisory attributes configured with `go.opentelemetry.io/otel/metric/x.WithDefaultAttributes` when a matching View in `go.opentelemetry.io/otel/sdk/metric` does not specify an attribute filter. (#8859) - Ignore HTTP URL paths when building OTLP/gRPC metric exporter targets from `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, while preserving `unix://` and `unix-abstract://` targets; treat `unix-abstract://` endpoints as insecure in `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc` and `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp`. (#8862) - Ignore HTTP(S) paths when deriving gRPC trace exporter endpoints from `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` in `go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc`. (#8852) - Bound memory used while parsing dense W3C property metadata by storing it compactly and materializing `Property` values on demand in `go.opentelemetry.io/otel/baggage` and `go.opentelemetry.io/otel/propagation`. ### Removed - Remove the experimental `OTEL_GO_X_METRIC_EXPORT_BATCH_SIZE` environment variable in `go.opentelemetry.io/otel/sdk/metric`. Use the `WithMaxExportBatchSize` option instead. (#8960)
Fixes #8146
Towards #7810
Adds
attribute.KeyValue.String, using the stable OpenTelemetry Attribute representation for non-OTLP protocols. Each key-value pair is encoded as a single-member JSON object, and the value reuses the existing non-OTLP AnyValue formatter so strings, byte slices, special floating-point values, empty values, slices, and maps are represented consistently withattribute.Value.String.The governing representation was stabilized by open-telemetry/opentelemetry-specification#5149.
The implementation delegates to the shared map formatter used by composite attribute values, keeping representation and escaping rules in one place.
Benchmarks
The direct
formatMapcall was compared withformatMapValue([1]KeyValue{kv})over six runs. It reduced scalar geomean latency by 35.84%, bytes by 57.14%, and allocations from two to one while retaining the shared formatter.Scalar values:
Slice, composite, and map values: