0
# V2 Client Operations
1

2
Enhanced tracing operations with rich span metadata, batch processing, and performance optimizations. The v2 API is the recommended choice for new applications, providing comprehensive tracing capabilities with structured data and advanced features.
3

4
## Capabilities
5

6
### Synchronous Client
7

8
The synchronous TraceServiceClient provides comprehensive v2 trace operations with rich span metadata and batch processing capabilities.
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 batch_write_spans(
22
        self,
23
        request: Optional[Union[BatchWriteSpansRequest, dict]] = None,
24
        *,
25
        name: Optional[str] = None,
26
        spans: Optional[Sequence[Span]] = None,
27
        retry: OptionalRetry = None,
28
        timeout: Union[float, object] = None,
29
        metadata: Sequence[Tuple[str, str]] = ()
30
    ) -> None:
31
        """
32
        Sends new spans to new or existing traces.
33

34
        Args:
35
            request: The request object containing spans to write
36
            name: Required. The resource name of the project where spans belong
37
            spans: Required. A list of new spans to write
38
            retry: Designation of what errors should be retried
39
            timeout: The timeout for this request
40
            metadata: Strings which should be sent along with the request as metadata
41

42
        Raises:
43
            google.api_core.exceptions.GoogleAPICallError: If the request failed
44
        """
45

46
    def create_span(
47
        self,
48
        request: Optional[Union[Span, dict]] = None,
49
        *,
50
        retry: OptionalRetry = None,
51
        timeout: Union[float, object] = None,
52
        metadata: Sequence[Tuple[str, str]] = ()
53
    ) -> Span:
54
        """
55
        Creates a new span.
56

57
        Args:
58
            request: The request object - the span to create
59
            retry: Designation of what errors should be retried
60
            timeout: The timeout for this request
61
            metadata: Strings which should be sent along with the request as metadata
62

63
        Returns:
64
            The created span
65

66
        Raises:
67
            google.api_core.exceptions.GoogleAPICallError: If the request failed
68
        """
69
```
70

71
### Asynchronous Client
72

73
The asynchronous TraceServiceAsyncClient provides the same functionality as the synchronous client but with async/await support for concurrent operations.
74

75
```python { .api }
76
class TraceServiceAsyncClient:
77
    def __init__(
78
        self,
79
        *,
80
        credentials: Optional[Credentials] = None,
81
        transport: Optional[Union[str, TraceServiceTransport, Callable]] = None,
82
        client_options: Optional[Union[ClientOptions, dict]] = None,
83
        client_info: gapic_v1.client_info.ClientInfo = None
84
    ): ...
85

86
    async def batch_write_spans(
87
        self,
88
        request: Optional[Union[BatchWriteSpansRequest, dict]] = None,
89
        *,
90
        name: Optional[str] = None,
91
        spans: Optional[Sequence[Span]] = None,
92
        retry: OptionalRetry = None,
93
        timeout: Union[float, object] = None,
94
        metadata: Sequence[Tuple[str, str]] = ()
95
    ) -> None:
96
        """
97
        Sends new spans to new or existing traces (async version).
98

99
        Args:
100
            request: The request object containing spans to write
101
            name: Required. The resource name of the project where spans belong
102
            spans: Required. A list of new spans to write
103
            retry: Designation of what errors should be retried
104
            timeout: The timeout for this request
105
            metadata: Strings which should be sent along with the request as metadata
106

107
        Raises:
108
            google.api_core.exceptions.GoogleAPICallError: If the request failed
109
        """
110

111
    async def create_span(
112
        self,
113
        request: Optional[Union[Span, dict]] = None,
114
        *,
115
        retry: OptionalRetry = None,
116
        timeout: Union[float, object] = None,
117
        metadata: Sequence[Tuple[str, str]] = ()
118
    ) -> Span:
119
        """
120
        Creates a new span (async version).
121

122
        Args:
123
            request: The request object - the span to create
124
            retry: Designation of what errors should be retried
125
            timeout: The timeout for this request
126
            metadata: Strings which should be sent along with the request as metadata
127

128
        Returns:
129
            The created span
130

131
        Raises:
132
            google.api_core.exceptions.GoogleAPICallError: If the request failed
133
        """
134
```
135

136
## Usage Examples
137

138
### Basic Span Creation
139

140
```python
141
from google.cloud import trace_v2
142

143
# Initialize client
144
client = trace_v2.TraceServiceClient()
145

146
# Create a span
147
span = trace_v2.Span(
148
    name="projects/my-project/traces/trace-123/spans/span-456",
149
    span_id="span-456",
150
    display_name=trace_v2.TruncatableString(value="database-query"),
151
    start_time={"seconds": 1609459200, "nanos": 500000000},
152
    end_time={"seconds": 1609459201, "nanos": 750000000},
153
    span_kind=trace_v2.Span.SpanKind.INTERNAL
154
)
155

156
# Create the span
157
created_span = client.create_span(request=span)
158
```
159

160
### Batch Span Writing
161

162
```python
163
from google.cloud import trace_v2
164

165
# Initialize client
166
client = trace_v2.TraceServiceClient()
167

168
# Create multiple spans
169
spans = [
170
    trace_v2.Span(
171
        name="projects/my-project/traces/trace-123/spans/span-1",
172
        span_id="span-1",
173
        display_name=trace_v2.TruncatableString(value="operation-1"),
174
        start_time={"seconds": 1609459200},
175
        end_time={"seconds": 1609459201}
176
    ),
177
    trace_v2.Span(
178
        name="projects/my-project/traces/trace-123/spans/span-2",
179
        span_id="span-2",
180
        display_name=trace_v2.TruncatableString(value="operation-2"),
181
        start_time={"seconds": 1609459201},
182
        end_time={"seconds": 1609459202}
183
    )
184
]
185

186
# Batch write spans
187
client.batch_write_spans(
188
    name="projects/my-project",
189
    spans=spans
190
)
191
```
192

193
### Async Operations
194

195
```python
196
import asyncio
197
from google.cloud import trace_v2
198

199
async def create_spans_async():
200
    # Initialize async client
201
    client = trace_v2.TraceServiceAsyncClient()
202
    
203
    # Create span
204
    span = trace_v2.Span(
205
        name="projects/my-project/traces/trace-123/spans/async-span",
206
        span_id="async-span",
207
        display_name=trace_v2.TruncatableString(value="async-operation"),
208
        start_time={"seconds": 1609459200},
209
        end_time={"seconds": 1609459201}
210
    )
211
    
212
    # Create span asynchronously
213
    created_span = await client.create_span(request=span)
214
    
215
    # Batch write spans asynchronously
216
    spans = [span]
217
    await client.batch_write_spans(
218
        name="projects/my-project",
219
        spans=spans
220
    )
221

222
# Run async operations
223
asyncio.run(create_spans_async())
224
```