Client for Stackdriver Trace API#

class google.cloud.trace_v2.TraceServiceClient(transport=None, channel=None, credentials=None, client_config=None, client_info=None, client_options=None)[source]#

This file describes an API for collecting and viewing traces and spans within a trace. A Trace is a collection of spans corresponding to a single operation or set of operations for an application. A span is an individual timed event which forms a node of the trace tree. A single trace may contain span(s) from multiple services.

Constructor.

Parameters
  • (Union[TraceServiceGrpcTransport, (transport) – Callable[[~.Credentials, type], ~.TraceServiceGrpcTransport]): A transport instance, responsible for actually making the API calls. The default transport uses the gRPC protocol. This argument may also be a callable which returns a transport instance. Callables will be sent the credentials as the first argument and the default transport class as the second argument.

  • channel (grpc.Channel) – DEPRECATED. A Channel instance through which to make calls. This argument is mutually exclusive with credentials; providing both will raise an exception.

  • credentials (google.auth.credentials.Credentials) – The authorization credentials to attach to requests. These credentials identify this application to the service. If none are specified, the client will attempt to ascertain the credentials from the environment. This argument is mutually exclusive with providing a transport instance to transport; doing so will raise an exception.

  • client_config (dict) – DEPRECATED. A dictionary of call options for each method. If not specified, the default configuration is used.

  • client_info (google.api_core.gapic_v1.client_info.ClientInfo) – The client info used to send a user-agent string along with API requests. If None, then default info will be used. Generally, you only need to set this if you’re developing your own client library.

  • client_options (Union[dict, google.api_core.client_options.ClientOptions]) – Client options used to set user options on the client. API Endpoint should be set through client_options.

batch_write_spans(name, spans, retry=<object object>, timeout=<object object>, metadata=None)[source]#

Sends new spans to new or existing traces. You cannot update existing spans.

Example

>>> from google.cloud import trace_v2
>>>
>>> client = trace_v2.TraceServiceClient()
>>>
>>> name = client.project_path('[PROJECT]')
>>>
>>> # TODO: Initialize `spans`:
>>> spans = []
>>>
>>> client.batch_write_spans(name, spans)
Parameters
  • name (str) – Required. The name of the project where the spans belong. The format is projects/[PROJECT_ID].

  • spans (list[Union[dict, Span]]) –

    A list of new spans. The span names must not match existing spans, or the results are undefined.

    If a dict is provided, it must be of the same form as the protobuf message Span

  • retry (Optional[google.api_core.retry.Retry]) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

  • timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

  • metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.

Raises
create_span(name, span_id, display_name, start_time, end_time, parent_span_id=None, attributes=None, stack_trace=None, time_events=None, links=None, status=None, same_process_as_parent_span=None, child_span_count=None, retry=<object object>, timeout=<object object>, metadata=None)[source]#

Creates a new span.

Example

>>> from google.cloud import trace_v2
>>>
>>> client = trace_v2.TraceServiceClient()
>>>
>>> name = client.span_path('[PROJECT]', '[TRACE]', '[SPAN]')
>>>
>>> # TODO: Initialize `span_id`:
>>> span_id = ''
>>>
>>> # TODO: Initialize `display_name`:
>>> display_name = {}
>>>
>>> # TODO: Initialize `start_time`:
>>> start_time = {}
>>>
>>> # TODO: Initialize `end_time`:
>>> end_time = {}
>>>
>>> response = client.create_span(name, span_id, display_name, start_time, end_time)
Parameters
  • name (str) –

    The resource name of the span in the following format:

    projects/[PROJECT_ID]/traces/[TRACE_ID]/spans/[SPAN_ID]
    

    [TRACE_ID] is a unique identifier for a trace within a project; it is a 32-character hexadecimal encoding of a 16-byte array.

    [SPAN_ID] is a unique identifier for a span within a trace; it is a 16-character hexadecimal encoding of an 8-byte array.

  • span_id (str) – The [SPAN_ID] portion of the span’s resource name.

  • display_name (Union[dict, TruncatableString]) –

    A description of the span’s operation (up to 128 bytes). Stackdriver Trace displays the description in the {% dynamic print site_values.console_name %}. For example, the display name can be a qualified method name or a file name and a line number where the operation is called. A best practice is to use the same display name within an application and at the same call point. This makes it easier to correlate spans in different traces.

    If a dict is provided, it must be of the same form as the protobuf message TruncatableString

  • start_time (Union[dict, Timestamp]) –

    The start time of the span. On the client side, this is the time kept by the local machine where the span execution starts. On the server side, this is the time when the server’s application handler starts running.

    If a dict is provided, it must be of the same form as the protobuf message Timestamp

  • end_time (Union[dict, Timestamp]) –

    The end time of the span. On the client side, this is the time kept by the local machine where the span execution ends. On the server side, this is the time when the server application handler stops running.

    If a dict is provided, it must be of the same form as the protobuf message Timestamp

  • parent_span_id (str) – The [SPAN_ID] of this span’s parent span. If this is a root span, then this field must be empty.

  • attributes (Union[dict, Attributes]) –

    A set of attributes on the span. You can have up to 32 attributes per span.

    If a dict is provided, it must be of the same form as the protobuf message Attributes

  • stack_trace (Union[dict, StackTrace]) –

    Stack trace captured at the start of the span.

    If a dict is provided, it must be of the same form as the protobuf message StackTrace

  • time_events (Union[dict, TimeEvents]) –

    A set of time events. You can have up to 32 annotations and 128 message events per span.

    If a dict is provided, it must be of the same form as the protobuf message TimeEvents

  • links (Union[dict, Links]) –

    Links associated with the span. You can have up to 128 links per Span.

    If a dict is provided, it must be of the same form as the protobuf message Links

  • status (Union[dict, Status]) –

    An optional final status for this span.

    If a dict is provided, it must be of the same form as the protobuf message Status

  • same_process_as_parent_span (Union[dict, BoolValue]) –

    (Optional) Set this parameter to indicate whether this span is in the same process as its parent. If you do not set this parameter, Stackdriver Trace is unable to take advantage of this helpful information.

    If a dict is provided, it must be of the same form as the protobuf message BoolValue

  • child_span_count (Union[dict, Int32Value]) –

    An optional number of child spans that were generated while this span was active. If set, allows implementation to detect missing child spans.

    If a dict is provided, it must be of the same form as the protobuf message Int32Value

  • retry (Optional[google.api_core.retry.Retry]) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

  • timeout (Optional[float]) – The amount of time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

  • metadata (Optional[Sequence[Tuple[str, str]]]) – Additional metadata that is provided to the method.

Returns

A Span instance.

Raises
enums = <module 'google.cloud.trace_v2.gapic.enums' from '/usr/local/lib/python3.7/site-packages/google/cloud/trace_v2/gapic/enums.py'>#
classmethod from_service_account_file(filename, *args, **kwargs)[source]#

Creates an instance of this client using the provided credentials file.

Parameters
  • filename (str) – The path to the service account private key json file.

  • args – Additional arguments to pass to the constructor.

  • kwargs – Additional arguments to pass to the constructor.

Returns

The constructed client.

Return type

TraceServiceClient

classmethod from_service_account_json(filename, *args, **kwargs)#

Creates an instance of this client using the provided credentials file.

Parameters
  • filename (str) – The path to the service account private key json file.

  • args – Additional arguments to pass to the constructor.

  • kwargs – Additional arguments to pass to the constructor.

Returns

The constructed client.

Return type

TraceServiceClient

classmethod project_path(project)[source]#

Return a fully-qualified project string.

classmethod span_path(project, trace, span)[source]#

Return a fully-qualified span string.