Class TraceServiceClient (0.23.0)

TraceServiceClient(
    transport=None,
    channel=None,
    credentials=None,
    client_config=None,
    client_info=None,
    client_options=None,
)

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.

Methods

TraceServiceClient

TraceServiceClient(
    transport=None,
    channel=None,
    credentials=None,
    client_config=None,
    client_info=None,
    client_options=None,
)

Constructor.

Parameters
NameDescription
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

batch_write_spans(name, spans, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

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

.. rubric:: 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
NameDescription
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.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

create_span

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=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>, metadata=None)

Creates a new span.

.. rubric:: 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
NameDescription
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.

Exceptions
TypeDescription
google.api_core.exceptions.GoogleAPICallErrorIf the request failed for any reason.
google.api_core.exceptions.RetryErrorIf the request failed due to a retryable error and retry attempts failed.
ValueErrorIf the parameters are invalid.

from_service_account_file

from_service_account_file(filename, *args, **kwargs)

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

Parameter
NameDescription
filename str

The path to the service account private key json file.

Returns
TypeDescription
TraceServiceClientThe constructed client.

from_service_account_json

from_service_account_json(filename, *args, **kwargs)

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

Parameter
NameDescription
filename str

The path to the service account private key json file.

Returns
TypeDescription
TraceServiceClientThe constructed client.

project_path

project_path(project)

Return a fully-qualified project string.

span_path

span_path(project, trace, span)

Return a fully-qualified span string.