tessl/pypi-google-cloud-trace
Google Cloud Trace API client library for distributed tracing and performance analysis
—
Pending
v2-client.mddocs/
V2 Client Operations
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.
Capabilities
Synchronous Client
The synchronous TraceServiceClient provides comprehensive v2 trace operations with rich span metadata and batch processing capabilities.
class TraceServiceClient:
def __init__(
self,
*,
credentials: Optional[Credentials] = None,
transport: Optional[Union[str, TraceServiceTransport, Callable]] = None,
client_options: Optional[Union[ClientOptions, dict]] = None,
client_info: gapic_v1.client_info.ClientInfo = None
): ...
def batch_write_spans(
self,
request: Optional[Union[BatchWriteSpansRequest, dict]] = None,
*,
name: Optional[str] = None,
spans: Optional[Sequence[Span]] = None,
retry: OptionalRetry = None,
timeout: Union[float, object] = None,
metadata: Sequence[Tuple[str, str]] = ()
) -> None:
"""
Sends new spans to new or existing traces.
Args:
request: The request object containing spans to write
name: Required. The resource name of the project where spans belong
spans: Required. A list of new spans to write
retry: Designation of what errors should be retried
timeout: The timeout for this request
metadata: Strings which should be sent along with the request as metadata
Raises:
google.api_core.exceptions.GoogleAPICallError: If the request failed
"""
def create_span(
self,
request: Optional[Union[Span, dict]] = None,
*,
retry: OptionalRetry = None,
timeout: Union[float, object] = None,
metadata: Sequence[Tuple[str, str]] = ()
) -> Span:
"""
Creates a new span.
Args:
request: The request object - the span to create
retry: Designation of what errors should be retried
timeout: The timeout for this request
metadata: Strings which should be sent along with the request as metadata
Returns:
The created span
Raises:
google.api_core.exceptions.GoogleAPICallError: If the request failed
"""Asynchronous Client
The asynchronous TraceServiceAsyncClient provides the same functionality as the synchronous client but with async/await support for concurrent operations.
class TraceServiceAsyncClient:
def __init__(
self,
*,
credentials: Optional[Credentials] = None,
transport: Optional[Union[str, TraceServiceTransport, Callable]] = None,
client_options: Optional[Union[ClientOptions, dict]] = None,
client_info: gapic_v1.client_info.ClientInfo = None
): ...
async def batch_write_spans(
self,
request: Optional[Union[BatchWriteSpansRequest, dict]] = None,
*,
name: Optional[str] = None,
spans: Optional[Sequence[Span]] = None,
retry: OptionalRetry = None,
timeout: Union[float, object] = None,
metadata: Sequence[Tuple[str, str]] = ()
) -> None:
"""
Sends new spans to new or existing traces (async version).
Args:
request: The request object containing spans to write
name: Required. The resource name of the project where spans belong
spans: Required. A list of new spans to write
retry: Designation of what errors should be retried
timeout: The timeout for this request
metadata: Strings which should be sent along with the request as metadata
Raises:
google.api_core.exceptions.GoogleAPICallError: If the request failed
"""
async def create_span(
self,
request: Optional[Union[Span, dict]] = None,
*,
retry: OptionalRetry = None,
timeout: Union[float, object] = None,
metadata: Sequence[Tuple[str, str]] = ()
) -> Span:
"""
Creates a new span (async version).
Args:
request: The request object - the span to create
retry: Designation of what errors should be retried
timeout: The timeout for this request
metadata: Strings which should be sent along with the request as metadata
Returns:
The created span
Raises:
google.api_core.exceptions.GoogleAPICallError: If the request failed
"""Usage Examples
Basic Span Creation
from google.cloud import trace_v2
# Initialize client
client = trace_v2.TraceServiceClient()
# Create a span
span = trace_v2.Span(
name="projects/my-project/traces/trace-123/spans/span-456",
span_id="span-456",
display_name=trace_v2.TruncatableString(value="database-query"),
start_time={"seconds": 1609459200, "nanos": 500000000},
end_time={"seconds": 1609459201, "nanos": 750000000},
span_kind=trace_v2.Span.SpanKind.INTERNAL
)
# Create the span
created_span = client.create_span(request=span)Batch Span Writing
from google.cloud import trace_v2
# Initialize client
client = trace_v2.TraceServiceClient()
# Create multiple spans
spans = [
trace_v2.Span(
name="projects/my-project/traces/trace-123/spans/span-1",
span_id="span-1",
display_name=trace_v2.TruncatableString(value="operation-1"),
start_time={"seconds": 1609459200},
end_time={"seconds": 1609459201}
),
trace_v2.Span(
name="projects/my-project/traces/trace-123/spans/span-2",
span_id="span-2",
display_name=trace_v2.TruncatableString(value="operation-2"),
start_time={"seconds": 1609459201},
end_time={"seconds": 1609459202}
)
]
# Batch write spans
client.batch_write_spans(
name="projects/my-project",
spans=spans
)Async Operations
import asyncio
from google.cloud import trace_v2
async def create_spans_async():
# Initialize async client
client = trace_v2.TraceServiceAsyncClient()
# Create span
span = trace_v2.Span(
name="projects/my-project/traces/trace-123/spans/async-span",
span_id="async-span",
display_name=trace_v2.TruncatableString(value="async-operation"),
start_time={"seconds": 1609459200},
end_time={"seconds": 1609459201}
)
# Create span asynchronously
created_span = await client.create_span(request=span)
# Batch write spans asynchronously
spans = [span]
await client.batch_write_spans(
name="projects/my-project",
spans=spans
)
# Run async operations
asyncio.run(create_spans_async())Install with Tessl CLI
npx tessl i tessl/pypi-google-cloud-trace