0
# Google Cloud Trace
1
2
A comprehensive Python client library for Google Cloud Trace, a distributed tracing system that collects latency data from applications and displays it in the Google Cloud Platform Console. It enables developers to track how requests propagate through their applications and receive detailed near real-time performance insights.
3
4
## Package Information
5
6
- **Package Name**: google-cloud-trace
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-trace`
9
- **Python Requirements**: >= 3.7
10
11
## Core Imports
12
13
```python
14
from google.cloud import trace
15
```
16
17
For explicit API version usage:
18
19
```python
20
from google.cloud import trace_v1, trace_v2
21
```
22
23
Individual component imports:
24
25
```python
26
from google.cloud.trace import TraceServiceClient, TraceServiceAsyncClient
27
from google.cloud.trace_v2 import Span, AttributeValue, BatchWriteSpansRequest
28
from google.cloud.trace_v1 import Trace, TraceSpan
29
```
30
31
## Basic Usage
32
33
```python
34
from google.cloud.trace import TraceServiceClient
35
from google.cloud.trace_v2.types import Span, TruncatableString
36
37
# Initialize client (defaults to v2 API)
38
client = TraceServiceClient()
39
40
# Create a span (v2 API)
41
span = Span(
42
name="projects/my-project/traces/my-trace-id/spans/my-span-id",
43
span_id="my-span-id",
44
display_name=TruncatableString(value="my-operation"),
45
start_time={"seconds": 1609459200},
46
end_time={"seconds": 1609459201}
47
)
48
49
# Write the span
50
client.create_span(request=span)
51
52
# Batch write multiple spans
53
spans = [span] # List of spans
54
client.batch_write_spans(
55
name="projects/my-project",
56
spans=spans
57
)
58
```
59
60
## Architecture
61
62
Google Cloud Trace provides two API versions with distinct capabilities:
63
64
- **V1 API**: Legacy tracing with basic trace and span operations, focused on trace collection and retrieval
65
- **V2 API**: Enhanced tracing with rich span metadata, attributes, time events, and performance optimizations
66
67
Both APIs support synchronous and asynchronous clients, providing flexibility for different application architectures. The library follows Google Cloud client library conventions with consistent parameter patterns, retry mechanisms, and authentication handling.
68
69
## Capabilities
70
71
### V2 Client Operations
72
73
Enhanced tracing operations with rich span metadata, batch processing, and performance optimizations. The v2 API is recommended for new applications.
74
75
```python { .api }
76
class TraceServiceClient:
77
def batch_write_spans(self, request=None, *, name=None, spans=None, **kwargs) -> None: ...
78
def create_span(self, request=None, **kwargs) -> Span: ...
79
80
class TraceServiceAsyncClient:
81
async def batch_write_spans(self, request=None, *, name=None, spans=None, **kwargs) -> None: ...
82
async def create_span(self, request=None, **kwargs) -> Span: ...
83
```
84
85
[V2 Client Operations](./v2-client.md)
86
87
### V1 Client Operations
88
89
Legacy trace operations for basic trace collection, retrieval, and management. Provides compatibility with older tracing implementations.
90
91
```python { .api }
92
class TraceServiceClient:
93
def list_traces(self, request=None, *, project_id=None, **kwargs) -> ListTracesPager: ...
94
def get_trace(self, request=None, *, project_id=None, trace_id=None, **kwargs) -> Trace: ...
95
def patch_traces(self, request=None, *, project_id=None, traces=None, **kwargs) -> None: ...
96
97
class TraceServiceAsyncClient:
98
async def list_traces(self, request=None, *, project_id=None, **kwargs) -> ListTracesAsyncPager: ...
99
async def get_trace(self, request=None, *, project_id=None, trace_id=None, **kwargs) -> Trace: ...
100
async def patch_traces(self, request=None, *, project_id=None, traces=None, **kwargs) -> None: ...
101
```
102
103
[V1 Client Operations](./v1-client.md)
104
105
### V2 Data Types
106
107
Rich data structures for enhanced tracing with attributes, time events, stack traces, and structured metadata.
108
109
```python { .api }
110
class Span:
111
name: str
112
span_id: str
113
display_name: TruncatableString
114
start_time: Timestamp
115
end_time: Timestamp
116
attributes: Span.Attributes
117
# ... additional fields
118
119
class AttributeValue:
120
string_value: TruncatableString # oneof
121
int_value: int # oneof
122
bool_value: bool # oneof
123
124
class TruncatableString:
125
value: str
126
truncated_byte_count: int
127
```
128
129
[V2 Data Types](./v2-data-types.md)
130
131
### V1 Data Types
132
133
Basic data structures for legacy trace operations with simple trace and span representations.
134
135
```python { .api }
136
class Trace:
137
project_id: str
138
trace_id: str
139
spans: List[TraceSpan]
140
141
class TraceSpan:
142
span_id: int
143
kind: SpanKind
144
name: str
145
start_time: Timestamp
146
end_time: Timestamp
147
parent_span_id: int
148
labels: Dict[str, str]
149
```
150
151
[V1 Data Types](./v1-data-types.md)
152
153
### Authentication & Configuration
154
155
Client authentication, configuration options, and resource path management utilities.
156
157
```python { .api }
158
class TraceServiceClient:
159
@classmethod
160
def from_service_account_file(cls, filename, *args, **kwargs): ...
161
@classmethod
162
def from_service_account_info(cls, info, *args, **kwargs): ...
163
164
@staticmethod
165
def common_project_path(project: str) -> str: ...
166
@staticmethod
167
def span_path(project: str, trace: str, span: str) -> str: ...
168
```
169
170
[Authentication & Configuration](./auth-config.md)