Span: add attribute, event, link setter to the API #83

alban · 2019-08-12T11:40:30Z

Basic tests that exercise the API are added as well. However it does not
actually test that the attributes, events and links are written properly
because there is no getter. Those tests can be added later when the
attributes are actually used.

The spec mentions additional APIs for lazy initialization (AddLazyEvent,
AddLazyLink). Those are not added in this patch because OT-Python does
not expose the Event type (currently defined in the SDK only).

#75 (attribute)
#76 (event)
#77 (link)

a-feld · 2019-08-12T19:02:53Z

opentelemetry-api/src/opentelemetry/trace/__init__.py

@@ -65,6 +65,8 @@
 import typing

 from opentelemetry import loader
+from opentelemetry import trace as trace_api


This import can be removed and the trace_api.SpanContext below can be replaced with 'SpanContext'! 😄

Thanks! I'm fixing this...

carlosalberto · 2019-08-12T21:56:56Z

It all looks good, in addition to what was commented by @a-feld mentioned

Also, the tickets were originally created to track the API + the SDK changes, so that's remaining ;) (Can be done in future PRs)

reyang · 2019-08-13T00:42:51Z

opentelemetry-sdk/tests/trace/test_trace.py

+
+            root.add_event('event1', 'event1-detail')
+
+            root.add_link(other_neighbor, 'neighbor')


add_link requires a SpanContext, do we intend to revisit this later?

I am not sure to follow: on this line, the other_neighbor argument is a SpanContext, created above:

other_neighbor = trace_api.SpanContext( trace_id=0x0000000000000000000000000000cafe, span_id=0x00000000cafe1234 )

Sorry I thought it was a string. You're right.

I guess the correct invocation should be something like this? root.add_link(other_neighbor, {'name': 'neighbor'})
I also wonder if the API should treat attributes as optional? root.add_link(my_span_context)

I also wonder if the API should treat attributes as optional?

Oh actually it should (same with add_event())

Related question: should we add Link/Event classes or keep with this minimalistic approach? cc @c24t

This PR seems like a great place to add Link/Event.

@reyang points out that we could use a singleton default empty attribute map here (like @carlosalberto's CURRENT_SPAN to avoid creating a bunch of empty attributes.

reyang

LGTM, I've put one question in the comments.

opentelemetry-sdk/tests/trace/test_trace.py

alban · 2019-08-13T12:28:08Z

Also, the tickets were originally created to track the API + the SDK changes, so that's remaining ;) (Can be done in future PRs)

Should I remove the "Fixes #XXX" in the PR description then?

Basic tests that exercise the API are added as well. However it does not actually test that the attributes, events and links are written properly because there is no getter. Those tests can be added later when the attributes are actually used. The spec mentions additional APIs for lazy initialization (AddLazyEvent, AddLazyLink). Those are not added in this patch because OT-Python does not expose the Event type (currently defined in the SDK only).

carlosalberto · 2019-08-13T16:54:21Z

@alban Yes, please ;) A simple mention to them should be fine (we can close later on the issues when the actual SDK portions are done)

c24t

Minor comments, but this looks great. Thanks!

c24t · 2019-08-13T19:14:01Z

opentelemetry-api/src/opentelemetry/trace/__init__.py

+                  name: str,
+                  attributes: 'types.Attributes',
+                  ) -> None:
+        """Adds an Event.


One open question is whether the caller ever needs access to the events or links they create (in which case we need the classes in the API) or if we should treat them as part of the implementation of these methods.

I think it's best to start out with the API that exposes as few details as possible.

There are two places where I've seen Event/Link and related members being publicly used/exposed : 1) SpanData (but as that is probable going to the SDK at the very least) and 2) MessageEvent (which extends Event, at least in Java: https://github.com/open-telemetry/opentelemetry-java/blob/master/contrib/trace_utils/src/main/java/io/opentelemetry/contrib/trace/MessageEvent.java).

Makes me feel we should include these Event, etc classes here.

opentelemetry-api/src/opentelemetry/trace/__init__.py

c24t · 2019-08-13T19:18:18Z

opentelemetry-api/src/opentelemetry/trace/__init__.py

+                  ) -> None:
+        """Adds an Event.
+
+        Adds a single Event with the name and, optionally, attributes passed


Suggested change

Adds a single Event with the name and, optionally, attributes passed

Adds a single `Event` with the name and, optionally, attributes passed

Do we have an explicit Event class? If not, then that suggestion would break the doc build.

At the moment, we don't. We have the following

Event = namedtuple('Event', ('name', 'attributes'))

But that's in the SDK, not exposed in the API.

c24t · 2019-08-13T19:18:55Z

opentelemetry-api/src/opentelemetry/trace/__init__.py

+                 ) -> None:
+        """Adds a Link to another Span.
+
+        Adds a single Link to the Span via the SpanContext passed as argument.


Suggested change

Adds a single Link to the Span via the SpanContext passed as argument.

Adds a single `Link` to the `Span` via the `SpanContext` passed as argument.

"the Span" should be "the span" (following your rationale #83 (comment))

Co-Authored-By: Chris Kleinknecht <[email protected]>

Even though the public API does not expose getters, we can access the span members directly in Python.

Symptoms: ``` /home/travis/build/kinvolk/opentelemetry-python/opentelemetry-api/src/opentelemetry/trace/__init__.py:docstring of opentelemetry.trace.Span.set_attribute:3: WARNING: 'any' reference target not found: Attribute 298/home/travis/build/kinvolk/opentelemetry-python/opentelemetry-api/src/opentelemetry/trace/__init__.py:docstring of opentelemetry.trace.Span.add_link:3: WARNING: 'any' reference target not found: Link 299 ```

alban · 2019-08-14T12:51:14Z

I updated the PR:

tests: use a dict in add_link and add_event instead of a string by mistake
make argument optional in add_link and add_event. I reused Span.empty_attributes in the implementation but didn't expose Link/Event in the API
API docstring: changes in spelling "span" following Chris' suggestion. But I didn't take Attribute and Link to avoid CI error
tests: we don't have getters but I added tests accessing the span members directly

opentelemetry-api/src/opentelemetry/trace/__init__.py

Oberon00 · 2019-08-14T12:56:40Z

opentelemetry-api/src/opentelemetry/trace/__init__.py

+                  name: str,
+                  attributes: 'types.Attributes',
+                  ) -> None:
+        """Adds an Event.


