0
# V2 Data Types
1

2
Rich data structures for enhanced tracing with attributes, time events, stack traces, and structured metadata. The v2 API provides comprehensive data types that support detailed tracing information and flexible span representation.
3

4
## Core Data Types
5

6
### Span
7

8
Enhanced span representation with rich metadata, supporting complex tracing scenarios with detailed attributes, time events, and relationships.
9

10
```python { .api }
11
class Span:
12
    name: str  # Resource name: "projects/{project}/traces/{trace}/spans/{span}"
13
    span_id: str  # Unique identifier for this span within a trace
14
    parent_span_id: str  # ID of the parent span, if any
15
    display_name: TruncatableString  # Human-readable name for this span
16
    start_time: Timestamp  # Start time of the span
17
    end_time: Timestamp  # End time of the span
18
    attributes: Span.Attributes  # Set of attributes for this span
19
    stack_trace: StackTrace  # Stack trace captured during span execution
20
    time_events: Span.TimeEvents  # Time-stamped events during span execution
21
    links: Span.Links  # Links to other spans
22
    status: Status  # Optional status for this span
23
    same_process_as_parent_span: BoolValue  # True if span and parent in same process
24
    child_span_count: Int32Value  # Number of child spans generated
25
    span_kind: SpanKind  # Type of span (INTERNAL, SERVER, CLIENT, etc.)
26

27
    class Attributes:
28
        attribute_map: Dict[str, AttributeValue]  # Map of attributes
29
        dropped_attributes_count: int  # Number of dropped attributes
30

31
    class TimeEvent:
32
        time: Timestamp  # Time when event occurred
33
        annotation: Annotation  # Text annotation with optional attributes
34
        message_event: MessageEvent  # Network message event
35

36
        class Annotation:
37
            description: TruncatableString  # Description of the annotation
38
            attributes: Attributes  # Set of attributes for this annotation
39

40
        class MessageEvent:
41
            type: Type  # Type of message (SENT, RECEIVED)
42
            id: int  # Identifier for this message
43
            uncompressed_size_bytes: int  # Uncompressed size in bytes
44
            compressed_size_bytes: int  # Compressed size in bytes
45

46
            class Type(Enum):
47
                TYPE_UNSPECIFIED = 0
48
                SENT = 1
49
                RECEIVED = 2
50

51
    class TimeEvents:
52
        time_event: List[TimeEvent]  # Collection of time events
53
        dropped_annotations_count: int  # Number of dropped annotations
54
        dropped_message_events_count: int  # Number of dropped message events
55

56
    class Link:
57
        trace_id: str  # Trace ID for linked span
58
        span_id: str  # Span ID for linked span
59
        type: Type  # Relationship type
60
        attributes: Attributes  # Link attributes
61

62
        class Type(Enum):
63
            TYPE_UNSPECIFIED = 0
64
            CHILD_LINKED_SPAN = 1
65
            PARENT_LINKED_SPAN = 2
66

67
    class Links:
68
        link: List[Link]  # Collection of links
69
        dropped_links_count: int  # Number of dropped links
70

71
class SpanKind(Enum):
72
    SPAN_KIND_UNSPECIFIED = 0  # Unspecified span kind
73
    INTERNAL = 1  # Internal operation within application
74
    SERVER = 2  # Synchronous RPC server span
75
    CLIENT = 3  # Synchronous RPC client span
76
    PRODUCER = 4  # Asynchronous producer span
77
    CONSUMER = 5  # Asynchronous consumer span
78
```
79

80
### AttributeValue
81

82
Union type for span attribute values, supporting string, integer, and boolean types with proper type safety.
83

84
```python { .api }
85
class AttributeValue:
86
    string_value: TruncatableString  # String attribute value (oneof)
87
    int_value: int  # Integer attribute value (oneof)
88
    bool_value: bool  # Boolean attribute value (oneof)
89
```
90

91
### TruncatableString
92

93
String representation with truncation metadata, allowing for efficient storage and transmission of potentially large string values.
94

95
```python { .api }
96
class TruncatableString:
97
    value: str  # The truncated or untruncated original string
98
    truncated_byte_count: int  # Number of bytes removed from original string
99
```
100

101
### StackTrace
102

103
Call stack information with detailed frame data, enabling precise debugging and performance analysis.
104

105
```python { .api }
106
class StackTrace:
107
    stack_frames: StackFrames  # Stack frames in this stack trace
108
    stack_trace_hash_id: int  # Hash ID used to conserve network bandwidth
109

110
    class StackFrame:
111
        function_name: TruncatableString  # Name of the function
112
        original_function_name: TruncatableString  # Unmangled function name
113
        file_name: TruncatableString  # Name of the source file
114
        line_number: int  # Line number in the source file
115
        column_number: int  # Column number in the source file
116
        load_module: Module  # Binary module this frame belongs to
117
        source_version: TruncatableString  # Source code version identifier
118

119
    class StackFrames:
120
        frame: List[StackFrame]  # Stack frames in this call stack
121
        dropped_frames_count: int  # Number of stack frames dropped
122
```
123

124
### Module
125

126
Binary module identification for stack trace frames, providing detailed information about loaded modules.
127

