docs(api): state that links at span creation are preferred (#68) - #133
Merged
michaelbushe merged 7 commits intoSep 13, 2026
Merged
michaelbushe merged 7 commits into
michaelbushe merged 7 commits into
Conversation
yuzurihaaa
requested review from
michaelbushe and
robert-northmind
as code owners
September 10, 2026 11:33
trace/api.md requires the API documentation to state that adding links at span creation is preferred to calling AddLink later, for contexts available during span creation, because head sampling decisions can only consider information present during span creation. The equivalent requirement for attributes was already documented on the attribute setters; only the link methods were missing it. Comments only, no behavior change. Fixes MindfulSoftwareLLC#68 Assisted-by: Claude Opus 5 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Assisted-by: Claude Opus 5 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The added text was one 45-word sentence with gerund verbs and a trailing condition. Split it into three sentences, each under the 25-word limit for descriptive text, with each condition before what it governs. Also replace the circular "[spanContext] the span context for the span" and document the parameters that carried no description. The spec requirement is unchanged: both methods still state that links given at span creation are preferred, and why. Assisted-by: Claude Opus 5 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Split a 34-word sentence with a mid-clause aside into two sentences under the 25-word limit. Assisted-by: Claude Opus 5 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
behavior, not behaviour, matching the OpenTelemetry spec and the rest of this file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E3LcZp1QRqoTrKB6PnaJ1Y
michaelbushe
force-pushed
the
fix/68-addlink-creation-preferred
branch
from
September 13, 2026 17:49
6981579 to
6d85307
Compare
behavior, not behaviour. Last British spelling in the file, and this PR is already touching the section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E3LcZp1QRqoTrKB6PnaJ1Y
michaelbushe
approved these changes
Sep 13, 2026
harshitt13
added a commit
to harshitt13/dartastic_opentelemetry_api
that referenced
this pull request
Sep 13, 2026
Brings in MindfulSoftwareLLC#103, MindfulSoftwareLLC#106, MindfulSoftwareLLC#112, MindfulSoftwareLLC#113, MindfulSoftwareLLC#117, MindfulSoftwareLLC#118, MindfulSoftwareLLC#119, MindfulSoftwareLLC#127, MindfulSoftwareLLC#130, MindfulSoftwareLLC#133 and the MindfulSoftwareLLC#136 CHANGELOG heading conventions. Conflict resolutions: - attribute.dart, attributes.dart (fromJson) and otel_api_factory.dart (attrsFromMap): upstream's pre-AnyValue typed dispatch is superseded by AnyValue.fromObject, which this branch introduces. - attributes.dart _getTyped: kept upstream's MindfulSoftwareLLC#106 contract, where a type mismatch is reported through OTelErrorHandling and returns null rather than throwing, reimplemented over the AnyValue representation. This branch had it throwing StateError, which also contradicted the getter doc comments. - attributes.dart _getTyped: mixed int/double arrays still read back as List<double>, the coercion attrsFromMap and fromJson applied before AnyValue. JSON has a single number type, so [1, 2.5] is routine. The promotion happens in the getter, so the stored AnyValue keeps each element's own type rather than boxing ints into doubles, which would corrupt a heterogeneous log body. An empty array now satisfies any typed list getter, which it otherwise lost on the way through AnyValue. - any_value.dart: DateTime converts with Timestamp.dateTimeToString, as attrsFromMap and Span.setDateTimeAttribute already do, rather than toIso8601String, which widens the fractional part to microseconds whenever the DateTime carries them. This branch never intended to change DateTime formatting. - CHANGELOG.md: took upstream's rc.4-wip section whole and added this branch's entries under Added and Changed, following the headings MindfulSoftwareLLC#136 standardized. Dropped this branch's empty-value Fixed entry, because MindfulSoftwareLLC#103 already landed that fix upstream and documents it. - tests: kept upstream's test names and assertions where they cover the same ground, adapted to the AnyValue representation, and folded in their extra key assertions so no coverage was lost. dart analyze is clean and 1268 tests pass. Signed-off-by: harshitt13 <find.harshitkushwaha@gmail.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #68
Spec requirement
Spec: OpenTelemetry Specification v1.60.0 — Trace API
Requirement level: MUST
Pinned source: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.60.0/specification/trace/api.md#link
The quote was re-verified word for word against the v1.60.0 source. The same sentence appears in both the
Linksection and theAddLinksection.The problem
The doc comments on
APISpan.addLinkandAPISpan.addSpanLinksaid only that a link is added and that the call is ignored once the span has ended. Neither mentioned that links supplied at span creation are preferred.The spec states the equivalent requirement for attributes, and that one was already documented — on the ten typed attribute setters, on the
attributessetter and onaddAttributes. Only the link requirement was unmet.The change
Both link methods now carry the required text, pointing at the
linksparameter ofstartSpan/createSpanso the reader knows what the preferred alternative actually is.Comments only. No behavior change, no API change, no test change.
dart analyzereports no issues forspan.dartand the full suite passes (1199 tests).Assisted-by: Claude Opus 5
🤖 Generated with Claude Code