0
# V1 Client Operations
1

2
Legacy trace operations for basic trace collection, retrieval, and management. The v1 API provides compatibility with older tracing implementations and supports fundamental trace operations with simple data structures.
3

4
## Capabilities
5

6
### Synchronous Client
7

8
The synchronous TraceServiceClient provides comprehensive v1 trace operations for managing traces and spans.
9

10
```python { .api }
11
class TraceServiceClient:
12
    def __init__(
13
        self,
14
        *,
15
        credentials: Optional[Credentials] = None,
16
        transport: Optional[Union[str, TraceServiceTransport, Callable]] = None,
17
        client_options: Optional[Union[ClientOptions, dict]] = None,
18
        client_info: gapic_v1.client_info.ClientInfo = None
19
    ): ...
20

21
    def list_traces(
22
        self,
23
        request: Optional[Union[ListTracesRequest, dict]] = None,
24
        *,
25
        project_id: Optional[str] = None,
26
        view: Optional[ListTracesRequest.ViewType] = None,
27
        page_size: Optional[int] = None,
28
        start_time: Optional[Timestamp] = None,
29
        end_time: Optional[Timestamp] = None,
30
        filter: Optional[str] = None,
31
        order_by: Optional[str] = None,
32
        retry: OptionalRetry = None,
33
        timeout: Union[float, object] = None,
34
        metadata: Sequence[Tuple[str, str]] = ()
35
    ) -> ListTracesPager:
36
        """
37
        Returns a list of traces that match the specified filter conditions.
38

39
        Args:
40
            request: The request object for listing traces
41
            project_id: Required. The project ID where traces are stored
42
            view: Type of data returned for traces (MINIMAL, ROOTSPAN, COMPLETE)
43
            page_size: Maximum number of traces to return
44
            start_time: Start of the time range for traces
45
            end_time: End of the time range for traces
46
            filter: Optional filter expression for traces
47
            order_by: Field used to sort the returned traces
48
            retry: Designation of what errors should be retried
49
            timeout: The timeout for this request
50
            metadata: Strings which should be sent along with the request as metadata
51

52
        Returns:
53
            Paginated list of traces matching the filter conditions
54

55
        Raises:
56
            google.api_core.exceptions.GoogleAPICallError: If the request failed
57
        """
58

59
    def get_trace(
60
        self,
61
        request: Optional[Union[GetTraceRequest, dict]] = None,
62
        *,
63
        project_id: Optional[str] = None,
64
        trace_id: Optional[str] = None,
65
        retry: OptionalRetry = None,
66
        timeout: Union[float, object] = None,
67
        metadata: Sequence[Tuple[str, str]] = ()
68
    ) -> Trace:
69
        """
70
        Gets a single trace by its ID.
71

72
        Args:
73
            request: The request object for getting a trace
74
            project_id: Required. The project ID where the trace is stored
75
            trace_id: Required. The ID of the trace to retrieve
76
            retry: Designation of what errors should be retried
77
            timeout: The timeout for this request
78
            metadata: Strings which should be sent along with the request as metadata
79

80
        Returns:
81
            The requested trace with all its spans
82

83
        Raises:
84
            google.api_core.exceptions.GoogleAPICallError: If the request failed
85
            google.api_core.exceptions.NotFound: If the trace doesn't exist
86
        """
87

88
    def patch_traces(
89
        self,
90
        request: Optional[Union[PatchTracesRequest, dict]] = None,
91
        *,
92
        project_id: Optional[str] = None,
93
        traces: Optional[Traces] = None,
94
        retry: OptionalRetry = None,
95
        timeout: Union[float, object] = None,
96
        metadata: Sequence[Tuple[str, str]] = ()
97
    ) -> None:
98
        """
99
        Sends new traces to Cloud Trace or updates existing traces.
100

101
        Args:
102
            request: The request object containing traces to patch
103
            project_id: Required. The project ID where traces should be written
104
            traces: Required. The body of the patch request containing traces
105
            retry: Designation of what errors should be retried
106
            timeout: The timeout for this request
107
            metadata: Strings which should be sent along with the request as metadata
108

109
        Raises:
110
            google.api_core.exceptions.GoogleAPICallError: If the request failed
111
        """
112

113
    @classmethod
114
    def from_service_account_file(
115
        cls,
116
        filename: str,
117
        *args,
118
        **kwargs
119
    ) -> "TraceServiceClient":
120
        """
121
        Creates a client instance from a service account JSON file.
122

123
        Args:
124
            filename: Path to the service account JSON file
125
            *args: Additional arguments to pass to the client constructor
126
            **kwargs: Additional keyword arguments to pass to the client constructor
127

128
        Returns:
129
            Constructed TraceServiceClient instance
130
        """
131

132
    @classmethod
133
    def from_service_account_info(
134
        cls,
135
        info: Dict[str, Any],
136
        *args,
137
        **kwargs
138
    ) -> "TraceServiceClient":
139
        """
140
        Creates a client instance from service account information.
141

142
        Args:
143
            info: Service account information as a dictionary
144
            *args: Additional arguments to pass to the client constructor
145
            **kwargs: Additional keyword arguments to pass to the client constructor
146

147
        Returns:
148
            Constructed TraceServiceClient instance
149
        """
150

151
    # Alias for from_service_account_file
152
    from_service_account_json = from_service_account_file
153

154
    @property
155
    def transport(self) -> TraceServiceTransport:
156
        """Returns the transport used by the client instance."""
157
    
158
    @property
159
    def api_endpoint(self) -> str:
160
        """Returns the API endpoint used by the client instance."""
161
    
162
    @property
163
    def universe_domain(self) -> str:
164
        """Returns the universe domain used by the client instance."""
165

166
    def __enter__(self) -> "TraceServiceClient":
167
        """Enter the client context."""
168
    
169
    def __exit__(self, type, value, traceback) -> None:
170
        """Exit the client context and clean up resources."""
171
```
172

