or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

auth-config.mdindex.mdv1-client.mdv1-data-types.mdv2-client.mdv2-data-types.md
tile.json

tessl/pypi-google-cloud-trace

Google Cloud Trace API client library for distributed tracing and performance analysis

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/google-cloud-trace@1.16.x

To install, run

npx @tessl/cli install tessl/pypi-google-cloud-trace@1.16.0

index.mddocs/

Google Cloud Trace

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.

Package Information

  • Package Name: google-cloud-trace
  • Language: Python
  • Installation: pip install google-cloud-trace
  • Python Requirements: >= 3.7

Core Imports

from google.cloud import trace

For explicit API version usage:

from google.cloud import trace_v1, trace_v2

Individual component imports:

from google.cloud.trace import TraceServiceClient, TraceServiceAsyncClient
from google.cloud.trace_v2 import Span, AttributeValue, BatchWriteSpansRequest
from google.cloud.trace_v1 import Trace, TraceSpan

Basic Usage

from google.cloud.trace import TraceServiceClient
from google.cloud.trace_v2.types import Span, TruncatableString

# Initialize client (defaults to v2 API)
client = TraceServiceClient()

# Create a span (v2 API)
span = Span(
    name="projects/my-project/traces/my-trace-id/spans/my-span-id",
    span_id="my-span-id",
    display_name=TruncatableString(value="my-operation"),
    start_time={"seconds": 1609459200},
    end_time={"seconds": 1609459201}
)

# Write the span
client.create_span(request=span)

# Batch write multiple spans
spans = [span]  # List of spans
client.batch_write_spans(
    name="projects/my-project",
    spans=spans
)

Architecture

Google Cloud Trace provides two API versions with distinct capabilities:

  • V1 API: Legacy tracing with basic trace and span operations, focused on trace collection and retrieval
  • V2 API: Enhanced tracing with rich span metadata, attributes, time events, and performance optimizations

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.

Capabilities

V2 Client Operations

Enhanced tracing operations with rich span metadata, batch processing, and performance optimizations. The v2 API is recommended for new applications.

class TraceServiceClient:
    def batch_write_spans(self, request=None, *, name=None, spans=None, **kwargs) -> None: ...
    def create_span(self, request=None, **kwargs) -> Span: ...

class TraceServiceAsyncClient:
    async def batch_write_spans(self, request=None, *, name=None, spans=None, **kwargs) -> None: ...
    async def create_span(self, request=None, **kwargs) -> Span: ...

V2 Client Operations

V1 Client Operations

Legacy trace operations for basic trace collection, retrieval, and management. Provides compatibility with older tracing implementations.

class TraceServiceClient:
    def list_traces(self, request=None, *, project_id=None, **kwargs) -> ListTracesPager: ...
    def get_trace(self, request=None, *, project_id=None, trace_id=None, **kwargs) -> Trace: ...
    def patch_traces(self, request=None, *, project_id=None, traces=None, **kwargs) -> None: ...

class TraceServiceAsyncClient:
    async def list_traces(self, request=None, *, project_id=None, **kwargs) -> ListTracesAsyncPager: ...
    async def get_trace(self, request=None, *, project_id=None, trace_id=None, **kwargs) -> Trace: ...
    async def patch_traces(self, request=None, *, project_id=None, traces=None, **kwargs) -> None: ...

V1 Client Operations

V2 Data Types

Rich data structures for enhanced tracing with attributes, time events, stack traces, and structured metadata.

class Span:
    name: str
    span_id: str
    display_name: TruncatableString
    start_time: Timestamp
    end_time: Timestamp
    attributes: Span.Attributes
    # ... additional fields

class AttributeValue:
    string_value: TruncatableString  # oneof
    int_value: int  # oneof
    bool_value: bool  # oneof

class TruncatableString:
    value: str
    truncated_byte_count: int

V2 Data Types

V1 Data Types

Basic data structures for legacy trace operations with simple trace and span representations.

class Trace:
    project_id: str
    trace_id: str
    spans: List[TraceSpan]

class TraceSpan:
    span_id: int
    kind: SpanKind
    name: str
    start_time: Timestamp
    end_time: Timestamp
    parent_span_id: int
    labels: Dict[str, str]

V1 Data Types

Authentication & Configuration

Client authentication, configuration options, and resource path management utilities.

class TraceServiceClient:
    @classmethod
    def from_service_account_file(cls, filename, *args, **kwargs): ...
    @classmethod
    def from_service_account_info(cls, info, *args, **kwargs): ...
    
    @staticmethod
    def common_project_path(project: str) -> str: ...
    @staticmethod  
    def span_path(project: str, trace: str, span: str) -> str: ...

Authentication & Configuration