I think it's best to start out with the API that exposes as few details as possible.

Oberon00 · 2019-08-14T12:57:45Z

opentelemetry-api/src/opentelemetry/trace/__init__.py

+                  ) -> None:
+        """Adds an Event.
+
+        Adds a single Event with the name and, optionally, attributes passed


Do we have an explicit Event class? If not, then that suggestion would break the doc build.

opentelemetry-api/src/opentelemetry/trace/__init__.py

Oberon00 · 2019-08-14T13:09:59Z

opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py

                  ) -> None:
        if self.events is Span.empty_events:
            self.events = BoundedList(MAX_NUM_EVENTS)
+        if attributes is None:
+            attributes = Span.empty_attributes


It somewhat irks me that we can't use Span.empty_attributes as default and leave out this check, because the API already specifies a default argument of None. But I know of no better way to write this than the one you used here.

I initially tried to use {} as default value but the CI complained with:

Dangerous default value {} as argument

and I read recommendations to use None in that case.

Co-Authored-By: Christian Neumüller <[email protected]>

Symptoms: ``` opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py:249:4: W0221: Parameters differ from overridden 'add_link' method (arguments-differ) ```

alban · 2019-08-14T14:23:22Z

Thanks for the additional review. I updated the PR again:

use your phrasing in the docstring
rename argument to link_target_context
avoid types in quotes when possible (types.Attributes)
update ASK to follow changes in API

alban requested review from c24t, carlosalberto, Oberon00 and reyang as code owners August 12, 2019 11:40

a-feld reviewed Aug 12, 2019

View reviewed changes

carlosalberto approved these changes Aug 12, 2019

View reviewed changes

reyang reviewed Aug 13, 2019

View reviewed changes

reyang approved these changes Aug 13, 2019

View reviewed changes

toumorokoshi reviewed Aug 13, 2019

View reviewed changes

opentelemetry-sdk/tests/trace/test_trace.py Outdated Show resolved Hide resolved

alban force-pushed the alban/attribute branch from 76027e0 to 8f4f3ee Compare August 13, 2019 13:37

c24t approved these changes Aug 13, 2019

View reviewed changes

a-feld mentioned this pull request Aug 13, 2019

Implement WSGI middleware integration. #84

Merged

alban and others added 6 commits August 14, 2019 12:23

Update opentelemetry-api/src/opentelemetry/trace/__init__.py

a923472

Co-Authored-By: Chris Kleinknecht <[email protected]>

Update opentelemetry-api/src/opentelemetry/trace/__init__.py

ee756c8

Co-Authored-By: Chris Kleinknecht <[email protected]>

Update opentelemetry-api/src/opentelemetry/trace/__init__.py

19a6985

Update tests

fd5f45e

Even though the public API does not expose getters, we can access the span members directly in Python.

Link & Event: make attributes optional as per the spec

4c40110

Oberon00 reviewed Aug 14, 2019

View reviewed changes

alban and others added 6 commits August 14, 2019 15:51

Update opentelemetry-api/src/opentelemetry/trace/__init__.py

5aec9fa

Co-Authored-By: Christian Neumüller <[email protected]>

Update opentelemetry-api/src/opentelemetry/trace/__init__.py

cf6f4c4

Co-Authored-By: Christian Neumüller <[email protected]>

Update opentelemetry-api/src/opentelemetry/trace/__init__.py

02f258d

Co-Authored-By: Christian Neumüller <[email protected]>

Update opentelemetry-api/src/opentelemetry/trace/__init__.py

950f5aa

Co-Authored-By: Christian Neumüller <[email protected]>

Span: line wrap

ca6a36f

sdk/trace: use methods with same prototype as api

f2a4674

Symptoms: ``` opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py:249:4: W0221: Parameters differ from overridden 'add_link' method (arguments-differ) ```

reyang merged commit b7b38a5 into open-telemetry:master Aug 15, 2019


		root.add_event('event1', 'event1-detail')

		root.add_link(other_neighbor, 'neighbor')

	Adds a single Event with the name and, optionally, attributes passed
	Adds a single `Event` with the name and, optionally, attributes passed

	Adds a single Link to the Span via the SpanContext passed as argument.
	Adds a single `Link` to the `Span` via the `SpanContext` passed as argument.

Span: add attribute, event, link setter to the API #83

Span: add attribute, event, link setter to the API #83

Uh oh!

Conversation

alban commented Aug 12, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carlosalberto commented Aug 12, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reyang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alban commented Aug 13, 2019

Uh oh!

carlosalberto commented Aug 13, 2019

Uh oh!

c24t left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alban commented Aug 14, 2019

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alban commented Aug 14, 2019

Uh oh!

Uh oh!

alban commented Aug 12, 2019 •

edited

Loading