173
### Asynchronous Client
174

175
The asynchronous TraceServiceAsyncClient provides the same functionality as the synchronous client but with async/await support.
176

177
```python { .api }
178
class TraceServiceAsyncClient:
179
    def __init__(
180
        self,
181
        *,
182
        credentials: Optional[Credentials] = None,
183
        transport: Optional[Union[str, TraceServiceTransport, Callable]] = None,
184
        client_options: Optional[Union[ClientOptions, dict]] = None,
185
        client_info: gapic_v1.client_info.ClientInfo = None
186
    ): ...
187

188
    async def list_traces(
189
        self,
190
        request: Optional[Union[ListTracesRequest, dict]] = None,
191
        *,
192
        project_id: Optional[str] = None,
193
        view: Optional[ListTracesRequest.ViewType] = None,
194
        page_size: Optional[int] = None,
195
        start_time: Optional[Timestamp] = None,
196
        end_time: Optional[Timestamp] = None,
197
        filter: Optional[str] = None,
198
        order_by: Optional[str] = None,
199
        retry: OptionalRetry = None,
200
        timeout: Union[float, object] = None,
201
        metadata: Sequence[Tuple[str, str]] = ()
202
    ) -> ListTracesAsyncPager:
203
        """
204
        Returns a list of traces that match the specified filter conditions (async version).
205

206
        Args:
207
            request: The request object for listing traces
208
            project_id: Required. The project ID where traces are stored
209
            view: Type of data returned for traces (MINIMAL, ROOTSPAN, COMPLETE)
210
            page_size: Maximum number of traces to return
211
            start_time: Start of the time range for traces
212
            end_time: End of the time range for traces
213
            filter: Optional filter expression for traces
214
            order_by: Field used to sort the returned traces
215
            retry: Designation of what errors should be retried
216
            timeout: The timeout for this request
217
            metadata: Strings which should be sent along with the request as metadata
218

219
        Returns:
220
            Paginated async iterator of traces matching the filter conditions
221

222
        Raises:
223
            google.api_core.exceptions.GoogleAPICallError: If the request failed
224
        """
225

226
    async def get_trace(
227
        self,
228
        request: Optional[Union[GetTraceRequest, dict]] = None,
229
        *,
230
        project_id: Optional[str] = None,
231
        trace_id: Optional[str] = None,
232
        retry: OptionalRetry = None,
233
        timeout: Union[float, object] = None,
234
        metadata: Sequence[Tuple[str, str]] = ()
235
    ) -> Trace:
236
        """
237
        Gets a single trace by its ID (async version).
238

239
        Args:
240
            request: The request object for getting a trace
241
            project_id: Required. The project ID where the trace is stored
242
            trace_id: Required. The ID of the trace to retrieve
243
            retry: Designation of what errors should be retried
244
            timeout: The timeout for this request
245
            metadata: Strings which should be sent along with the request as metadata
246

247
        Returns:
248
            The requested trace with all its spans
249

250
        Raises:
251
            google.api_core.exceptions.GoogleAPICallError: If the request failed
252
            google.api_core.exceptions.NotFound: If the trace doesn't exist
253
        """
254

255
    async def patch_traces(
256
        self,
257
        request: Optional[Union[PatchTracesRequest, dict]] = None,
258
        *,
259
        project_id: Optional[str] = None,
260
        traces: Optional[Traces] = None,
261
        retry: OptionalRetry = None,
262
        timeout: Union[float, object] = None,
263
        metadata: Sequence[Tuple[str, str]] = ()
264
    ) -> None:
265
        """
266
        Sends new traces to Cloud Trace or updates existing traces (async version).
267

268
        Args:
269
            request: The request object containing traces to patch
270
            project_id: Required. The project ID where traces should be written
271
            traces: Required. The body of the patch request containing traces
272
            retry: Designation of what errors should be retried
273
            timeout: The timeout for this request
274
            metadata: Strings which should be sent along with the request as metadata
275

276
        Raises:
277
            google.api_core.exceptions.GoogleAPICallError: If the request failed
278
        """
279

280
    @classmethod
281
    def from_service_account_file(
282
        cls,
283
        filename: str,
284
        *args,
285
        **kwargs
286
    ) -> "TraceServiceAsyncClient":
287
        """
288
        Creates an async client instance from a service account JSON file.
289

290
        Args:
291
            filename: Path to the service account JSON file
292
            *args: Additional arguments to pass to the client constructor
293
            **kwargs: Additional keyword arguments to pass to the client constructor
294

295
        Returns:
296
            Constructed TraceServiceAsyncClient instance
297
        """
298

299
    @classmethod
300
    def from_service_account_info(
301
        cls,
302
        info: Dict[str, Any],
303
        *args,
304
        **kwargs
305
    ) -> "TraceServiceAsyncClient":
306
        """
307
        Creates an async client instance from service account information.
308

309
        Args:
310
            info: Service account information as a dictionary
311
            *args: Additional arguments to pass to the client constructor
312
            **kwargs: Additional keyword arguments to pass to the client constructor
313

314
        Returns:
315
            Constructed TraceServiceAsyncClient instance
316
        """
317

318
    # Alias for from_service_account_file
319
    from_service_account_json = from_service_account_file
320

321
    @property
322
    def transport(self) -> TraceServiceTransport:
323
        """Returns the transport used by the client instance."""
324
    
325
    @property
326
    def api_endpoint(self) -> str:
327
        """Returns the API endpoint used by the client instance."""
328
    
329
    @property
330
    def universe_domain(self) -> str:
331
        """Returns the universe domain used by the client instance."""
332

333
    async def __aenter__(self) -> "TraceServiceAsyncClient":
334
        """Enter the async client context."""
335
    
336
    async def __aexit__(self, type, value, traceback) -> None:
337
        """Exit the async client context and clean up resources."""
338
```
339

