Blame - docs/dyn/tracing_v1.projects.traces.html - platform/external/python/google-api-python-client

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

76

<h2>Instance Methods</h2>

77

78

<code><a href="#batchUpdate">batchUpdate(parent, body, x__xgafv=None)</a></code></p>

79

<p class="firstline">Sends new spans to Stackdriver Trace or updates existing spans. If the</p>

80

81

<code><a href="#get">get(name, x__xgafv=None)</a></code></p>

82

<p class="firstline">Returns a specific trace.</p>

83

84

<code><a href="#list">list(parent, orderBy=None, startTime=None, pageSize=None, x__xgafv=None, pageToken=None, filter=None, endTime=None)</a></code></p>

85

<p class="firstline">Returns of a list of traces that match the specified filter conditions.</p>

86

87

<code><a href="#listSpans">listSpans(name, pageToken=None, x__xgafv=None)</a></code></p>

88

<p class="firstline">Returns a list of spans within a trace.</p>

89

90

<code><a href="#listSpans_next">listSpans_next(previous_request, previous_response)</a></code></p>

91

<p class="firstline">Retrieves the next page of results.</p>

92

93

<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>

94

<p class="firstline">Retrieves the next page of results.</p>

95

<h3>Method Details</h3>

96

97

<code class="details" id="batchUpdate">batchUpdate(parent, body, x__xgafv=None)</code>

98

<pre>Sends new spans to Stackdriver Trace or updates existing spans. If the

99

name of a trace that you send matches that of an existing trace, any fields

100

in the existing trace and its spans are overwritten by the provided values,

101

and any new fields provided are merged with the existing trace data. If the

102

name does not match, a new trace is created with given set of spans.

103

104

Args:

105

parent: string, ID of the Cloud project where the trace data is stored. (required)

106

body: object, The request body. (required)

107

The object takes the form of:

108

109

