blob: f4d3c0e0d71bf46421016da5aa806f03ef1c8f10 [file] [log] [blame]
<html><body>
<style>
body, h1, h2, h3, div, span, p, pre, a {
margin: 0;
padding: 0;
border: 0;
font-weight: inherit;
font-style: inherit;
font-size: 100%;
font-family: inherit;
vertical-align: baseline;
}
body {
font-size: 13px;
padding: 1em;
}
h1 {
font-size: 26px;
margin-bottom: 1em;
}
h2 {
font-size: 24px;
margin-bottom: 1em;
}
h3 {
font-size: 20px;
margin-bottom: 1em;
margin-top: 1em;
}
pre, code {
line-height: 1.5;
font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
}
pre {
margin-top: 0.5em;
}
h1, h2, h3, p {
font-family: Arial, sans serif;
}
h1, h2, h3 {
border-bottom: solid #CCC 1px;
}
.toc_element {
margin-top: 0.5em;
}
.firstline {
margin-left: 2 em;
}
.method {
margin-top: 1em;
border: solid 1px #CCC;
padding: 1em;
background: #EEE;
}
.details {
font-weight: bold;
font-size: 14px;
}
</style>
<h1><a href="tracing_v1.html">Google Tracing API</a> . <a href="tracing_v1.projects.html">projects</a> . <a href="tracing_v1.projects.traces.html">traces</a></h1>
<h2>Instance Methods</h2>
<p class="toc_element">
<code><a href="#batchUpdate">batchUpdate(parent, body, x__xgafv=None)</a></code></p>
<p class="firstline">Sends new spans to Stackdriver Trace or updates existing spans. If the</p>
<p class="toc_element">
<code><a href="#get">get(name, x__xgafv=None)</a></code></p>
<p class="firstline">Returns a specific trace.</p>
<p class="toc_element">
<code><a href="#list">list(parent, orderBy=None, startTime=None, pageSize=None, x__xgafv=None, pageToken=None, filter=None, endTime=None)</a></code></p>
<p class="firstline">Returns of a list of traces that match the specified filter conditions.</p>
<p class="toc_element">
<code><a href="#listSpans">listSpans(name, pageToken=None, x__xgafv=None)</a></code></p>
<p class="firstline">Returns a list of spans within a trace.</p>
<p class="toc_element">
<code><a href="#listSpans_next">listSpans_next(previous_request, previous_response)</a></code></p>
<p class="firstline">Retrieves the next page of results.</p>
<p class="toc_element">
<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>
<p class="firstline">Retrieves the next page of results.</p>
<h3>Method Details</h3>
<div class="method">
<code class="details" id="batchUpdate">batchUpdate(parent, body, x__xgafv=None)</code>
<pre>Sends new spans to Stackdriver Trace or updates existing spans. If the
name of a trace that you send matches that of an existing trace, any fields
in the existing trace and its spans are overwritten by the provided values,
and any new fields provided are merged with the existing trace data. If the
name does not match, a new trace is created with given set of spans.
Args:
parent: string, ID of the Cloud project where the trace data is stored. (required)
body: object, The request body. (required)
The object takes the form of:
{ # The request message for the `BatchUpdateSpans` method.
"spanUpdates": { # A map from trace name to spans to be stored or updated.
"a_key": { # Collection of spans to update.
"spans": [ # A collection of spans.
{ # A span represents a single operation within a trace. Spans can be nested
# to form a trace tree. Often, a trace contains a root span that
# describes the end-to-end latency and, optionally, one or more subspans for
# its sub-operations. (A trace could alternatively contain multiple root spans,
# or none at all.) Spans do not need to be contiguous. There may be gaps
# and/or overlaps between spans in a trace.
"status": { # The `Status` type defines a logical error model that is suitable for different # An optional final status for this span.
# programming environments, including REST APIs and RPC APIs. It is used by
# [gRPC](https://github.com/grpc). The error model is designed to be:
#
# - Simple to use and understand for most users
# - Flexible enough to meet unexpected needs
#
# # Overview
#
# The `Status` message contains three pieces of data: error code, error message,
# and error details. The error code should be an enum value of
# google.rpc.Code, but it may accept additional error codes if needed. The
# error message should be a developer-facing English message that helps
# developers *understand* and *resolve* the error. If a localized user-facing
# error message is needed, put the localized message in the error details or
# localize it in the client. The optional error details may contain arbitrary
# information about the error. There is a predefined set of error detail types
# in the package `google.rpc` which can be used for common error conditions.
#
# # Language mapping
#
# The `Status` message is the logical representation of the error model, but it
# is not necessarily the actual wire format. When the `Status` message is
# exposed in different client libraries and different wire protocols, it can be
# mapped differently. For example, it will likely be mapped to some exceptions
# in Java, but more likely mapped to some error codes in C.
#
# # Other uses
#
# The error model and the `Status` message can be used in a variety of
# environments, either with or without APIs, to provide a
# consistent developer experience across different environments.
#
# Example uses of this error model include:
#
# - Partial errors. If a service needs to return partial errors to the client,
# it may embed the `Status` in the normal response to indicate the partial
# errors.
#
# - Workflow errors. A typical workflow has multiple steps. Each step may
# have a `Status` message for error reporting purpose.
#
# - Batch operations. If a client uses batch request and batch response, the
# `Status` message should be used directly inside batch response, one for
# each error sub-response.
#
# - Asynchronous operations. If an API call embeds asynchronous operation
# results in its response, the status of those operations should be
# represented directly using the `Status` message.
#
# - Logging. If some API errors are stored in logs, the message `Status` could
# be used directly after any stripping needed for security/privacy reasons.
"message": "A String", # A developer-facing error message, which should be in English. Any
# user-facing error message should be localized and sent in the
# google.rpc.Status.details field, or localized by the client.
"code": 42, # The status code, which should be an enum value of google.rpc.Code.
"details": [ # A list of messages that carry the error details. There will be a
# common set of message types for APIs to use.
{
"a_key": "", # Properties of the object. Contains field @type with type URL.
},
],
},
"stackTrace": { # StackTrace collected in a trace. # Stack trace captured at the start of the span.
"stackTraceHashId": "A String", # The hash ID is used to conserve network bandwidth for duplicate
# stack traces within a single trace.
#
# Often multiple spans will have identical stack traces.
# The first occurance of a stack trace should contain both the
# `stackFrame` content and a value in `stackTraceHashId`.
#
# Subsequent spans within the same request can refer
# to that stack trace by only setting `stackTraceHashId`.
"stackFrame": [ # Stack frames of this stack trace.
{ # Represents a single stack frame in a stack trace.
"columnNumber": "A String", # Column number is important in JavaScript (anonymous functions).
# May not be available in some languages.
"functionName": "A String", # The fully-qualified name that uniquely identifies this function or
# method.
"fileName": "A String", # The filename of the file containing this frame.
"originalFunctionName": "A String", # Used when the function name is
# [mangled](http://www.avabodh.com/cxxin/namemangling.html). May be
# fully-qualified.
"loadModule": { # Binary module. # Binary module the code is loaded from.
"buildId": "A String", # Build_id is a unique identifier for the module,
# usually a hash of its contents
"module": "A String", # E.g. main binary, kernel modules, and dynamic libraries
# such as libc.so, sharedlib.so
},
"lineNumber": "A String", # Line number of the frame.
"sourceVersion": "A String", # The version of the deployed source code.
},
],
},
"name": "A String", # Name of the span. The span name is sanitized and displayed in the
# Stackdriver Trace tool in the {% dynamic print site_values.console_name %}.
# The name may be a method name or some other per-call site name.
# For the same executable and the same call point, a best practice is
# to use a consistent name, which makes it easier to correlate
# cross-trace spans.
"links": [ # A collection of links, which are references from this span to another span
# in a different trace.
{ # A pointer from this span to another span in a different `Trace`. Used
# (for example) in batching operations, where a single batch handler
# processes multiple requests from different traces.
"spanId": "A String", # The `id` of the linked span.
"traceId": "A String", # The ID of the parent trace of the linked span.
"type": "A String", # The relationship of the current span relative to the linked span.
},
],
"localEndTime": "A String", # End time of the span.
# On the client side, this is the local machine clock time at which the span
# execution was ended; on the server
# side, this is the time at which the server application handler stopped
# running.
"parentId": "A String", # ID of the parent span. If this is a root span, the value must be `0` or
# empty.
"attributes": { # Properties of a span in key:value format. The maximum length for the
# key is 128 characters. The value can be a string (up to 2000 characters),
# int, or boolean.
#
# Some common pair examples:
#
# "/instance_id": "my-instance"
# "/zone": "us-central1-a"
# "/grpc/peer_address": "ip:port" (dns, etc.)
# "/grpc/deadline": "Duration"
# "/http/user_agent"
# "/http/request_bytes": 300
# "/http/response_bytes": 1200
# "/http/url": google.com/apis
# "abc.com/myattribute": true
"a_key": { # The allowed types for the value side of an attribute key:value pair.
"stringValue": "A String", # A string value.
"intValue": "A String", # An integer value.
"boolValue": True or False, # A boolean value.
},
},
"timeEvents": [ # A collection of `TimeEvent`s. A `TimeEvent` is a time-stamped annotation
# on the span, consisting of either user-supplied key:value pairs, or
# details of an RPC message sent/received on the network.
{ # A time-stamped annotation in the Span.
"networkEvent": { # An event describing an RPC message sent/received on the network. # An event describing an RPC message sent/received on the network.
"messageSize": "A String", # The number of bytes sent or received.
"type": "A String", # Type of NetworkEvent. Indicates whether the RPC message was sent or
# received.
"kernelTime": "A String", # If available, this is the kernel time:
#
# * For sent messages, this is the time at which the first bit was sent.
# * For received messages, this is the time at which the last bit was
# received.
"messageId": "A String", # An identifier for the message, which must be unique in this span.
},
"annotation": { # Text annotation with a set of attributes. # One or more key:value pairs.
"attributes": { # A set of attributes on the annotation.
"a_key": { # The allowed types for the value side of an attribute key:value pair.
"stringValue": "A String", # A string value.
"intValue": "A String", # An integer value.
"boolValue": True or False, # A boolean value.
},
},
"description": "A String", # A user-supplied message describing the event.
},
"localTime": "A String", # The timestamp indicating the time the event occurred.
},
],
"id": "A String", # Identifier for the span. Must be a 64-bit integer other than 0 and
# unique within a trace.
"localStartTime": "A String", # Start time of the span.
# On the client side, this is the local machine clock time at which the span
# execution was started; on the server
# side, this is the time at which the server application handler started
# running.
"hasRemoteParent": True or False, # True if this span has a remote parent (is an RPC server span).
},
],
},
},
}
x__xgafv: string, V1 error format.
Allowed values
1 - v1 error format
2 - v2 error format
Returns:
An object of the form:
{ # A generic empty message that you can re-use to avoid defining duplicated
# empty messages in your APIs. A typical example is to use it as the request
# or the response type of an API method. For instance:
#
# service Foo {
# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
# }
#
# The JSON representation for `Empty` is empty JSON object `{}`.
}</pre>
</div>
<div class="method">
<code class="details" id="get">get(name, x__xgafv=None)</code>
<pre>Returns a specific trace.
Args:
name: string, ID of the trace. Format is `projects/PROJECT_ID/traces/TRACE_ID`. (required)
x__xgafv: string, V1 error format.
Allowed values
1 - v1 error format
2 - v2 error format
Returns:
An object of the form:
{ # A trace describes how long it takes for an application to perform some
# operations. It consists of a set of spans, each representing
# an operation and including time information and operation details.
"name": "A String", # A globally unique identifier for the trace in the format
# `projects/PROJECT_NUMBER/traces/TRACE_ID`. `TRACE_ID` is a base16-encoded
# string of a 128-bit number and is required to be 32 char long.
}</pre>
</div>
<div class="method">
<code class="details" id="list">list(parent, orderBy=None, startTime=None, pageSize=None, x__xgafv=None, pageToken=None, filter=None, endTime=None)</code>
<pre>Returns of a list of traces that match the specified filter conditions.
Args:
parent: string, ID of the Cloud project where the trace data is stored. (required)
orderBy: string, Field used to sort the returned traces. Optional.
Can be one of the following:
* `trace_id`
* `name` (`name` field of root span in the trace)
* `duration` (difference between `end_time` and `start_time` fields of
the root span)
* `start` (`start_time` field of the root span)
Descending order can be specified by appending `desc` to the sort field
(for example, `name desc`).
Only one sort field is permitted.
startTime: string, Start of the time interval (inclusive) during which the trace data was
collected from the application.
pageSize: integer, Maximum number of traces to return. If not specified or <= 0, the
implementation selects a reasonable value. The implementation may
return fewer traces than the requested page size. Optional.
x__xgafv: string, V1 error format.
Allowed values
1 - v1 error format
2 - v2 error format
pageToken: string, Token identifying the page of results to return. If provided, use the
value of the `next_page_token` field from a previous request. Optional.
filter: string, An optional filter for the request.
Example:
`version_label_key:a some_label:some_label_key`
returns traces from version `a` and has `some_label` with `some_label_key`.
endTime: string, End of the time interval (inclusive) during which the trace data was
collected from the application.
Returns:
An object of the form:
{ # The response message for the `ListTraces` method.
"nextPageToken": "A String", # If defined, indicates that there are more traces that match the request
# and that this value should be passed to the next request to continue
# retrieving additional traces.
"traces": [ # List of trace records returned.
{ # A trace describes how long it takes for an application to perform some
# operations. It consists of a set of spans, each representing
# an operation and including time information and operation details.
"name": "A String", # A globally unique identifier for the trace in the format
# `projects/PROJECT_NUMBER/traces/TRACE_ID`. `TRACE_ID` is a base16-encoded
# string of a 128-bit number and is required to be 32 char long.
},
],
}</pre>
</div>
<div class="method">
<code class="details" id="listSpans">listSpans(name, pageToken=None, x__xgafv=None)</code>
<pre>Returns a list of spans within a trace.
Args:
name: string, ID of the trace for which to list child spans. Format is
`projects/PROJECT_ID/traces/TRACE_ID`. (required)
pageToken: string, Token identifying the page of results to return. If provided, use the
value of the `nextPageToken` field from a previous request. Optional.
x__xgafv: string, V1 error format.
Allowed values
1 - v1 error format
2 - v2 error format
Returns:
An object of the form:
{ # The response message for the `ListSpans` method.
"nextPageToken": "A String", # If defined, indicates that there are more spans that match the request.
# Pass this as the value of `pageToken` in a subsequent request to retrieve
# additional spans.
"spans": [ # The requested spans if there are any in the specified trace.
{ # A span represents a single operation within a trace. Spans can be nested
# to form a trace tree. Often, a trace contains a root span that
# describes the end-to-end latency and, optionally, one or more subspans for
# its sub-operations. (A trace could alternatively contain multiple root spans,
# or none at all.) Spans do not need to be contiguous. There may be gaps
# and/or overlaps between spans in a trace.
"status": { # The `Status` type defines a logical error model that is suitable for different # An optional final status for this span.
# programming environments, including REST APIs and RPC APIs. It is used by
# [gRPC](https://github.com/grpc). The error model is designed to be:
#
# - Simple to use and understand for most users
# - Flexible enough to meet unexpected needs
#
# # Overview
#
# The `Status` message contains three pieces of data: error code, error message,
# and error details. The error code should be an enum value of
# google.rpc.Code, but it may accept additional error codes if needed. The
# error message should be a developer-facing English message that helps
# developers *understand* and *resolve* the error. If a localized user-facing
# error message is needed, put the localized message in the error details or
# localize it in the client. The optional error details may contain arbitrary
# information about the error. There is a predefined set of error detail types
# in the package `google.rpc` which can be used for common error conditions.
#
# # Language mapping
#
# The `Status` message is the logical representation of the error model, but it
# is not necessarily the actual wire format. When the `Status` message is
# exposed in different client libraries and different wire protocols, it can be
# mapped differently. For example, it will likely be mapped to some exceptions
# in Java, but more likely mapped to some error codes in C.
#
# # Other uses
#
# The error model and the `Status` message can be used in a variety of
# environments, either with or without APIs, to provide a
# consistent developer experience across different environments.
#
# Example uses of this error model include:
#
# - Partial errors. If a service needs to return partial errors to the client,
# it may embed the `Status` in the normal response to indicate the partial
# errors.
#
# - Workflow errors. A typical workflow has multiple steps. Each step may
# have a `Status` message for error reporting purpose.
#
# - Batch operations. If a client uses batch request and batch response, the
# `Status` message should be used directly inside batch response, one for
# each error sub-response.
#
# - Asynchronous operations. If an API call embeds asynchronous operation
# results in its response, the status of those operations should be
# represented directly using the `Status` message.
#
# - Logging. If some API errors are stored in logs, the message `Status` could
# be used directly after any stripping needed for security/privacy reasons.
"message": "A String", # A developer-facing error message, which should be in English. Any
# user-facing error message should be localized and sent in the
# google.rpc.Status.details field, or localized by the client.
"code": 42, # The status code, which should be an enum value of google.rpc.Code.
"details": [ # A list of messages that carry the error details. There will be a
# common set of message types for APIs to use.
{
"a_key": "", # Properties of the object. Contains field @type with type URL.
},
],
},
"stackTrace": { # StackTrace collected in a trace. # Stack trace captured at the start of the span.
"stackTraceHashId": "A String", # The hash ID is used to conserve network bandwidth for duplicate
# stack traces within a single trace.
#
# Often multiple spans will have identical stack traces.
# The first occurance of a stack trace should contain both the
# `stackFrame` content and a value in `stackTraceHashId`.
#
# Subsequent spans within the same request can refer
# to that stack trace by only setting `stackTraceHashId`.
"stackFrame": [ # Stack frames of this stack trace.
{ # Represents a single stack frame in a stack trace.
"columnNumber": "A String", # Column number is important in JavaScript (anonymous functions).
# May not be available in some languages.
"functionName": "A String", # The fully-qualified name that uniquely identifies this function or
# method.
"fileName": "A String", # The filename of the file containing this frame.
"originalFunctionName": "A String", # Used when the function name is
# [mangled](http://www.avabodh.com/cxxin/namemangling.html). May be
# fully-qualified.
"loadModule": { # Binary module. # Binary module the code is loaded from.
"buildId": "A String", # Build_id is a unique identifier for the module,
# usually a hash of its contents
"module": "A String", # E.g. main binary, kernel modules, and dynamic libraries
# such as libc.so, sharedlib.so
},
"lineNumber": "A String", # Line number of the frame.
"sourceVersion": "A String", # The version of the deployed source code.
},
],
},
"name": "A String", # Name of the span. The span name is sanitized and displayed in the
# Stackdriver Trace tool in the {% dynamic print site_values.console_name %}.
# The name may be a method name or some other per-call site name.
# For the same executable and the same call point, a best practice is
# to use a consistent name, which makes it easier to correlate
# cross-trace spans.
"links": [ # A collection of links, which are references from this span to another span
# in a different trace.
{ # A pointer from this span to another span in a different `Trace`. Used
# (for example) in batching operations, where a single batch handler
# processes multiple requests from different traces.
"spanId": "A String", # The `id` of the linked span.
"traceId": "A String", # The ID of the parent trace of the linked span.
"type": "A String", # The relationship of the current span relative to the linked span.
},
],
"localEndTime": "A String", # End time of the span.
# On the client side, this is the local machine clock time at which the span
# execution was ended; on the server
# side, this is the time at which the server application handler stopped
# running.
"parentId": "A String", # ID of the parent span. If this is a root span, the value must be `0` or
# empty.
"attributes": { # Properties of a span in key:value format. The maximum length for the
# key is 128 characters. The value can be a string (up to 2000 characters),
# int, or boolean.
#
# Some common pair examples:
#
# "/instance_id": "my-instance"
# "/zone": "us-central1-a"
# "/grpc/peer_address": "ip:port" (dns, etc.)
# "/grpc/deadline": "Duration"
# "/http/user_agent"
# "/http/request_bytes": 300
# "/http/response_bytes": 1200
# "/http/url": google.com/apis
# "abc.com/myattribute": true
"a_key": { # The allowed types for the value side of an attribute key:value pair.
"stringValue": "A String", # A string value.
"intValue": "A String", # An integer value.
"boolValue": True or False, # A boolean value.
},
},
"timeEvents": [ # A collection of `TimeEvent`s. A `TimeEvent` is a time-stamped annotation
# on the span, consisting of either user-supplied key:value pairs, or
# details of an RPC message sent/received on the network.
{ # A time-stamped annotation in the Span.
"networkEvent": { # An event describing an RPC message sent/received on the network. # An event describing an RPC message sent/received on the network.
"messageSize": "A String", # The number of bytes sent or received.
"type": "A String", # Type of NetworkEvent. Indicates whether the RPC message was sent or
# received.
"kernelTime": "A String", # If available, this is the kernel time:
#
# * For sent messages, this is the time at which the first bit was sent.
# * For received messages, this is the time at which the last bit was
# received.
"messageId": "A String", # An identifier for the message, which must be unique in this span.
},
"annotation": { # Text annotation with a set of attributes. # One or more key:value pairs.
"attributes": { # A set of attributes on the annotation.
"a_key": { # The allowed types for the value side of an attribute key:value pair.
"stringValue": "A String", # A string value.
"intValue": "A String", # An integer value.
"boolValue": True or False, # A boolean value.
},
},
"description": "A String", # A user-supplied message describing the event.
},
"localTime": "A String", # The timestamp indicating the time the event occurred.
},
],
"id": "A String", # Identifier for the span. Must be a 64-bit integer other than 0 and
# unique within a trace.
"localStartTime": "A String", # Start time of the span.
# On the client side, this is the local machine clock time at which the span
# execution was started; on the server
# side, this is the time at which the server application handler started
# running.
"hasRemoteParent": True or False, # True if this span has a remote parent (is an RPC server span).
},
],
}</pre>
</div>
<div class="method">
<code class="details" id="listSpans_next">listSpans_next(previous_request, previous_response)</code>
<pre>Retrieves the next page of results.
Args:
previous_request: The request for the previous page. (required)
previous_response: The response from the request for the previous page. (required)
Returns:
A request object that you can call 'execute()' on to request the next
page. Returns None if there are no more items in the collection.
</pre>
</div>
<div class="method">
<code class="details" id="list_next">list_next(previous_request, previous_response)</code>
<pre>Retrieves the next page of results.
Args:
previous_request: The request for the previous page. (required)
previous_response: The response from the request for the previous page. (required)
Returns:
A request object that you can call 'execute()' on to request the next
page. Returns None if there are no more items in the collection.
</pre>
</div>
</body></html>