340
## Usage Examples
341

342
### Listing Traces
343

344
```python
345
from google.cloud import trace_v1
346

347
# Initialize client
348
client = trace_v1.TraceServiceClient()
349

350
# List traces for a project
351
request = trace_v1.ListTracesRequest(
352
    project_id="my-project",
353
    view=trace_v1.ListTracesRequest.ViewType.COMPLETE,
354
    start_time={"seconds": 1609459200},
355
    end_time={"seconds": 1609462800},
356
    page_size=100
357
)
358

359
# Get traces
360
traces_pager = client.list_traces(request=request)
361

362
# Iterate through traces
363
for trace in traces_pager:
364
    print(f"Trace ID: {trace.trace_id}")
365
    print(f"Project: {trace.project_id}")
366
    print(f"Number of spans: {len(trace.spans)}")
367
```
368

369
### Getting a Single Trace
370

371
```python
372
from google.cloud import trace_v1
373

374
# Initialize client
375
client = trace_v1.TraceServiceClient()
376

377
# Get a specific trace
378
trace = client.get_trace(
379
    project_id="my-project",
380
    trace_id="abc123def456"
381
)
382

383
print(f"Trace ID: {trace.trace_id}")
384
for span in trace.spans:
385
    print(f"Span: {span.name} ({span.span_id})")
386
```
387

388
### Creating/Updating Traces
389

390
```python
391
from google.cloud import trace_v1
392

393
# Initialize client
394
client = trace_v1.TraceServiceClient()
395

396
# Create trace span
397
span = trace_v1.TraceSpan(
398
    span_id=12345,
399
    kind=trace_v1.TraceSpan.SpanKind.RPC_SERVER,
400
    name="my-operation",
401
    start_time={"seconds": 1609459200, "nanos": 500000000},
402
    end_time={"seconds": 1609459201, "nanos": 750000000},
403
    labels={
404
        "component": "database",
405
        "operation": "query"
406
    }
407
)
408

409
# Create trace
410
trace = trace_v1.Trace(
411
    project_id="my-project",
412
    trace_id="abc123def456",
413
    spans=[span]
414
)
415

416
# Send traces to Cloud Trace
417
traces = trace_v1.Traces(traces=[trace])
418
client.patch_traces(
419
    project_id="my-project",
420
    traces=traces
421
)
422
```
423

424
### Async Operations
425

426
```python
427
import asyncio
428
from google.cloud import trace_v1
429

430
async def list_traces_async():
431
    # Initialize async client
432
    client = trace_v1.TraceServiceAsyncClient()
433
    
434
    # List traces asynchronously
435
    request = trace_v1.ListTracesRequest(
436
        project_id="my-project",
437
        view=trace_v1.ListTracesRequest.ViewType.MINIMAL,
438
        page_size=50
439
    )
440
    
441
    traces_pager = await client.list_traces(request=request)
442
    
443
    # Iterate through traces
444
    async for trace in traces_pager:
445
        print(f"Trace ID: {trace.trace_id}")
446

447
# Run async operation
448
asyncio.run(list_traces_async())
449
```