V1 Data Types

class Trace:
    project_id: str  # Project ID for this trace
    trace_id: str  # Globally unique identifier for this trace  
    spans: List[TraceSpan]  # Collection of spans that comprise this trace

class TraceSpan:
    span_id: int  # Identifier for this span, unique within a trace
    kind: SpanKind  # Type of span (unspecified, RPC server, RPC client)
    name: str  # Name of the span (description of the operation)
    start_time: Timestamp  # Start time of the span's execution
    end_time: Timestamp  # End time of the span's execution  
    parent_span_id: int  # ID of the parent span (0 if root span)
    labels: Dict[str, str]  # Collection of labels associated with this span

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

class Traces:
    traces: List[Trace]  # Collection of traces

class ListTracesRequest:
    project_id: str  # Required. ID of the project containing traces
    view: ViewType  # Type of data to return for each trace
    page_size: int  # Maximum number of traces to return
    page_token: str  # Token identifying specific page of results
    start_time: Timestamp  # Start of the time range (inclusive)
    end_time: Timestamp  # End of the time range (exclusive) 
    filter: str  # Optional filter expression
    order_by: str  # Field used to sort the returned traces

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

class ListTracesResponse:
    traces: List[Trace]  # List of traces matching the request
    next_page_token: str  # Token for retrieving the next page of results

class GetTraceRequest:
    project_id: str  # Required. ID of the project containing the trace
    trace_id: str  # Required. ID of the trace to retrieve

class PatchTracesRequest:
    project_id: str  # Required. ID of the project receiving traces
    traces: Traces  # Required. Collection of traces to be patched

class Timestamp:
    seconds: int  # Seconds since Unix epoch (January 1, 1970 UTC)
    nanos: int  # Non-negative fractions of a second at nanosecond resolution

from google.cloud import trace_v1

# Create a simple span
span = trace_v1.TraceSpan(
    span_id=12345,
    kind=trace_v1.TraceSpan.SpanKind.RPC_SERVER,
    name="handle-request",
    start_time={"seconds": 1609459200, "nanos": 0},
    end_time={"seconds": 1609459201, "nanos": 500000000},
    parent_span_id=0,  # Root span
    labels={
        "http.method": "GET",
        "http.url": "/api/users",
        "http.status_code": "200"
    }
)

# Create trace containing the span
trace = trace_v1.Trace(
    project_id="my-project",
    trace_id="abc123def456ghi789",
    spans=[span]
)

from google.cloud import trace_v1

# Create root span
root_span = trace_v1.TraceSpan(
    span_id=1,
    kind=trace_v1.TraceSpan.SpanKind.RPC_SERVER,
    name="handle-user-request",
    start_time={"seconds": 1609459200, "nanos": 0},
    end_time={"seconds": 1609459203, "nanos": 0},
    parent_span_id=0,
    labels={
        "component": "api-server",
        "operation": "get-user"
    }
)

# Create child span for database operation
db_span = trace_v1.TraceSpan(
    span_id=2,
    kind=trace_v1.TraceSpan.SpanKind.RPC_CLIENT,
    name="database-query",
    start_time={"seconds": 1609459201, "nanos": 0},
    end_time={"seconds": 1609459202, "nanos": 500000000},
    parent_span_id=1,  # Child of root span
    labels={
        "db.type": "postgresql",
        "db.statement": "SELECT * FROM users WHERE id = ?",
        "db.instance": "users-db"
    }
)

# Create child span for cache operation
cache_span = trace_v1.TraceSpan(
    span_id=3,
    kind=trace_v1.TraceSpan.SpanKind.RPC_CLIENT,
    name="cache-lookup",
    start_time={"seconds": 1609459200, "nanos": 500000000},
    end_time={"seconds": 1609459200, "nanos": 750000000},
    parent_span_id=1,  # Child of root span
    labels={
        "cache.type": "redis",
        "cache.key": "user:123",
        "cache.hit": "false"
    }
)

# Create trace with all spans
trace = trace_v1.Trace(
    project_id="my-project",
    trace_id="multi-span-trace-id",
    spans=[root_span, db_span, cache_span]
)

from google.cloud import trace_v1

# Create list traces request
list_request = trace_v1.ListTracesRequest(
    project_id="my-project",
    view=trace_v1.ListTracesRequest.ViewType.COMPLETE,
    page_size=50,
    start_time={"seconds": 1609459200},
    end_time={"seconds": 1609462800},
    filter='span:"database-query"',
    order_by="start_time desc"
)

# Create get trace request  
get_request = trace_v1.GetTraceRequest(
    project_id="my-project",
    trace_id="abc123def456ghi789"
)

# Create patch traces request
traces_collection = trace_v1.Traces(traces=[trace])
patch_request = trace_v1.PatchTracesRequest(
    project_id="my-project",
    traces=traces_collection
)

import time
from google.cloud import trace_v1

# Create timestamp from current time
current_time = time.time()
timestamp = {
    "seconds": int(current_time),
    "nanos": int((current_time % 1) * 1e9)
}

# Create span with precise timing
span = trace_v1.TraceSpan(
    span_id=1,
    kind=trace_v1.TraceSpan.SpanKind.RPC_SERVER,
    name="timed-operation",
    start_time=timestamp,
    end_time={
        "seconds": timestamp["seconds"] + 1,
        "nanos": timestamp["nanos"] + 500000000
    },
    parent_span_id=0,
    labels={"timing": "precise"}
)