0
# V1 Data Types
1

2
Basic data structures for legacy trace operations with simple trace and span representations. The v1 API provides fundamental data types for basic tracing functionality and compatibility with older systems.
3

4
## Core Data Types
5

6
### Trace
7

8
Complete trace information including project ID, trace ID, and collection of spans representing the execution path.
9

10
```python { .api }
11
class Trace:
12
    project_id: str  # Project ID for this trace
13
    trace_id: str  # Globally unique identifier for this trace  
14
    spans: List[TraceSpan]  # Collection of spans that comprise this trace
15
```
16

17
### TraceSpan
18

19
Single timed event within a trace, representing an operation with start/end times and metadata.
20

21
```python { .api }
22
class TraceSpan:
23
    span_id: int  # Identifier for this span, unique within a trace
24
    kind: SpanKind  # Type of span (unspecified, RPC server, RPC client)
25
    name: str  # Name of the span (description of the operation)
26
    start_time: Timestamp  # Start time of the span's execution
27
    end_time: Timestamp  # End time of the span's execution  
28
    parent_span_id: int  # ID of the parent span (0 if root span)
29
    labels: Dict[str, str]  # Collection of labels associated with this span
30

31
class SpanKind(Enum):
32
    SPAN_KIND_UNSPECIFIED = 0  # Unspecified span kind
33
    RPC_SERVER = 1  # Indicates server-side handling of RPC or other remote request
34
    RPC_CLIENT = 2  # Indicates client-side call to RPC or other remote request
35
```
36

37
### Traces
38

39
Collection wrapper for multiple traces, used for batch operations.
40

41
```python { .api }
42
class Traces:
43
    traces: List[Trace]  # Collection of traces
44
```
45

46
## Request/Response Types
47

48
### ListTracesRequest
49

50
Request message for listing traces with filtering and pagination options.
51

52
```python { .api }
53
class ListTracesRequest:
54
    project_id: str  # Required. ID of the project containing traces
55
    view: ViewType  # Type of data to return for each trace
56
    page_size: int  # Maximum number of traces to return
57
    page_token: str  # Token identifying specific page of results
58
    start_time: Timestamp  # Start of the time range (inclusive)
59
    end_time: Timestamp  # End of the time range (exclusive) 
60
    filter: str  # Optional filter expression
61
    order_by: str  # Field used to sort the returned traces
62

63
    class ViewType(Enum):
64
        VIEW_TYPE_UNSPECIFIED = 0  # Default view type
65
        MINIMAL = 1  # Minimal view with basic trace information
66
        ROOTSPAN = 2  # Root span view containing root span only
67
        COMPLETE = 3  # Complete view with all spans and details
68
```
69

70
### ListTracesResponse
71

72
Response message containing paginated list of traces.
73

74
```python { .api }
75
class ListTracesResponse:
76
    traces: List[Trace]  # List of traces matching the request
77
    next_page_token: str  # Token for retrieving the next page of results
78
```
79

80
### GetTraceRequest
81

82
Request message for retrieving a single trace by ID.
83

84
```python { .api }
85
class GetTraceRequest:
86
    project_id: str  # Required. ID of the project containing the trace
87
    trace_id: str  # Required. ID of the trace to retrieve
88
```
89

90
### PatchTracesRequest
91

92
Request message for sending new traces or updating existing ones.
93

94
```python { .api }
95
class PatchTracesRequest:
96
    project_id: str  # Required. ID of the project receiving traces
97
    traces: Traces  # Required. Collection of traces to be patched
98
```
99

100
## Common Types
101

102
### Timestamp
103

104
Represents a point in time, independent of any time zone or calendar.
105

106
```python { .api }
107
class Timestamp:
108
    seconds: int  # Seconds since Unix epoch (January 1, 1970 UTC)
109
    nanos: int  # Non-negative fractions of a second at nanosecond resolution
110
```
111

112
## Usage Examples
113

114
### Creating a Basic Trace
115

