{ "swagger": "2.0", "info": { "title": "opencensus/proto/agent/trace/v1/trace_service.proto", "version": "version not set" }, "tags": [ { "name": "TraceService" } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/v1/trace": { "post": { "summary": "For performance reasons, it is recommended to keep this RPC\nalive for the entire life of the application.", "operationId": "TraceService_Export", "responses": { "200": { "description": "A successful response.(streaming responses)", "schema": { "type": "object", "properties": { "result": { "$ref": "#/definitions/v1ExportTraceServiceResponse" }, "error": { "$ref": "#/definitions/googlerpcStatus" } }, "title": "Stream result of v1ExportTraceServiceResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/googlerpcStatus" } } }, "parameters": [ { "name": "body", "description": " (streaming inputs)", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1ExportTraceServiceRequest" } } ], "tags": [ "TraceService" ] } } }, "definitions": { "ConstantSamplerConstantDecision": { "type": "string", "enum": [ "ALWAYS_OFF", "ALWAYS_ON", "ALWAYS_PARENT" ], "default": "ALWAYS_OFF", "description": "How spans should be sampled:\n- Always off\n- Always on\n- Always follow the parent Span's decision (off if no parent)." }, "LibraryInfoLanguage": { "type": "string", "enum": [ "LANGUAGE_UNSPECIFIED", "CPP", "C_SHARP", "ERLANG", "GO_LANG", "JAVA", "NODE_JS", "PHP", "PYTHON", "RUBY", "WEB_JS" ], "default": "LANGUAGE_UNSPECIFIED" }, "SpanAttributes": { "type": "object", "properties": { "attributeMap": { "type": "object", "additionalProperties": { "$ref": "#/definitions/v1AttributeValue" }, "description": "\"/http/user_agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36\"\n \"/http/server_latency\": 300\n \"abc.com/myattribute\": true\n \"abc.com/score\": 10.239", "title": "The set of attributes. The value can be a string, an integer, a double\nor the Boolean values `true` or `false`. Note, global attributes like \nserver name can be set as tags using resource API. Examples of attributes:" }, "droppedAttributesCount": { "type": "integer", "format": "int32", "description": "The number of attributes that were discarded. Attributes can be discarded\nbecause their keys are too long or because there are too many attributes.\nIf this value is 0, then no attributes were dropped." } }, "description": "A set of attributes, each with a key and a value." }, "SpanLink": { "type": "object", "properties": { "traceId": { "type": "string", "format": "byte", "description": "A unique identifier of a trace that this linked span is part of. The ID is a \n16-byte array." }, "spanId": { "type": "string", "format": "byte", "description": "A unique identifier for the linked span. The ID is an 8-byte array." }, "type": { "$ref": "#/definitions/SpanLinkType", "description": "The relationship of the current span relative to the linked span." }, "attributes": { "$ref": "#/definitions/SpanAttributes", "description": "A set of attributes on the link." }, "tracestate": { "$ref": "#/definitions/SpanTracestate", "description": "The Tracestate associated with the link." } }, "description": "A pointer from the current span to another span in the same trace or in a\ndifferent trace. For example, this can be used in batching operations,\nwhere a single batch handler processes multiple requests from different\ntraces or when the handler receives a request from a different project." }, "SpanLinkType": { "type": "string", "enum": [ "TYPE_UNSPECIFIED", "CHILD_LINKED_SPAN", "PARENT_LINKED_SPAN" ], "default": "TYPE_UNSPECIFIED", "description": "The relationship of the current span relative to the linked span: child,\nparent, or unspecified.\n\n - TYPE_UNSPECIFIED: The relationship of the two spans is unknown, or known but other\nthan parent-child.\n - CHILD_LINKED_SPAN: The linked span is a child of the current span.\n - PARENT_LINKED_SPAN: The linked span is a parent of the current span." }, "SpanLinks": { "type": "object", "properties": { "link": { "type": "array", "items": { "$ref": "#/definitions/SpanLink" }, "description": "A collection of links." }, "droppedLinksCount": { "type": "integer", "format": "int32", "description": "The number of dropped links after the maximum size was enforced. If\nthis value is 0, then no links were dropped." } }, "description": "A collection of links, which are references from this span to a span\nin the same or different trace." }, "SpanSpanKind": { "type": "string", "enum": [ "SPAN_KIND_UNSPECIFIED", "SERVER", "CLIENT" ], "default": "SPAN_KIND_UNSPECIFIED", "description": "Type of span. Can be used to specify additional relationships between spans\nin addition to a parent/child relationship.\n\n - SPAN_KIND_UNSPECIFIED: Unspecified.\n - SERVER: Indicates that the span covers server-side handling of an RPC or other\nremote network request.\n - CLIENT: Indicates that the span covers the client-side wrapper around an RPC or\nother remote request." }, "SpanTimeEvent": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "The time the event occurred." }, "annotation": { "$ref": "#/definitions/TimeEventAnnotation", "description": "A text annotation with a set of attributes." }, "messageEvent": { "$ref": "#/definitions/TimeEventMessageEvent", "description": "An event describing a message sent/received between Spans." } }, "description": "A time-stamped annotation or message event in the Span." }, "SpanTimeEvents": { "type": "object", "properties": { "timeEvent": { "type": "array", "items": { "$ref": "#/definitions/SpanTimeEvent" }, "description": "A collection of `TimeEvent`s." }, "droppedAnnotationsCount": { "type": "integer", "format": "int32", "description": "The number of dropped annotations in all the included time events.\nIf the value is 0, then no annotations were dropped." }, "droppedMessageEventsCount": { "type": "integer", "format": "int32", "description": "The number of dropped message events in all the included time events.\nIf the value is 0, then no message events were dropped." } }, "description": "A collection of `TimeEvent`s. A `TimeEvent` is a time-stamped annotation\non the span, consisting of either user-supplied key-value pairs, or\ndetails of a message sent/received between Spans." }, "SpanTracestate": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/TracestateEntry" }, "description": "A list of entries that represent the Tracestate." } }, "description": "This field conveys information about request position in multiple distributed tracing graphs.\nIt is a list of Tracestate.Entry with a maximum of 32 members in the list.\n\nSee the https://github.com/w3c/distributed-tracing for more details about this field." }, "StackTraceStackFrame": { "type": "object", "properties": { "functionName": { "$ref": "#/definitions/v1TruncatableString", "description": "The fully-qualified name that uniquely identifies the function or\nmethod that is active in this frame." }, "originalFunctionName": { "$ref": "#/definitions/v1TruncatableString", "description": "An un-mangled function name, if `function_name` is\n[mangled](http://www.avabodh.com/cxxin/namemangling.html). The name can\nbe fully qualified." }, "fileName": { "$ref": "#/definitions/v1TruncatableString", "description": "The name of the source file where the function call appears." }, "lineNumber": { "type": "string", "format": "int64", "description": "The line number in `file_name` where the function call appears." }, "columnNumber": { "type": "string", "format": "int64", "description": "The column number where the function call appears, if available.\nThis is important in JavaScript because of its anonymous functions." }, "loadModule": { "$ref": "#/definitions/v1Module", "description": "The binary module from where the code was loaded." }, "sourceVersion": { "$ref": "#/definitions/v1TruncatableString", "description": "The version of the deployed source code." } }, "description": "A single stack frame in a stack trace." }, "StackTraceStackFrames": { "type": "object", "properties": { "frame": { "type": "array", "items": { "$ref": "#/definitions/StackTraceStackFrame" }, "description": "Stack frames in this call stack." }, "droppedFramesCount": { "type": "integer", "format": "int32", "description": "The number of stack frames that were dropped because there\nwere too many stack frames.\nIf this value is 0, then no stack frames were dropped." } }, "description": "A collection of stack frames, which can be truncated." }, "TimeEventAnnotation": { "type": "object", "properties": { "description": { "$ref": "#/definitions/v1TruncatableString", "description": "A user-supplied message describing the event." }, "attributes": { "$ref": "#/definitions/SpanAttributes", "description": "A set of attributes on the annotation." } }, "description": "A text annotation with a set of attributes." }, "TimeEventMessageEvent": { "type": "object", "properties": { "type": { "$ref": "#/definitions/TimeEventMessageEventType", "description": "The type of MessageEvent. Indicates whether the message was sent or\nreceived." }, "id": { "type": "string", "format": "uint64", "description": "An identifier for the MessageEvent's message that can be used to match\nSENT and RECEIVED MessageEvents. For example, this field could\nrepresent a sequence ID for a streaming RPC. It is recommended to be\nunique within a Span." }, "uncompressedSize": { "type": "string", "format": "uint64", "description": "The number of uncompressed bytes sent or received." }, "compressedSize": { "type": "string", "format": "uint64", "description": "The number of compressed bytes sent or received. If zero, assumed to\nbe the same size as uncompressed." } }, "description": "An event describing a message sent/received between Spans." }, "TimeEventMessageEventType": { "type": "string", "enum": [ "TYPE_UNSPECIFIED", "SENT", "RECEIVED" ], "default": "TYPE_UNSPECIFIED", "description": "Indicates whether the message was sent or received.\n\n - TYPE_UNSPECIFIED: Unknown event type.\n - SENT: Indicates a sent message.\n - RECEIVED: Indicates a received message." }, "TracestateEntry": { "type": "object", "properties": { "key": { "type": "string", "description": "The key must begin with a lowercase letter, and can only contain\nlowercase letters 'a'-'z', digits '0'-'9', underscores '_', dashes\n'-', asterisks '*', and forward slashes '/'." }, "value": { "type": "string", "description": "The value is opaque string up to 256 characters printable ASCII\nRFC0020 characters (i.e., the range 0x20 to 0x7E) except ',' and '='.\nNote that this also excludes tabs, newlines, carriage returns, etc." } } }, "googlerpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/definitions/protobufAny" } } } }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "tracev1Status": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "description": "The status code. This is optional field. It is safe to assume 0 (OK)\nwhen not set." }, "message": { "type": "string", "description": "A developer-facing error message, which should be in English." } }, "description": "The `Status` type defines a logical error model that is suitable for different\nprogramming environments, including REST APIs and RPC APIs. This proto's fields\nare a subset of those of\n[google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto),\nwhich is used by [gRPC](https://github.com/grpc)." }, "v1AttributeValue": { "type": "object", "properties": { "stringValue": { "$ref": "#/definitions/v1TruncatableString", "description": "A string up to 256 bytes long." }, "intValue": { "type": "string", "format": "int64", "description": "A 64-bit signed integer." }, "boolValue": { "type": "boolean", "description": "A Boolean value represented by `true` or `false`." }, "doubleValue": { "type": "number", "format": "double", "description": "A double value." } }, "description": "The value of an Attribute." }, "v1ConstantSampler": { "type": "object", "properties": { "decision": { "$ref": "#/definitions/ConstantSamplerConstantDecision" } }, "description": "Sampler that always makes a constant decision on span sampling." }, "v1ExportTraceServiceRequest": { "type": "object", "properties": { "node": { "$ref": "#/definitions/v1Node", "description": "This is required only in the first message on the stream or if the\nprevious sent ExportTraceServiceRequest message has a different Node (e.g.\nwhen the same RPC is used to send Spans from multiple Applications)." }, "spans": { "type": "array", "items": { "$ref": "#/definitions/v1Span" }, "description": "A list of Spans that belong to the last received Node." }, "resource": { "$ref": "#/definitions/v1Resource", "description": "The resource for the spans in this message that do not have an explicit\nresource set.\nIf unset, the most recently set resource in the RPC stream applies. It is\nvalid to never be set within a stream, e.g. when no resource info is known." } } }, "v1ExportTraceServiceResponse": { "type": "object" }, "v1LibraryInfo": { "type": "object", "properties": { "language": { "$ref": "#/definitions/LibraryInfoLanguage", "description": "Language of OpenCensus Library." }, "exporterVersion": { "type": "string", "description": "Version of Agent exporter of Library." }, "coreLibraryVersion": { "type": "string", "description": "Version of OpenCensus Library." } }, "description": "Information on OpenCensus Library." }, "v1Module": { "type": "object", "properties": { "module": { "$ref": "#/definitions/v1TruncatableString", "description": "TODO: document the meaning of this field.\nFor example: main binary, kernel modules, and dynamic libraries\nsuch as libc.so, sharedlib.so." }, "buildId": { "$ref": "#/definitions/v1TruncatableString", "description": "A unique identifier for the module, usually a hash of its\ncontents." } }, "description": "A description of a binary module." }, "v1Node": { "type": "object", "properties": { "identifier": { "$ref": "#/definitions/v1ProcessIdentifier", "description": "Identifier that uniquely identifies a process within a VM/container." }, "libraryInfo": { "$ref": "#/definitions/v1LibraryInfo", "description": "Information on the OpenCensus Library that initiates the stream." }, "serviceInfo": { "$ref": "#/definitions/v1ServiceInfo", "description": "Additional information on service." }, "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional attributes." } }, "title": "Identifier metadata of the Node that produces the span or tracing data.\nNote, this is not the metadata about the Node or service that is described by associated spans.\nIn the future we plan to extend the identifier proto definition to support\nadditional information (e.g cloud id, etc.)" }, "v1ProbabilitySampler": { "type": "object", "properties": { "samplingProbability": { "type": "number", "format": "double", "description": "The desired probability of sampling. Must be within [0.0, 1.0]." } }, "description": "Sampler that tries to uniformly sample traces with a given probability.\nThe probability of sampling a trace is equal to that of the specified probability." }, "v1ProcessIdentifier": { "type": "object", "properties": { "hostName": { "type": "string", "description": "The host name. Usually refers to the machine/container name.\nFor example: os.Hostname() in Go, socket.gethostname() in Python." }, "pid": { "type": "integer", "format": "int64", "description": "Process id." }, "startTimestamp": { "type": "string", "format": "date-time", "description": "Start time of this ProcessIdentifier. Represented in epoch time." } }, "description": "Identifier that uniquely identifies a process within a VM/container." }, "v1RateLimitingSampler": { "type": "object", "properties": { "qps": { "type": "string", "format": "int64", "description": "Rate per second." } }, "description": "Sampler that tries to sample with a rate per time window." }, "v1Resource": { "type": "object", "properties": { "type": { "type": "string", "description": "Type identifier for the resource." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Set of labels that describe the resource." } }, "description": "Resource information." }, "v1ServiceInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the service." } }, "description": "Additional service information." }, "v1Span": { "type": "object", "properties": { "traceId": { "type": "string", "format": "byte", "description": "A unique identifier for a trace. All spans from the same trace share\nthe same `trace_id`. The ID is a 16-byte array. An ID with all zeroes\nis considered invalid.\n\nThis field is semantically required. Receiver should generate new\nrandom trace_id if empty or invalid trace_id was received.\n\nThis field is required." }, "spanId": { "type": "string", "format": "byte", "description": "A unique identifier for a span within a trace, assigned when the span\nis created. The ID is an 8-byte array. An ID with all zeroes is considered\ninvalid.\n\nThis field is semantically required. Receiver should generate new\nrandom span_id if empty or invalid span_id was received.\n\nThis field is required." }, "tracestate": { "$ref": "#/definitions/SpanTracestate", "description": "The Tracestate on the span." }, "parentSpanId": { "type": "string", "format": "byte", "description": "The `span_id` of this span's parent span. If this is a root span, then this\nfield must be empty. The ID is an 8-byte array." }, "name": { "$ref": "#/definitions/v1TruncatableString", "description": "A description of the span's operation.\n\nFor example, the name can be a qualified method name or a file name\nand a line number where the operation is called. A best practice is to use\nthe same display name at the same call point in an application.\nThis makes it easier to correlate spans in different traces.\n\nThis field is semantically required to be set to non-empty string.\nWhen null or empty string received - receiver may use string \"name\"\nas a replacement. There might be smarted algorithms implemented by\nreceiver to fix the empty span name.\n\nThis field is required." }, "kind": { "$ref": "#/definitions/SpanSpanKind", "description": "Distinguishes between spans generated in a particular context. For example,\ntwo spans with the same name may be distinguished using `CLIENT` (caller)\nand `SERVER` (callee) to identify queueing latency associated with the span." }, "startTime": { "type": "string", "format": "date-time", "description": "The start time of the span. On the client side, this is the time kept by\nthe local machine where the span execution starts. On the server side, this\nis the time when the server's application handler starts running.\n\nThis field is semantically required. When not set on receive -\nreceiver should set it to the value of end_time field if it was\nset. Or to the current time if neither was set. It is important to\nkeep end_time \u003e start_time for consistency.\n\nThis field is required." }, "endTime": { "type": "string", "format": "date-time", "description": "The end time of the span. On the client side, this is the time kept by\nthe local machine where the span execution ends. On the server side, this\nis the time when the server application handler stops running.\n\nThis field is semantically required. When not set on receive -\nreceiver should set it to start_time value. It is important to\nkeep end_time \u003e start_time for consistency.\n\nThis field is required." }, "attributes": { "$ref": "#/definitions/SpanAttributes", "description": "A set of attributes on the span." }, "stackTrace": { "$ref": "#/definitions/v1StackTrace", "description": "A stack trace captured at the start of the span." }, "timeEvents": { "$ref": "#/definitions/SpanTimeEvents", "description": "The included time events." }, "links": { "$ref": "#/definitions/SpanLinks", "description": "The included links." }, "status": { "$ref": "#/definitions/tracev1Status", "description": "An optional final status for this span. Semantically when Status\nwasn't set it is means span ended without errors and assume\nStatus.Ok (code = 0)." }, "resource": { "$ref": "#/definitions/v1Resource", "description": "An optional resource that is associated with this span. If not set, this span \nshould be part of a batch that does include the resource information, unless resource \ninformation is unknown." }, "sameProcessAsParentSpan": { "type": "boolean", "description": "A highly recommended but not required flag that identifies when a\ntrace crosses a process boundary. True when the parent_span belongs\nto the same process as the current span. This flag is most commonly\nused to indicate the need to adjust time as clocks in different\nprocesses may not be synchronized." }, "childSpanCount": { "type": "integer", "format": "int64", "description": "An optional number of child spans that were generated while this span\nwas active. If set, allows an implementation to detect missing child spans." } }, "description": "A span represents a single operation within a trace. Spans can be\nnested to form a trace tree. Spans may also be linked to other spans\nfrom the same or different trace. And form graphs. Often, a trace\ncontains a root span that describes the end-to-end latency, and one\nor more subspans for its sub-operations. A trace can also contain\nmultiple root spans, or none at all. Spans do not need to be\ncontiguous - there may be gaps or overlaps between spans in a trace.\n\nThe next id is 17.\nTODO(bdrutu): Add an example." }, "v1StackTrace": { "type": "object", "properties": { "stackFrames": { "$ref": "#/definitions/StackTraceStackFrames", "description": "Stack frames in this stack trace." }, "stackTraceHashId": { "type": "string", "format": "uint64", "description": "The hash ID is used to conserve network bandwidth for duplicate\nstack traces within a single trace.\n\nOften multiple spans will have identical stack traces.\nThe first occurrence of a stack trace should contain both\n`stack_frames` and a value in `stack_trace_hash_id`.\n\nSubsequent spans within the same request can refer\nto that stack trace by setting only `stack_trace_hash_id`.\n\nTODO: describe how to deal with the case where stack_trace_hash_id is\nzero because it was not set." } }, "description": "The call stack which originated this span." }, "v1TraceConfig": { "type": "object", "properties": { "probabilitySampler": { "$ref": "#/definitions/v1ProbabilitySampler" }, "constantSampler": { "$ref": "#/definitions/v1ConstantSampler" }, "rateLimitingSampler": { "$ref": "#/definitions/v1RateLimitingSampler" }, "maxNumberOfAttributes": { "type": "string", "format": "int64", "description": "The global default max number of attributes per span." }, "maxNumberOfAnnotations": { "type": "string", "format": "int64", "description": "The global default max number of annotation events per span." }, "maxNumberOfMessageEvents": { "type": "string", "format": "int64", "description": "The global default max number of message events per span." }, "maxNumberOfLinks": { "type": "string", "format": "int64", "description": "The global default max number of link entries per span." } }, "description": "Global configuration of the trace service. All fields must be specified, or\nthe default (zero) values will be used for each type." }, "v1TruncatableString": { "type": "object", "properties": { "value": { "type": "string", "description": "The shortened string. For example, if the original string was 500 bytes long and\nthe limit of the string was 128 bytes, then this value contains the first 128\nbytes of the 500-byte string. Note that truncation always happens on a\ncharacter boundary, to ensure that a truncated string is still valid UTF-8.\nBecause it may contain multi-byte characters, the size of the truncated string\nmay be less than the truncation limit." }, "truncatedByteCount": { "type": "integer", "format": "int32", "description": "The number of bytes removed from the original string. If this\nvalue is 0, then the string was not shortened." } }, "description": "A string that might be shortened to a specified length." }, "v1UpdatedLibraryConfig": { "type": "object", "properties": { "node": { "$ref": "#/definitions/v1Node", "description": "This field is ignored when the RPC is used to configure only one Application.\nThis is required only in the first message on the stream or if the\nprevious sent UpdatedLibraryConfig message has a different Node." }, "config": { "$ref": "#/definitions/v1TraceConfig", "description": "Requested updated configuration." } } } } }