Skip to content

Commit beb8bb9

Browse files
committed
Add docs for trace_call and trace_call_end_lazily
1 parent 8db062a commit beb8bb9

File tree

3 files changed

+25
-13
lines changed

3 files changed

+25
-13
lines changed

google/cloud/spanner_v1/_opentelemetry_tracing.py

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,8 @@ def get_tracer(tracer_provider=None):
5454
return tracer_provider.get_tracer(TRACER_NAME, TRACER_VERSION)
5555

5656

57-
def _prepare_span_attributes(
58-
name, session=None, extra_attributes=None, observability_options=None
57+
def _make_tracer_and_span_attributes(
58+
session=None, extra_attributes=None, observability_options=None
5959
):
6060
if not HAS_OPENTELEMETRY_INSTALLED:
6161
return None, None
@@ -104,8 +104,13 @@ def _prepare_span_attributes(
104104

105105
@contextmanager
106106
def trace_call(name, session=None, extra_attributes=None, observability_options=None):
107-
tracer, span_attributes = _prepare_span_attributes(
108-
name, session, extra_attributes, observability_options
107+
"""
108+
trace_call is used in situations where you need to end a span with a context manager
109+
or after a scope is exited. If you need to keep a span alive and lazily end it, please
110+
invoke `trace_call_end_lazily`.
111+
"""
112+
tracer, span_attributes = _make_tracer_and_span_attributes(
113+
session, extra_attributes, observability_options
109114
)
110115
if not tracer:
111116
yield None
@@ -124,10 +129,17 @@ def trace_call(name, session=None, extra_attributes=None, observability_options=
124129
span.set_status(Status(StatusCode.OK))
125130

126131

127-
def trace_end_explicitly(
132+
def trace_call_end_lazily(
128133
name, session=None, extra_attributes=None, observability_options=None
129134
):
130-
tracer, span_attributes = _prepare_span_attributes(
135+
"""
136+
trace_call_end_lazily is used in situations where you won't have a context manager
137+
and need to end a span explicitly when a specific condition happens. If you need a
138+
context manager, please invoke `trace_call` with which you can invoke
139+
`with trace_call(...) as span:`
140+
It is the caller's responsibility to explicitly invoke span.end()
141+
"""
142+
tracer, span_attributes = _make_tracer_and_span_attributes(
131143
session, extra_attributes, observability_options
132144
)
133145
if not tracer:

google/cloud/spanner_v1/batch.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
)
2929
from google.cloud.spanner_v1._opentelemetry_tracing import (
3030
trace_call,
31-
trace_end_explicitly,
31+
trace_call_end_lazily,
3232
)
3333
from google.cloud.spanner_v1 import RequestOptions
3434
from google.cloud.spanner_v1._helpers import _retry
@@ -52,7 +52,7 @@ def __init__(self, session):
5252
observability_options = getattr(
5353
self._session._database, "observability_options", None
5454
)
55-
self.__span = trace_end_explicitly(
55+
self.__span = trace_call_end_lazily(
5656
"CloudSpanner." + type(self).__name__,
5757
self._session,
5858
observability_options=observability_options,
@@ -263,7 +263,7 @@ def __enter__(self):
263263
observability_options = getattr(
264264
self._session._database, "observability_options", None
265265
)
266-
self.__span = trace_end_explicitly(
266+
self.__span = trace_call_end_lazily(
267267
"CloudSpanner.Batch",
268268
self._session,
269269
observability_options=observability_options,

google/cloud/spanner_v1/database.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
)
5656
from google.cloud.spanner_v1._opentelemetry_tracing import (
5757
trace_call,
58-
trace_end_explicitly,
58+
trace_call_end_lazily,
5959
)
6060
from google.cloud.spanner_v1.batch import Batch
6161
from google.cloud.spanner_v1.batch import MutationGroups
@@ -1195,7 +1195,7 @@ def __init__(
11951195
def __enter__(self):
11961196
"""Begin ``with`` block."""
11971197
observability_options = self._database.observability_options
1198-
self.__span = trace_end_explicitly(
1198+
self.__span = trace_call_end_lazily(
11991199
"CloudSpanner.Database.batch",
12001200
None,
12011201
observability_options=observability_options,
@@ -1291,7 +1291,7 @@ def __enter__(self):
12911291
attributes = dict()
12921292
if self._kw:
12931293
attributes["multi_use"] = self._kw["multi_use"]
1294-
self.__span = trace_end_explicitly(
1294+
self.__span = trace_call_end_lazily(
12951295
"CloudSpanner.Database.snapshot",
12961296
None,
12971297
attributes,
@@ -1346,7 +1346,7 @@ def __init__(
13461346
self._exact_staleness = exact_staleness
13471347
observability_options = getattr(self._database, "observability_options", {})
13481348
self.__observability_options = observability_options
1349-
self.__span = trace_end_explicitly(
1349+
self.__span = trace_call_end_lazily(
13501350
"CloudSpanner.BatchSnapshot",
13511351
self._session,
13521352
observability_options=observability_options,

0 commit comments

Comments
 (0)