116
```python
117
from google.cloud import trace_v1
118

119
# Create a simple span
120
span = trace_v1.TraceSpan(
121
    span_id=12345,
122
    kind=trace_v1.TraceSpan.SpanKind.RPC_SERVER,
123
    name="handle-request",
124
    start_time={"seconds": 1609459200, "nanos": 0},
125
    end_time={"seconds": 1609459201, "nanos": 500000000},
126
    parent_span_id=0,  # Root span
127
    labels={
128
        "http.method": "GET",
129
        "http.url": "/api/users",
130
        "http.status_code": "200"
131
    }
132
)
133

134
# Create trace containing the span
135
trace = trace_v1.Trace(
136
    project_id="my-project",
137
    trace_id="abc123def456ghi789",
138
    spans=[span]
139
)
140
```
141

142
### Creating a Multi-Span Trace
143

144
```python
145
from google.cloud import trace_v1
146

147
# Create root span
148
root_span = trace_v1.TraceSpan(
149
    span_id=1,
150
    kind=trace_v1.TraceSpan.SpanKind.RPC_SERVER,
151
    name="handle-user-request",
152
    start_time={"seconds": 1609459200, "nanos": 0},
153
    end_time={"seconds": 1609459203, "nanos": 0},
154
    parent_span_id=0,
155
    labels={
156
        "component": "api-server",
157
        "operation": "get-user"
158
    }
159
)
160

161
# Create child span for database operation
162
db_span = trace_v1.TraceSpan(
163
    span_id=2,
164
    kind=trace_v1.TraceSpan.SpanKind.RPC_CLIENT,
165
    name="database-query",
166
    start_time={"seconds": 1609459201, "nanos": 0},
167
    end_time={"seconds": 1609459202, "nanos": 500000000},
168
    parent_span_id=1,  # Child of root span
169
    labels={
170
        "db.type": "postgresql",
171
        "db.statement": "SELECT * FROM users WHERE id = ?",
172
        "db.instance": "users-db"
173
    }
174
)
175

176
# Create child span for cache operation
177
cache_span = trace_v1.TraceSpan(
178
    span_id=3,
179
    kind=trace_v1.TraceSpan.SpanKind.RPC_CLIENT,
180
    name="cache-lookup",
181
    start_time={"seconds": 1609459200, "nanos": 500000000},
182
    end_time={"seconds": 1609459200, "nanos": 750000000},
183
    parent_span_id=1,  # Child of root span
184
    labels={
185
        "cache.type": "redis",
186
        "cache.key": "user:123",
187
        "cache.hit": "false"
188
    }
189
)
190

191
# Create trace with all spans
192
trace = trace_v1.Trace(
193
    project_id="my-project",
194
    trace_id="multi-span-trace-id",
195
    spans=[root_span, db_span, cache_span]
196
)
197
```
198

199
### Creating Request Objects
200

201
```python
202
from google.cloud import trace_v1
203

204
# Create list traces request
205
list_request = trace_v1.ListTracesRequest(
206
    project_id="my-project",
207
    view=trace_v1.ListTracesRequest.ViewType.COMPLETE,
208
    page_size=50,
209
    start_time={"seconds": 1609459200},
210
    end_time={"seconds": 1609462800},
211
    filter='span:"database-query"',
212
    order_by="start_time desc"
213
)
214

215
# Create get trace request  
216
get_request = trace_v1.GetTraceRequest(
217
    project_id="my-project",
218
    trace_id="abc123def456ghi789"
219
)
220

221
# Create patch traces request
222
traces_collection = trace_v1.Traces(traces=[trace])
223
patch_request = trace_v1.PatchTracesRequest(
224
    project_id="my-project",
225
    traces=traces_collection
226
)
227
```
228

229
### Working with Timestamps
230

231
```python
232
import time
233
from google.cloud import trace_v1
234

235
# Create timestamp from current time
236
current_time = time.time()
237
timestamp = {
238
    "seconds": int(current_time),
239
    "nanos": int((current_time % 1) * 1e9)
240
}
241

242
# Create span with precise timing
243
span = trace_v1.TraceSpan(
244
    span_id=1,
245
    kind=trace_v1.TraceSpan.SpanKind.RPC_SERVER,
246
    name="timed-operation",
247
    start_time=timestamp,
248
    end_time={
249
        "seconds": timestamp["seconds"] + 1,
250
        "nanos": timestamp["nanos"] + 500000000
251
    },
252
    parent_span_id=0,
253
    labels={"timing": "precise"}
254
)
255
```