# Cloud Trace API . projects . traces

## Instance Methods

Returns the spans Resource.

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

### Method Details

`batchWrite(name, body=None, x__xgafv=None)`

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

    Args:
      name: string, Required. The name of the project where the spans belong. The format is
    `projects/[PROJECT_ID]`. (required)
      body: object, The request body.
        The object takes the form of:

    { # The request message for the `BatchWriteSpans` method.
        "spans": [ # Required. A list of new spans. The span names must not match existing
            # spans, or the results are undefined.
          { # 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 one or more subspans for
              # its sub-operations. A trace can also contain multiple root spans,
              # or none at all. Spans do not need to be contiguous&mdash;there may be
              # gaps or overlaps between spans in a trace.
            "displayName": { # Represents a string that might be shortened to a specified length. # Required. A description of the span's operation (up to 128 bytes).
                # Trace displays the description in the
                # Google Cloud Platform Console.
                # 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.
              "value": "A String", # The shortened string. For example, if the original string is 500
                  # bytes long and the limit of the string is 128 bytes, then
                  # `value` contains the first 128 bytes of the 500-byte string.
                  #
                  # Truncation always happens on a UTF8 character boundary. If there
                  # are multi-byte characters in the string, then the length of the
                  # shortened string might be less than the size limit.
              "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                  # value is 0, then the string was not shortened.
            },
            "links": { # A collection of links, which are references from this span to a span # Links associated with the span. You can have up to 128 links per Span.
                # in the same or different trace.
              "link": [ # A collection of links.
                { # A pointer from the current span to another span in the same trace or in a
                    # different trace. For example, this can be used in batching operations,
                    # where a single batch handler processes multiple requests from different
                    # traces or when the handler receives a request from a different project.
                  "traceId": "A String", # The [TRACE_ID] for a trace within a project.
                  "type": "A String", # The relationship of the current span relative to the linked span.
                  "spanId": "A String", # The [SPAN_ID] for a span within a trace.
                  "attributes": { # A set of attributes, each in the format `[KEY]:[VALUE]`. # A set of attributes on the link. You have have up to  32 attributes per
                      # link.
                    "attributeMap": { # The set of attributes. Each attribute's key can be up to 128 bytes
                        # long. The value can be a string up to 256 bytes, a signed 64-bit integer,
                        # or the Boolean values `true` and `false`. For example:
                        #
                        #     "/instance_id": { "string_value": { "value": "my-instance" } }
                        #     "/http/request_bytes": { "int_value": 300 }
                        #     "abc.com/myattribute": { "bool_value": false }
                      "a_key": { # The allowed types for [VALUE] in a `[KEY]:[VALUE]` attribute.
                        "stringValue": { # Represents a string that might be shortened to a specified length. # A string up to 256 bytes long.
                          "value": "A String", # The shortened string. For example, if the original string is 500
                              # bytes long and the limit of the string is 128 bytes, then
                              # `value` contains the first 128 bytes of the 500-byte string.
                              #
                              # Truncation always happens on a UTF8 character boundary. If there
                              # are multi-byte characters in the string, then the length of the
                              # shortened string might be less than the size limit.
                          "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                              # value is 0, then the string was not shortened.
                        },
                        "intValue": "A String", # A 64-bit signed integer.
                        "boolValue": True or False, # A Boolean value represented by `true` or `false`.
                      },
                    },
                    "droppedAttributesCount": 42, # The number of attributes that were discarded. Attributes can be discarded
                        # because their keys are too long or because there are too many attributes.
                        # If this value is 0 then all attributes are valid.
                  },
                },
              ],
              "droppedLinksCount": 42, # The number of dropped links after the maximum size was enforced. If
                  # this value is 0, then no links were dropped.
            },
            "parentSpanId": "A String", # The [SPAN_ID] of this span's parent span. If this is a root span,
                # then this field must be empty.
            "timeEvents": { # A collection of `TimeEvent`s. A `TimeEvent` is a time-stamped annotation # A set of time events. You can have up to 32 annotations and 128 message
                # events per span.
                # on the span, consisting of either user-supplied key:value pairs, or
                # details of a message sent/received between Spans.
              "droppedMessageEventsCount": 42, # The number of dropped message events in all the included time events.
                  # If the value is 0, then no message events were dropped.
              "timeEvent": [ # A collection of `TimeEvent`s.
                { # A time-stamped annotation or message event in the Span.
                  "time": "A String", # The timestamp indicating the time the event occurred.
                  "annotation": { # Text annotation with a set of attributes. # Text annotation with a set of attributes.
                    "description": { # Represents a string that might be shortened to a specified length. # A user-supplied message describing the event. The maximum length for
                        # the description is 256 bytes.
                      "value": "A String", # The shortened string. For example, if the original string is 500
                          # bytes long and the limit of the string is 128 bytes, then
                          # `value` contains the first 128 bytes of the 500-byte string.
                          #
                          # Truncation always happens on a UTF8 character boundary. If there
                          # are multi-byte characters in the string, then the length of the
                          # shortened string might be less than the size limit.
                      "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                          # value is 0, then the string was not shortened.
                    },
                    "attributes": { # A set of attributes, each in the format `[KEY]:[VALUE]`. # A set of attributes on the annotation. You can have up to 4 attributes
                        # per Annotation.
                      "attributeMap": { # The set of attributes. Each attribute's key can be up to 128 bytes
                          # long. The value can be a string up to 256 bytes, a signed 64-bit integer,
                          # or the Boolean values `true` and `false`. For example:
                          #
                          #     "/instance_id": { "string_value": { "value": "my-instance" } }
                          #     "/http/request_bytes": { "int_value": 300 }
                          #     "abc.com/myattribute": { "bool_value": false }
                        "a_key": { # The allowed types for [VALUE] in a `[KEY]:[VALUE]` attribute.
                          "stringValue": { # Represents a string that might be shortened to a specified length. # A string up to 256 bytes long.
                            "value": "A String", # The shortened string. For example, if the original string is 500
                                # bytes long and the limit of the string is 128 bytes, then
                                # `value` contains the first 128 bytes of the 500-byte string.
                                #
                                # Truncation always happens on a UTF8 character boundary. If there
                                # are multi-byte characters in the string, then the length of the
                                # shortened string might be less than the size limit.
                            "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                                # value is 0, then the string was not shortened.
                          },
                          "intValue": "A String", # A 64-bit signed integer.
                          "boolValue": True or False, # A Boolean value represented by `true` or `false`.
                        },
                      },
                      "droppedAttributesCount": 42, # The number of attributes that were discarded. Attributes can be discarded
                          # because their keys are too long or because there are too many attributes.
                          # If this value is 0 then all attributes are valid.
                    },
                  },
                  "messageEvent": { # An event describing a message sent/received between Spans. # An event describing a message sent/received between Spans.
                    "compressedSizeBytes": "A String", # The number of compressed bytes sent or received. If missing assumed to
                        # be the same size as uncompressed.
                    "uncompressedSizeBytes": "A String", # The number of uncompressed bytes sent or received.
                    "id": "A String", # An identifier for the MessageEvent's message that can be used to match
                        # SENT and RECEIVED MessageEvents. It is recommended to be unique within
                        # a Span.
                    "type": "A String", # Type of MessageEvent. Indicates whether the message was sent or
                        # received.
                  },
                },
              ],
              "droppedAnnotationsCount": 42, # The number of dropped annotations in all the included time events.
                  # If the value is 0, then no annotations were dropped.
            },
            "name": "A String", # Required. The resource name of the span in the following format:
                #
                #     projects/[PROJECT_ID]/traces/[TRACE_ID]/spans/SPAN_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. It should not
                # be zero.
            "status": { # The `Status` type defines a logical error model that is suitable for # Optional. The final status for this span.
                # different programming environments, including REST APIs and RPC APIs. It is
                # used by [gRPC](https://github.com/grpc). Each `Status` message contains
                # three pieces of data: error code, error message, and error details.
                #
                # You can find out more about this error model and how to work with it in the
                # [API Design Guide](https://cloud.google.com/apis/design/errors).
              "details": [ # A list of messages that carry the error details.  There is a common set of
                  # message types for APIs to use.
                {
                  "a_key": "", # Properties of the object. Contains field @type with type URL.
                },
              ],
              "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.
            },
            "childSpanCount": 42, # Optional. The number of child spans that were generated while this span
                # was active. If set, allows implementation to detect missing child spans.
            "stackTrace": { # A call stack appearing 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 occurrence 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`.
              "stackFrames": { # A collection of stack frames, which can be truncated. # Stack frames in this stack trace. A maximum of 128 frames are allowed.
                "droppedFramesCount": 42, # The number of stack frames that were dropped because there
                    # were too many stack frames.
                    # If this value is 0, then no stack frames were dropped.
                "frame": [ # Stack frames in this call stack.
                  { # Represents a single stack frame in a stack trace.
                    "lineNumber": "A String", # The line number in `file_name` where the function call appears.
                    "functionName": { # Represents a string that might be shortened to a specified length. # The fully-qualified name that uniquely identifies the function or
                        # method that is active in this frame (up to 1024 bytes).
                      "value": "A String", # The shortened string. For example, if the original string is 500
                          # bytes long and the limit of the string is 128 bytes, then
                          # `value` contains the first 128 bytes of the 500-byte string.
                          #
                          # Truncation always happens on a UTF8 character boundary. If there
                          # are multi-byte characters in the string, then the length of the
                          # shortened string might be less than the size limit.
                      "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                          # value is 0, then the string was not shortened.
                    },
                    "sourceVersion": { # Represents a string that might be shortened to a specified length. # The version of the deployed source code (up to 128 bytes).
                      "value": "A String", # The shortened string. For example, if the original string is 500
                          # bytes long and the limit of the string is 128 bytes, then
                          # `value` contains the first 128 bytes of the 500-byte string.
                          #
                          # Truncation always happens on a UTF8 character boundary. If there
                          # are multi-byte characters in the string, then the length of the
                          # shortened string might be less than the size limit.
                      "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                          # value is 0, then the string was not shortened.
                    },
                    "loadModule": { # Binary module. # The binary module from where the code was loaded.
                      "buildId": { # Represents a string that might be shortened to a specified length. # A unique identifier for the module, usually a hash of its
                          # contents (up to 128 bytes).
                        "value": "A String", # The shortened string. For example, if the original string is 500
                            # bytes long and the limit of the string is 128 bytes, then
                            # `value` contains the first 128 bytes of the 500-byte string.
                            #
                            # Truncation always happens on a UTF8 character boundary. If there
                            # are multi-byte characters in the string, then the length of the
                            # shortened string might be less than the size limit.
                        "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                            # value is 0, then the string was not shortened.
                      },
                      "module": { # Represents a string that might be shortened to a specified length. # For example: main binary, kernel modules, and dynamic libraries
                          # such as libc.so, sharedlib.so (up to 256 bytes).
                        "value": "A String", # The shortened string. For example, if the original string is 500
                            # bytes long and the limit of the string is 128 bytes, then
                            # `value` contains the first 128 bytes of the 500-byte string.
                            #
                            # Truncation always happens on a UTF8 character boundary. If there
                            # are multi-byte characters in the string, then the length of the
                            # shortened string might be less than the size limit.
                        "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                            # value is 0, then the string was not shortened.
                      },
                    },
                    "columnNumber": "A String", # The column number where the function call appears, if available.
                        # This is important in JavaScript because of its anonymous functions.
                    "originalFunctionName": { # Represents a string that might be shortened to a specified length. # An un-mangled function name, if `function_name` is
                        # [mangled](http://www.avabodh.com/cxxin/namemangling.html). The name can
                        # be fully-qualified (up to 1024 bytes).
                      "value": "A String", # The shortened string. For example, if the original string is 500
                          # bytes long and the limit of the string is 128 bytes, then
                          # `value` contains the first 128 bytes of the 500-byte string.
                          #
                          # Truncation always happens on a UTF8 character boundary. If there
                          # are multi-byte characters in the string, then the length of the
                          # shortened string might be less than the size limit.
                      "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                          # value is 0, then the string was not shortened.
                    },
                    "fileName": { # Represents a string that might be shortened to a specified length. # The name of the source file where the function call appears (up to 256
                        # bytes).
                      "value": "A String", # The shortened string. For example, if the original string is 500
                          # bytes long and the limit of the string is 128 bytes, then
                          # `value` contains the first 128 bytes of the 500-byte string.
                          #
                          # Truncation always happens on a UTF8 character boundary. If there
                          # are multi-byte characters in the string, then the length of the
                          # shortened string might be less than the size limit.
                      "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                          # value is 0, then the string was not shortened.
                    },
                  },
                ],
              },
            },
            "attributes": { # A set of attributes, each in the format `[KEY]:[VALUE]`. # A set of attributes on the span. You can have up to 32 attributes per
                # span.
              "attributeMap": { # The set of attributes. Each attribute's key can be up to 128 bytes
                  # long. The value can be a string up to 256 bytes, a signed 64-bit integer,
                  # or the Boolean values `true` and `false`. For example:
                  #
                  #     "/instance_id": { "string_value": { "value": "my-instance" } }
                  #     "/http/request_bytes": { "int_value": 300 }
                  #     "abc.com/myattribute": { "bool_value": false }
                "a_key": { # The allowed types for [VALUE] in a `[KEY]:[VALUE]` attribute.
                  "stringValue": { # Represents a string that might be shortened to a specified length. # A string up to 256 bytes long.
                    "value": "A String", # The shortened string. For example, if the original string is 500
                        # bytes long and the limit of the string is 128 bytes, then
                        # `value` contains the first 128 bytes of the 500-byte string.
                        #
                        # Truncation always happens on a UTF8 character boundary. If there
                        # are multi-byte characters in the string, then the length of the
                        # shortened string might be less than the size limit.
                    "truncatedByteCount": 42, # The number of bytes removed from the original string. If this
                        # value is 0, then the string was not shortened.
                  },
                  "intValue": "A String", # A 64-bit signed integer.
                  "boolValue": True or False, # A Boolean value represented by `true` or `false`.
                },
              },
              "droppedAttributesCount": 42, # The number of attributes that were discarded. Attributes can be discarded
                  # because their keys are too long or because there are too many attributes.
                  # If this value is 0 then all attributes are valid.
            },
            "spanKind": "A String", # Optional. Distinguishes between spans generated in a particular context. For example,
                # two spans with the same name may be distinguished using `CLIENT` (caller)
                # and `SERVER` (callee) to identify an RPC call.
            "endTime": "A String", # Required. 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.
            "startTime": "A String", # Required. 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.
            "spanId": "A String", # Required. The [SPAN_ID] portion of the span's resource name.
            "sameProcessAsParentSpan": True or False, # Optional. Set this parameter to indicate whether this span is in
                # the same process as its parent. If you do not set this parameter,
                # Trace is unable to take advantage of this helpful information.
          },
        ],
      }

      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 `{}`.
      }