128
```python { .api }
129
class Module:
130
    module: TruncatableString  # Binary module name (e.g., main.binary)
131
    build_id: TruncatableString  # Unique identifier for the module
132
```
133

134
## Request Types
135

136
### BatchWriteSpansRequest
137

138
Request message for batch span writing operations, enabling efficient transmission of multiple spans.
139

140
```python { .api }
141
class BatchWriteSpansRequest:
142
    name: str  # Required. Resource name of the project: "projects/{project}"
143
    spans: List[Span]  # Required. Collection of spans to write
144
```
145

146
## Common Types
147

148
### Status
149

150
Standard RPC status representation for span completion status.
151

152
```python { .api }
153
class Status:
154
    code: int  # Status code (0 = OK)
155
    message: str  # Developer-facing error message
156
    details: List[Any]  # Additional error details
157
```
158

159
### Timestamp
160

161
Represents a point in time, independent of any time zone or calendar.
162

163
```python { .api }
164
class Timestamp:
165
    seconds: int  # Seconds since Unix epoch
166
    nanos: int  # Non-negative fractions of a second at nanosecond resolution
167
```
168

169
## Usage Examples
170

171
### Creating a Basic Span
172

173
```python
174
from google.cloud import trace_v2
175

176
# Create a basic span
177
span = trace_v2.Span(
178
    name="projects/my-project/traces/trace-123/spans/span-456",
179
    span_id="span-456",
180
    display_name=trace_v2.TruncatableString(value="database-query"),
181
    start_time={"seconds": 1609459200, "nanos": 500000000},
182
    end_time={"seconds": 1609459201, "nanos": 750000000},
183
    span_kind=trace_v2.Span.SpanKind.INTERNAL
184
)
185
```
186

187
### Creating a Span with Attributes
188

189
```python
190
from google.cloud import trace_v2
191

192
# Create span with attributes
193
attributes = trace_v2.Span.Attributes(
194
    attribute_map={
195
        "database.name": trace_v2.AttributeValue(
196
            string_value=trace_v2.TruncatableString(value="users")
197
        ),
198
        "database.rows_affected": trace_v2.AttributeValue(int_value=42),
199
        "database.cached": trace_v2.AttributeValue(bool_value=True)
200
    }
201
)
202

203
span = trace_v2.Span(
204
    name="projects/my-project/traces/trace-123/spans/db-span",
205
    span_id="db-span",
206
    display_name=trace_v2.TruncatableString(value="SELECT users"),
207
    start_time={"seconds": 1609459200},
208
    end_time={"seconds": 1609459201},
209
    attributes=attributes,
210
    span_kind=trace_v2.Span.SpanKind.INTERNAL
211
)
212
```
213

214
### Creating a Span with Time Events
215

216
```python
217
from google.cloud import trace_v2
218

219
# Create annotation
220
annotation = trace_v2.Span.TimeEvent.Annotation(
221
    description=trace_v2.TruncatableString(value="Cache miss occurred"),
222
    attributes=trace_v2.Span.Attributes(
223
        attribute_map={
224
            "cache.key": trace_v2.AttributeValue(
225
                string_value=trace_v2.TruncatableString(value="user:123")
226
            )
227
        }
228
    )
229
)
230

231
# Create time event
232
time_event = trace_v2.Span.TimeEvent(
233
    time={"seconds": 1609459200, "nanos": 750000000},
234
    annotation=annotation
235
)
236

237
# Create span with time events
238
time_events = trace_v2.Span.TimeEvents(
239
    time_event=[time_event],
240
    dropped_annotations_count=0
241
)
242

243
span = trace_v2.Span(
244
    name="projects/my-project/traces/trace-123/spans/annotated-span",
245
    span_id="annotated-span",
246
    display_name=trace_v2.TruncatableString(value="cache-operation"),
247
    start_time={"seconds": 1609459200},
248
    end_time={"seconds": 1609459201},
249
    time_events=time_events,
250
    span_kind=trace_v2.Span.SpanKind.INTERNAL
251
)
252
```
253

254
### Creating a Span with Links
255

256
```python
257
from google.cloud import trace_v2
258

259
# Create link to another span
260
link = trace_v2.Span.Link(
261
    trace_id="other-trace-id",
262
    span_id="other-span-id",
263
    type=trace_v2.Span.Link.Type.CHILD_LINKED_SPAN,
264
    attributes=trace_v2.Span.Attributes(
265
        attribute_map={
266
            "link.reason": trace_v2.AttributeValue(
267
                string_value=trace_v2.TruncatableString(value="async-operation")
268
            )
269
        }
270
    )
271
)
272

273
# Create span with links
274
links = trace_v2.Span.Links(
275
    link=[link],
276
    dropped_links_count=0
277
)
278

279
span = trace_v2.Span(
280
    name="projects/my-project/traces/trace-123/spans/linked-span",
281
    span_id="linked-span",
282
    display_name=trace_v2.TruncatableString(value="linked-operation"),
283
    start_time={"seconds": 1609459200},
284
    end_time={"seconds": 1609459201},
285
    links=links,
286
    span_kind=trace_v2.Span.SpanKind.CLIENT
287
)
288
```