{ # The request message for the `BatchUpdateSpans` method.

110

"spanUpdates": { # A map from trace name to spans to be stored or updated.

111

"a_key": { # Collection of spans to update.

112

"spans": [ # A collection of spans.

113

{ # A span represents a single operation within a trace. Spans can be nested

114

# and form a trace tree. Often, a trace contains a root span that describes the

115

# end-to-end latency and, optionally, one or more subspans for

116

# its sub-operations. Spans do not need to be contiguous. There may be gaps

117

# between spans in a trace.

118

"status": { # The `Status` type defines a logical error model that is suitable for different # The final status of the Span. This is optional.

119

# programming environments, including REST APIs and RPC APIs. It is used by

120

# [gRPC](https://github.com/grpc). The error model is designed to be:

121

#

122

# - Simple to use and understand for most users

123

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

128

# and error details. The error code should be an enum value of

129

# google.rpc.Code, but it may accept additional error codes if needed. The

130

# error message should be a developer-facing English message that helps

131

# developers *understand* and *resolve* the error. If a localized user-facing

132

# error message is needed, put the localized message in the error details or

133

# localize it in the client. The optional error details may contain arbitrary

134

# information about the error. There is a predefined set of error detail types

135

# 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

140

# is not necessarily the actual wire format. When the `Status` message is

141

# exposed in different client libraries and different wire protocols, it can be

142

# mapped differently. For example, it will likely be mapped to some exceptions

143

# 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

148

# environments, either with or without APIs, to provide a

149

# consistent developer experience across different environments.

150

#

151

# Example uses of this error model include:

152

#

153

# - Partial errors. If a service needs to return partial errors to the client,

154

# it may embed the `Status` in the normal response to indicate the partial

155

# errors.

156

#

157

# - Workflow errors. A typical workflow has multiple steps. Each step may

158

# have a `Status` message for error reporting purpose.

159

#

160

# - Batch operations. If a client uses batch request and batch response, the

161

# `Status` message should be used directly inside batch response, one for

162

# each error sub-response.

163

#

164

# - Asynchronous operations. If an API call embeds asynchronous operation

165

# results in its response, the status of those operations should be

166

# represented directly using the `Status` message.

167

#

168

# - Logging. If some API errors are stored in logs, the message `Status` could

169

# be used directly after any stripping needed for security/privacy reasons.

170

"message": "A String", # A developer-facing error message, which should be in English. Any

171

# user-facing error message should be localized and sent in the

172

# google.rpc.Status.details field, or localized by the client.

173

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

174

"details": [ # A list of messages that carry the error details. There will be a

175

# common set of message types for APIs to use.

176

{

177

"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. This is optional.

182

"stackTraceHashId": "A String", # User can choose to use their own hash function to hash large attributes to

183

# save network bandwidth and storage.

184

# Typical usage is to pass both stack_frame and stack_trace_hash_id initially

185

# to inform the storage of the mapping. And in subsequent calls, pass in

186

# stack_trace_hash_id only. User shall verify the hash value is

187

# successfully stored.

188

"stackFrame": [ # Stack frames of this stack trace.

189

{ # Presents a single stack frame in a stack trace.

190

"columnNumber": "A String", # Column number is important in JavaScript(anonymous functions),

191

# Might not be available in some languages.

192

"functionName": "A String", # Fully qualified names which uniquely identify function/method/etc.

193

"fileName": "A String", # File name of the frame.

194

"sourceVersion": "A String", # source_version is deployment specific. It might be

195

# better to be stored in deployment metadata.

196

"loadModule": { # Binary module. # Binary module the code is loaded from.

197

"buildId": "A String", # Build_id is a unique identifier for the module,

198

# usually a hash of its contents

199

"module": "A String", # E.g. main binary, kernel modules, and dynamic libraries

200

# such as libc.so, sharedlib.so

201

},

202

"lineNumber": "A String", # Line number of the frame.

203

"originalFunctionName": "A String", # Used when function name is ‘mangled’. Not guaranteed to be fully

204

# qualified but usually it is.

},

],

},

"hasRemoteParent": True or False, # True if this Span has a remote parent (is an RPC server Span).

209

"links": [ # A collection of links.

210

{ # Link one span with another which may be in a different Trace. Used (for

211

# example) in batching operations, where a single batch handler processes

212

# multiple requests from different traces.

213

"spanId": "A String", # The span identifier of the linked span.

214

"traceId": "A String", # The trace identifier of the linked span.

215

"type": "A String", # The type of the link.

216

},

217

],

218

"parentId": "A String", # ID of parent span. 0 or missing if this is a root span.

219

"localEndTime": "A String", # Local machine clock time from the UNIX epoch,

220

# at which span execution ended.

221

# On the server side these are the times when the server application

222

# handler finishes running.

223

"attributes": { # Properties of a span. Attributes at the span level.

224

# E.g.

225

# "/instance_id": "my-instance"

226

# "/zone": "us-central1-a"

227

# "/grpc/peer_address": "ip:port" (dns, etc.)

228

# "/grpc/deadline": "Duration"

229

# "/http/user_agent"

230

# "/http/request_bytes": 300

231

# "/http/response_bytes": 1200

232

# "/http/url": google.com/apis

233

# "/pid"

234

# "abc.com/myattribute": "my attribute value"

235

#

236

# Maximum length for attribute key is 128 characters, for string attribute

237

# value is 2K characters.

238

"a_key": { # Allowed attribute values.

239

"stringValue": "A String", # A string value.

240

"boolValue": True or False, # A boolean value.

241

"intValue": "A String", # An integer value.

242

},

243

},

244

"timeEvents": [ # A collection of time-stamped events.

245

{ # A time-stamped annotation in the Span.

246

"networkEvent": { # An event describing an RPC message sent/received on the network. # Optional field that can be used only for network events.

247

"messageSize": "A String", # Number of bytes send/receive.

248

"type": "A String", # Type of a NetworkEvent.

249

"kernelTime": "A String", # If available, this is the kernel time:

250

# For sent messages, this is the time at which the first bit was sent.

251

# For received messages, this is the time at which the last bit was

252

# received.

253

"messageId": "A String", # Every message has an identifier, which must be different from all the

254

# network messages in this span.

255

# This is especially important when the request/response are streamed.

256

},

257

"annotation": { # Text annotation with a set of attributes. # Optional field for user supplied <string, AttributeValue> map

258

"attributes": { # A set of attributes on the annotation.

259

"a_key": { # Allowed attribute values.

260

"stringValue": "A String", # A string value.

261

"boolValue": True or False, # A boolean value.

262

"intValue": "A String", # An integer value.

263

},

264

},

265

"description": "A String", # A user-supplied message describing the event.

266

},

267

"localTime": "A String", # The local machine absolute timestamp when this event happened.

268

},

269

],

270

"id": "A String", # Identifier for the span. Must be a 64-bit integer other than 0 and

271

# unique within a trace.

272

"localStartTime": "A String", # Local machine clock time from the UNIX epoch,

273

# at which span execution started.

274

# On the server side these are the times when the server application

275

# handler starts running.

276

"name": "A String", # Name of the span. The span name is sanitized and displayed in the

277

# Stackdriver Trace tool in the {% dynamic print site_values.console_name %}.

278

# The name may be a method name or some other per-call site name.

279

# For the same executable and the same call point, a best practice is

280

# to use a consistent name, which makes it easier to correlate

# cross-trace spans.

},

],

},

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

295

296

{ # A generic empty message that you can re-use to avoid defining duplicated

297

# empty messages in your APIs. A typical example is to use it as the request

298

# or the response type of an API method. For instance:

299

#

300

# service Foo {

301

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

302

# }

303

#

304

# The JSON representation for `Empty` is empty JSON object `{}`.

}</pre>

</div>

<code class="details" id="get">get(name, x__xgafv=None)</code>

310

<pre>Returns a specific trace.

311

312

Args:

313

name: string, ID of the trace which is "projects/<project_id>/traces/<trace_id>". (required)

314

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

321

322

{ # A trace describes how long it takes for an application to perform some

323

# operations. It consists of a set of spans, each of which contains details

324

# about an operation with time information and operation details.

325

"name": "A String", # ID of the trace which is "projects/<project_id>/traces/<trace_id>".

326

# trace_id is globally unique identifier for the trace. Common to all the

327

# spans. It is conceptually a 128-bit hex-encoded value.

}</pre>

</div>

<code class="details" id="list">list(parent, orderBy=None, startTime=None, pageSize=None, x__xgafv=None, pageToken=None, filter=None, endTime=None)</code>

333

<pre>Returns of a list of traces that match the specified filter conditions.

334

335

Args:

336

parent: string, ID of the Cloud project where the trace data is stored. (required)

337

orderBy: string, Field used to sort the returned traces. Optional.

338

Can be one of the following:

339

340

* `trace_id`

341

* `name` (`name` field of root span in the trace)

342

* `duration` (difference between `end_time` and `start_time` fields of

343

the root span)

344

* `start` (`start_time` field of the root span)

345

346

Descending order can be specified by appending `desc` to the sort field

347

(for example, `name desc`).

348

349

Only one sort field is permitted.

350

startTime: string, Start of the time interval (inclusive) during which the trace data was

351

collected from the application.

352

pageSize: integer, Maximum number of traces to return. If not specified or <= 0, the

353

implementation selects a reasonable value. The implementation may

354

return fewer traces than the requested page size. Optional.

355

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

360

value of the `next_page_token` field from a previous request. Optional.

361

filter: string, An optional filter for the request.

362

Example:

363

"version_label_key:a some_label:some_label_key"

364

returns traces from version a and has some_label with some_label_key.

365

endTime: string, End of the time interval (inclusive) during which the trace data was

366

collected from the application.

367

368

Returns:

369

An object of the form:

370

371

{ # The response message for the `ListTraces` method.

372

"nextPageToken": "A String", # If defined, indicates that there are more traces that match the request

373

# and that this value should be passed to the next request to continue

374

# retrieving additional traces.

375

"traces": [ # List of trace records returned.

376

{ # A trace describes how long it takes for an application to perform some

377

# operations. It consists of a set of spans, each of which contains details

378

# about an operation with time information and operation details.

379

"name": "A String", # ID of the trace which is "projects/<project_id>/traces/<trace_id>".

380

# trace_id is globally unique identifier for the trace. Common to all the

381

# spans. It is conceptually a 128-bit hex-encoded value.

},

],

}</pre>

</div>

<code class="details" id="listSpans">listSpans(name, pageToken=None, x__xgafv=None)</code>

389

<pre>Returns a list of spans within a trace.

390

391

Args:

392

name: string, ID of the span set where is "projects/<project_id>/traces/<trace_id>". (required)

393

pageToken: string, Token identifying the page of results to return. If provided, use the

394

value of the `page_token` field from a previous request. Optional.

395

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

402

403

{ # The response message for the 'ListSpans' method.

404

"nextPageToken": "A String", # If defined, indicates that there are more spans that match the request

405

# and that this value should be passed to the next request to continue

406

# retrieving additional spans.

407

"spans": [ # The requested spans if they are any in the specified trace.

408

{ # A span represents a single operation within a trace. Spans can be nested

409

# and form a trace tree. Often, a trace contains a root span that describes the

410

# end-to-end latency and, optionally, one or more subspans for

411

# its sub-operations. Spans do not need to be contiguous. There may be gaps

412

# between spans in a trace.

413

"status": { # The `Status` type defines a logical error model that is suitable for different # The final status of the Span. This is optional.

414

# programming environments, including REST APIs and RPC APIs. It is used by

415

# [gRPC](https://github.com/grpc). The error model is designed to be:

416

#

417

# - Simple to use and understand for most users

418

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error message,

423

# and error details. The error code should be an enum value of

424

# google.rpc.Code, but it may accept additional error codes if needed. The

425

# error message should be a developer-facing English message that helps

426

# developers *understand* and *resolve* the error. If a localized user-facing

427

# error message is needed, put the localized message in the error details or

428

# localize it in the client. The optional error details may contain arbitrary

429

# information about the error. There is a predefined set of error detail types

430

# 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

435

# is not necessarily the actual wire format. When the `Status` message is

436

# exposed in different client libraries and different wire protocols, it can be

437

# mapped differently. For example, it will likely be mapped to some exceptions

438

# 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

443

# environments, either with or without APIs, to provide a

444

# consistent developer experience across different environments.

445

#

446

# Example uses of this error model include:

447

#

448

# - Partial errors. If a service needs to return partial errors to the client,

449

# it may embed the `Status` in the normal response to indicate the partial

450

# errors.

451

#

452

# - Workflow errors. A typical workflow has multiple steps. Each step may

453

# have a `Status` message for error reporting purpose.

454

#

455

# - Batch operations. If a client uses batch request and batch response, the

456

# `Status` message should be used directly inside batch response, one for

457

# each error sub-response.

458

#

459

# - Asynchronous operations. If an API call embeds asynchronous operation

460

# results in its response, the status of those operations should be

461

# represented directly using the `Status` message.

462

#

463

# - Logging. If some API errors are stored in logs, the message `Status` could

464

# be used directly after any stripping needed for security/privacy reasons.

465

"message": "A String", # A developer-facing error message, which should be in English. Any

466

# user-facing error message should be localized and sent in the

467

# google.rpc.Status.details field, or localized by the client.

468

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

469

"details": [ # A list of messages that carry the error details. There will be a

470

# common set of message types for APIs to use.

471

{

472

"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. This is optional.

477

"stackTraceHashId": "A String", # User can choose to use their own hash function to hash large attributes to

478

# save network bandwidth and storage.

479

# Typical usage is to pass both stack_frame and stack_trace_hash_id initially

480

# to inform the storage of the mapping. And in subsequent calls, pass in

481

# stack_trace_hash_id only. User shall verify the hash value is

482

# successfully stored.

483

"stackFrame": [ # Stack frames of this stack trace.

484

{ # Presents a single stack frame in a stack trace.

485

"columnNumber": "A String", # Column number is important in JavaScript(anonymous functions),

486

# Might not be available in some languages.

487

"functionName": "A String", # Fully qualified names which uniquely identify function/method/etc.

488

"fileName": "A String", # File name of the frame.

489

"sourceVersion": "A String", # source_version is deployment specific. It might be

490

# better to be stored in deployment metadata.

491

"loadModule": { # Binary module. # Binary module the code is loaded from.

492

"buildId": "A String", # Build_id is a unique identifier for the module,

493

# usually a hash of its contents

494

"module": "A String", # E.g. main binary, kernel modules, and dynamic libraries

495

# such as libc.so, sharedlib.so

496

},

497

"lineNumber": "A String", # Line number of the frame.

498

"originalFunctionName": "A String", # Used when function name is ‘mangled’. Not guaranteed to be fully

499

# qualified but usually it is.

},

],

},

"hasRemoteParent": True or False, # True if this Span has a remote parent (is an RPC server Span).

504

"links": [ # A collection of links.

505

{ # Link one span with another which may be in a different Trace. Used (for

506

# example) in batching operations, where a single batch handler processes

507

# multiple requests from different traces.

508

"spanId": "A String", # The span identifier of the linked span.

509

"traceId": "A String", # The trace identifier of the linked span.

510

"type": "A String", # The type of the link.

511

},

512

],

513

"parentId": "A String", # ID of parent span. 0 or missing if this is a root span.

514

"localEndTime": "A String", # Local machine clock time from the UNIX epoch,

515

# at which span execution ended.

516

# On the server side these are the times when the server application

517

# handler finishes running.

518

"attributes": { # Properties of a span. Attributes at the span level.

519

# E.g.

520

# "/instance_id": "my-instance"

521

# "/zone": "us-central1-a"

522

# "/grpc/peer_address": "ip:port" (dns, etc.)

523

# "/grpc/deadline": "Duration"

524

# "/http/user_agent"

525

# "/http/request_bytes": 300

526

# "/http/response_bytes": 1200

527

# "/http/url": google.com/apis

528

# "/pid"

529

# "abc.com/myattribute": "my attribute value"

530

#

531

# Maximum length for attribute key is 128 characters, for string attribute

532

# value is 2K characters.

533

"a_key": { # Allowed attribute values.

534

"stringValue": "A String", # A string value.

535

"boolValue": True or False, # A boolean value.

536

"intValue": "A String", # An integer value.

537

},

538

},

539

"timeEvents": [ # A collection of time-stamped events.

540

{ # A time-stamped annotation in the Span.

541

"networkEvent": { # An event describing an RPC message sent/received on the network. # Optional field that can be used only for network events.

542

"messageSize": "A String", # Number of bytes send/receive.

543

"type": "A String", # Type of a NetworkEvent.

544

"kernelTime": "A String", # If available, this is the kernel time:

545

# For sent messages, this is the time at which the first bit was sent.

546

# For received messages, this is the time at which the last bit was

547

# received.

548

"messageId": "A String", # Every message has an identifier, which must be different from all the

549

# network messages in this span.

550

# This is especially important when the request/response are streamed.

551

},

552

"annotation": { # Text annotation with a set of attributes. # Optional field for user supplied <string, AttributeValue> map

553

"attributes": { # A set of attributes on the annotation.

554

"a_key": { # Allowed attribute values.

555

"stringValue": "A String", # A string value.

556

"boolValue": True or False, # A boolean value.

557

"intValue": "A String", # An integer value.

558

},

559

},

560

"description": "A String", # A user-supplied message describing the event.

561

},

562

"localTime": "A String", # The local machine absolute timestamp when this event happened.

563

},

564

],

565

"id": "A String", # Identifier for the span. Must be a 64-bit integer other than 0 and

566

# unique within a trace.

567

"localStartTime": "A String", # Local machine clock time from the UNIX epoch,

568

# at which span execution started.

569

# On the server side these are the times when the server application

570

# handler starts running.

571

"name": "A String", # Name of the span. The span name is sanitized and displayed in the

572

# Stackdriver Trace tool in the {% dynamic print site_values.console_name %}.

573

# The name may be a method name or some other per-call site name.

574

# For the same executable and the same call point, a best practice is

575

# to use a consistent name, which makes it easier to correlate

# cross-trace spans.

},

],

}</pre>

</div>

<code class="details" id="listSpans_next">listSpans_next(previous_request, previous_response)</code>

584

<pre>Retrieves the next page of results.

585

586

Args:

587

previous_request: The request for the previous page. (required)

588

previous_response: The response from the request for the previous page. (required)

589

590

Returns:

591

A request object that you can call 'execute()' on to request the next

592

page. Returns None if there are no more items in the collection.

</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

598

<pre>Retrieves the next page of results.

599

600

Args:

601

previous_request: The request for the previous page. (required)

602

previous_response: The response from the request for the previous page. (required)

603

604

Returns:

605

A request object that you can call 'execute()' on to request the next

606

page. Returns None if there are no more items in the collection.

</pre>

</div>

</body></html>