Skip to content

Commit 0c53f8d

Browse files
liyanhui1228liyanhui1228
authored
Add Trace V2 client and _gax (googleapis#4437)
1 parent 0dbccac commit 0c53f8d

11 files changed

Lines changed: 1338 additions & 298 deletions

File tree

‎trace/google/cloud/trace/__init__.py‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,24 @@
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
1414

15+
from __future__ import absolute_import
16+
1517
from google.cloud.trace.client import Client
18+
from google.cloud.trace_v2 import types
19+
from google.cloud.trace_v2.gapic import enums
20+
from google.cloud.trace_v2.gapic import trace_service_client
21+
1622

23+
class TraceServiceClient(trace_service_client.TraceServiceClient):
24+
__doc__ = trace_service_client.TraceServiceClient.__doc__
25+
enums = enums
1726

18-
__all__ = ['Client', 'SCOPE']
1927

28+
__all__ = (
29+
'enums',
30+
'types',
31+
'TraceServiceClient',
32+
'Client',
33+
'SCOPE',)
2034

2135
SCOPE = Client.SCOPE

‎trace/google/cloud/trace/_gax.py‎

Lines changed: 262 additions & 147 deletions
Large diffs are not rendered by default.

‎trace/google/cloud/trace/client.py‎

Lines changed: 181 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -16,21 +16,19 @@
1616

1717
from google.cloud.trace._gax import make_gax_trace_api
1818
from google.cloud.client import ClientWithProject
19-
from google.cloud._helpers import _datetime_to_pb_timestamp
2019

2120

2221
class Client(ClientWithProject):
23-
"""Client to bundle configuration needed for API requests.
24-
25-
:type project: str
26-
:param project: The project which the client acts on behalf of.
27-
If not passed, falls back to the default inferred from
28-
the environment.
29-
30-
:type credentials: :class:`~google.auth.credentials.Credentials`
31-
:param credentials: (Optional) The OAuth2 Credentials to use for this
32-
client. If not passed, falls back to the default
33-
inferred from the environment.
22+
"""
23+
Client to bundle configuration needed for API requests.
24+
25+
Args:
26+
project (str): The project which the client acts on behalf of.
27+
If not passed, falls back to the default inferred from
28+
the environment.
29+
credentials (Optional[:class:`~google.auth.credentials.Credentials`]):
30+
The OAuth2 Credentials to use for this client. If not passed,
31+
falls back to the default inferred from the environment.
3432
"""
3533
SCOPE = ('https://www.googleapis.com/auth/cloud-platform',
3634
'https://www.googleapis.com/auth/trace.append',)
@@ -44,128 +42,185 @@ def __init__(self, project=None, credentials=None):
4442

4543
@property
4644
def trace_api(self):
47-
"""Helper for trace-related API calls.
45+
"""
46+
Helper for trace-related API calls.
4847
4948
See
50-
https://cloud.google.com/trace/docs/reference/v1/rpc/google.devtools.
51-
cloudtrace.v1
49+
https://cloud.google.com/trace/docs/reference/v2/rpc/google.devtools.
50+
cloudtrace.v2
5251
"""
5352
self._trace_api = make_gax_trace_api(self)
5453
return self._trace_api
5554

56-
def patch_traces(self, traces, project_id=None, options=None):
57-
"""Sends new traces to Stackdriver Trace or updates existing traces.
58-
59-
:type traces: dict
60-
:param traces: The traces to be patched in the API call.
61-
62-
:type project_id: str
63-
:param project_id: (Optional) ID of the Cloud project where the trace
64-
data is stored.
65-
66-
:type options: :class:`~google.gax.CallOptions`
67-
:param options: (Optional) Overrides the default settings for this
68-
call, e.g, timeout, retries etc.
55+
def batch_write_spans(self,
56+
name,
57+
spans,
58+
retry=None,
59+
timeout=None):
6960
"""
70-
if project_id is None:
71-
project_id = self.project
72-
73-
self.trace_api.patch_traces(
74-
project_id=project_id,
75-
traces=traces,
76-
options=options)
77-
78-
def get_trace(self, trace_id, project_id=None, options=None):
79-
"""Gets a single trace by its ID.
80-
81-
:type project_id: str
82-
:param project_id: ID of the Cloud project where the trace data is
83-
stored.
84-
85-
:type trace_id: str
86-
:param trace_id: ID of the trace to return.
87-
88-
:type options: :class:`~google.gax.CallOptions`
89-
:param options: (Optional) Overrides the default settings for this
90-
call, e.g, timeout, retries etc.
91-
92-
:rtype: dict
93-
:returns: A Trace dict.
61+
Sends new spans to Stackdriver Trace or updates existing traces. If the
62+
name of a trace that you send matches that of an existing trace, new
63+
spans are added to the existing trace. Attempt to update existing spans
64+
results undefined behavior. If the name does not match, a new trace is
65+
created with given set of spans.
66+
67+
Example:
68+
>>> from google.cloud import trace_v2
69+
>>>
70+
>>> client = trace_v2.Client()
71+
>>>
72+
>>> name = 'projects/[PROJECT_ID]'
73+
>>> spans = {'spans': [{'endTime': '2017-11-21T23:50:58.890768Z',
74+
'spanId': [SPAN_ID],
75+
'startTime': '2017-11-21T23:50:58.890763Z',
76+
'name': 'projects/[PROJECT_ID]/traces/
77+
[TRACE_ID]/spans/[SPAN_ID]',
78+
'displayName': {'value': 'sample span'}}]}
79+
>>>
80+
>>> client.batch_write_spans(name, spans)
81+
82+
Args:
83+
name (str): Optional. Name of the project where the spans belong.
84+
The format is ``projects/PROJECT_ID``.
85+
spans (dict): A collection of spans.
86+
retry (Optional[google.api_core.retry.Retry]): A retry object used
87+
to retry requests. If ``None`` is specified, requests will not
88+
be retried.
89+
timeout (Optional[float]): The amount of time, in seconds, to wait
90+
for the request to complete. Note that if ``retry`` is
91+
specified, the timeout applies to each individual attempt.
92+
93+
Raises:
94+
google.api_core.exceptions.GoogleAPICallError: If the request
95+
failed for any reason.
96+
google.api_core.exceptions.RetryError: If the request failed due
97+
to a retryable error and retry attempts failed.
98+
ValueError: If the parameters are invalid.
9499
"""
95-
if project_id is None:
96-
project_id = self.project
97-
98-
return self.trace_api.get_trace(
99-
project_id=project_id,
100-
trace_id=trace_id,
101-
options=options)
102-
103-
def list_traces(
104-
self,
105-
project_id=None,
106-
view=None,
107-
page_size=None,
108-
start_time=None,
109-
end_time=None,
110-
filter_=None,
111-
order_by=None,
112-
page_token=None):
113-
"""Returns of a list of traces that match the filter conditions.
114-
115-
:type project_id: str
116-
:param project_id: (Optional) ID of the Cloud project where the trace
117-
data is stored.
118-
119-
:type view: :class:`google.cloud.trace_v1.gapic.enums.
120-
ListTracesRequest.ViewType`
121-
:param view: (Optional) Type of data returned for traces in the list.
122-
Default is ``MINIMAL``.
123-
124-
:type page_size: int
125-
:param page_size: (Optional) Maximum number of traces to return.
126-
If not specified or <= 0, the implementation selects
127-
a reasonable value. The implementation may return
128-
fewer traces than the requested page size.
129-
130-
:type start_time: :class:`~datetime.datetime`
131-
:param start_time: (Optional) Start of the time interval (inclusive)
132-
during which the trace data was collected from the
133-
application.
134-
135-
:type end_time: :class:`~datetime.datetime`
136-
:param end_time: (Optional) End of the time interval (inclusive) during
137-
which the trace data was collected from the
138-
application.
139-
140-
:type filter_: str
141-
:param filter_: (Optional) An optional filter for the request.
142-
143-
:type order_by: str
144-
:param order_by: (Optional) Field used to sort the returned traces.
145-
146-
:type page_token: str
147-
:param page_token: opaque marker for the next "page" of entries. If not
148-
passed, the API will return the first page of
149-
entries.
150-
151-
:rtype: :class:`~google.api_core.page_iterator.Iterator`
152-
:returns: Traces that match the specified filter conditions.
100+
self.trace_api.batch_write_spans(
101+
name=name,
102+
spans=spans,
103+
retry=retry,
104+
timeout=timeout)
105+
106+
def create_span(self,
107+
name,
108+
span_id,
109+
display_name,
110+
start_time,
111+
end_time,
112+
parent_span_id=None,
113+
attributes=None,
114+
stack_trace=None,
115+
time_events=None,
116+
links=None,
117+
status=None,
118+
same_process_as_parent_span=None,
119+
child_span_count=None,
120+
retry=None,
121+
timeout=None):
153122
"""
154-
if project_id is None:
155-
project_id = self.project
156-
157-
if start_time is not None:
158-
start_time = _datetime_to_pb_timestamp(start_time)
159-
160-
if end_time is not None:
161-
end_time = _datetime_to_pb_timestamp(end_time)
162-
163-
return self.trace_api.list_traces(
164-
project_id=project_id,
165-
view=view,
166-
page_size=page_size,
123+
Creates a new Span.
124+
125+
Example:
126+
>>> from google.cloud import trace_v2
127+
>>>
128+
>>> client = trace_v2.Client()
129+
>>>
130+
>>> name = 'projects/{project}/traces/{trace_id}/spans/{span_id}'.
131+
format('[PROJECT]', '[TRACE_ID]', '[SPAN_ID]')
132+
>>> span_id = '[SPAN_ID]'
133+
>>> display_name = {}
134+
>>> start_time = {}
135+
>>> end_time = {}
136+
>>>
137+
>>> response = client.create_span(name, span_id, display_name,
138+
start_time, end_time)
139+
140+
Args:
141+
name (str): The resource name of the span in the following format:
142+
143+
::
144+
145+
projects/[PROJECT_ID]/traces/[TRACE_ID]/spans/[SPAN_ID]
146+
147+
[TRACE_ID] is a unique identifier for a trace within a project.
148+
[SPAN_ID] is a unique identifier for a span within a trace,
149+
assigned when the span is created.
150+
span_id (str): The [SPAN_ID] portion of the span's resource name.
151+
The ID is a 16-character hexadecimal encoding of an 8-byte
152+
array.
153+
display_name (dict): A description of the span's operation
154+
(up to 128 bytes). Stackdriver Trace displays the description
155+
in the {% dynamic print site_values.console_name %}.
156+
For example, the display name can be a qualified method name
157+
or a file name and a line number where the operation is called.
158+
A best practice is to use the same display name within an
159+
application and at the same call point. This makes it easier to
160+
correlate spans in different traces.
161+
Contains two fields, value is the truncated name,
162+
truncatedByteCount is the number of bytes removed from the
163+
original string. If 0, then the string was not shortened.
164+
start_time (:class:`~datetime.datetime`):
165+
The start time of the span. On the client side, this is the
166+
time kept by the local machine where the span execution starts.
167+
On the server side, this is the time when the server's
168+
application handler starts running.
169+
end_time (:class:`~datetime.datetime`):
170+
The end time of the span. On the client side, this is the time
171+
kept by the local machine where the span execution ends. On the
172+
server side, this is the time when the server application
173+
handler stops running.
174+
parent_span_id (str): The [SPAN_ID] of this span's parent span.
175+
If this is a root span, then this field must be empty.
176+
attributes (dict): A set of attributes on the span. There is a
177+
limit of 32 attributes per span.
178+
stack_trace (dict):
179+
Stack trace captured at the start of the span.
180+
Contains two fields, stackFrames is a list of stack frames in
181+
this call stack, a maximum of 128 frames are allowed per
182+
StackFrame; stackTraceHashId is used to conserve network
183+
bandwidth for duplicate stack traces within a single trace.
184+
time_events (dict):
185+
The included time events. There can be up to 32 annotations
186+
and 128 message events per span.
187+
links (dict): A maximum of 128 links are allowed per Span.
188+
status (dict): An optional final status for this span.
189+
same_process_as_parent_span (bool): A highly recommended but not
190+
required flag that identifies when a trace crosses a process
191+
boundary. True when the parent_span belongs to the same process
192+
as the current span.
193+
child_span_count (int): An optional number of child spans that were
194+
generated while this span was active. If set, allows
195+
implementation to detect missing child spans.
196+
retry (Optional[google.api_core.retry.Retry]): A retry object used
197+
to retry requests. If ``None`` is specified, requests will not
198+
be retried.
199+
timeout (Optional[float]): The amount of time, in seconds, to wait
200+
for the request to complete. Note that if ``retry`` is
201+
specified, the timeout applies to each individual attempt.
202+
203+
Returns:
204+
A :class:`~google.cloud.trace_v2.types.Span` instance.
205+
206+
Raises:
207+
google.api_core.exceptions.GoogleAPICallError: If the request
208+
failed for any reason.
209+
google.api_core.exceptions.RetryError: If the request failed due
210+
to a retryable error and retry attempts failed.
211+
ValueError: If the parameters are invalid.
212+
"""
213+
return self.trace_api.create_span(
214+
name=name,
215+
span_id=span_id,
216+
display_name=display_name,
167217
start_time=start_time,
168218
end_time=end_time,
169-
filter_=filter_,
170-
order_by=order_by,
171-
page_token=page_token)
219+
parent_span_id=parent_span_id,
220+
attributes=attributes,
221+
stack_trace=stack_trace,
222+
time_events=time_events,
223+
links=links,
224+
status=status,
225+
same_process_as_parent_span=same_process_as_parent_span,
226+
child_span_count=child_span_count)

‎trace/google/cloud/trace/v1/__init__.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Copyright 2017 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from google.cloud.trace.v1.client import Client
16+
17+
18+
__all__ = ['Client', 'SCOPE']
19+
20+
21+
SCOPE = Client.SCOPE

0 commit comments

Comments
 (0)