Debian Codegraph @

opentelemetry/proto/trace/v1/trace.proto

raw
1 // Copyright 2019, OpenTelemetry Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 syntax = "proto3";
16
17 package opentelemetry.proto.trace.v1;
18
19 import "opentelemetry/proto/common/v1/common.proto";
20 import "opentelemetry/proto/resource/v1/resource.proto";
21
22 option csharp_namespace = "OpenTelemetry.Proto.Trace.V1";
23 option java_multiple_files = true;
24 option java_package = "io.opentelemetry.proto.trace.v1";
25 option java_outer_classname = "TraceProto";
26 option go_package = "go.opentelemetry.io/proto/otlp/trace/v1";
27
28 // TracesData represents the traces data that can be stored in a persistent storage,
29 // OR can be embedded by other protocols that transfer OTLP traces data but do
30 // not implement the OTLP protocol.
31 //
32 // The main difference between this message and collector protocol is that
33 // in this message there will not be any "control" or "metadata" specific to
34 // OTLP protocol.
35 //
36 // When new fields are added into this message, the OTLP request MUST be updated
37 // as well.
38 message TracesData {
39 // An array of ResourceSpans.
40 // For data coming from a single resource this array will typically contain
41 // one element. Intermediary nodes that receive data from multiple origins
42 // typically batch the data before forwarding further and in that case this
43 // array will contain multiple elements.
44 repeated ResourceSpans resource_spans = 1;
45 }
46
47 // A collection of ScopeSpans from a Resource.
48 message ResourceSpans {
49 reserved 1000;
50
51 // The resource for the spans in this message.
52 // If this field is not set then no resource info is known.
53 opentelemetry.proto.resource.v1.Resource resource = 1;
54
55 // A list of ScopeSpans that originate from a resource.
56 repeated ScopeSpans scope_spans = 2;
57
58 // The Schema URL, if known. This is the identifier of the Schema that the resource data
59 // is recorded in. Notably, the last part of the URL path is the version number of the
60 // schema: http[s]://server[:port]/path/<version>. To learn more about Schema URL see
61 // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
62 // This schema_url applies to the data in the "resource" field. It does not apply
63 // to the data in the "scope_spans" field which have their own schema_url field.
64 string schema_url = 3;
65 }
66
67 // A collection of Spans produced by an InstrumentationScope.
68 message ScopeSpans {
69 // The instrumentation scope information for the spans in this message.
70 // Semantically when InstrumentationScope isn't set, it is equivalent with
71 // an empty instrumentation scope name (unknown).
72 opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
73
74 // A list of Spans that originate from an instrumentation scope.
75 repeated Span spans = 2;
76
77 // The Schema URL, if known. This is the identifier of the Schema that the span data
78 // is recorded in. Notably, the last part of the URL path is the version number of the
79 // schema: http[s]://server[:port]/path/<version>. To learn more about Schema URL see
80 // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
81 // This schema_url applies to all spans and span events in the "spans" field.
82 string schema_url = 3;
83 }
84
85 // A Span represents a single operation performed by a single component of the system.
86 //
87 // The next available field id is 17.
88 message Span {
89 // A unique identifier for a trace. All spans from the same trace share
90 // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR
91 // of length other than 16 bytes is considered invalid (empty string in OTLP/JSON
92 // is zero-length and thus is also invalid).
93 //
94 // This field is required.
95 bytes trace_id = 1;
96
97 // A unique identifier for a span within a trace, assigned when the span
98 // is created. The ID is an 8-byte array. An ID with all zeroes OR of length
99 // other than 8 bytes is considered invalid (empty string in OTLP/JSON
100 // is zero-length and thus is also invalid).
101 //
102 // This field is required.
103 bytes span_id = 2;
104
105 // trace_state conveys information about request position in multiple distributed tracing graphs.
106 // It is a trace_state in w3c-trace-context format: https://www.w3.org/TR/trace-context/#tracestate-header
107 // See also https://github.com/w3c/distributed-tracing for more details about this field.
108 string trace_state = 3;
109
110 // The `span_id` of this span's parent span. If this is a root span, then this
111 // field must be empty. The ID is an 8-byte array.
112 bytes parent_span_id = 4;
113
114 // Flags, a bit field.
115 //
116 // Bits 0-7 (8 least significant bits) are the trace flags as defined in W3C Trace
117 // Context specification. To read the 8-bit W3C trace flag, use
118 // `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
119 //
120 // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
121 //
122 // Bits 8 and 9 represent the 3 states of whether a span's parent
123 // is remote. The states are (unknown, is not remote, is remote).
124 // To read whether the value is known, use `(flags & SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK) != 0`.
125 // To read whether the span is remote, use `(flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
126 //
127 // When creating span messages, if the message is logically forwarded from another source
128 // with an equivalent flags fields (i.e., usually another OTLP span message), the field SHOULD
129 // be copied as-is. If creating from a source that does not have an equivalent flags field
130 // (such as a runtime representation of an OpenTelemetry span), the high 22 bits MUST
131 // be set to zero.
132 // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
133 //
134 // [Optional].
135 fixed32 flags = 16;
136
137 // A description of the span's operation.
138 //
139 // For example, the name can be a qualified method name or a file name
140 // and a line number where the operation is called. A best practice is to use
141 // the same display name at the same call point in an application.
142 // This makes it easier to correlate spans in different traces.
143 //
144 // This field is semantically required to be set to non-empty string.
145 // Empty value is equivalent to an unknown span name.
146 //
147 // This field is required.
148 string name = 5;
149
150 // SpanKind is the type of span. Can be used to specify additional relationships between spans
151 // in addition to a parent/child relationship.
152 enum SpanKind {
153 // Unspecified. Do NOT use as default.
154 // Implementations MAY assume SpanKind to be INTERNAL when receiving UNSPECIFIED.
155 SPAN_KIND_UNSPECIFIED = 0;
156
157 // Indicates that the span represents an internal operation within an application,
158 // as opposed to an operation happening at the boundaries. Default value.
159 SPAN_KIND_INTERNAL = 1;
160
161 // Indicates that the span covers server-side handling of an RPC or other
162 // remote network request.
163 SPAN_KIND_SERVER = 2;
164
165 // Indicates that the span describes a request to some remote service.
166 SPAN_KIND_CLIENT = 3;
167
168 // Indicates that the span describes a producer sending a message to a broker.
169 // Unlike CLIENT and SERVER, there is often no direct critical path latency relationship
170 // between producer and consumer spans. A PRODUCER span ends when the message was accepted
171 // by the broker while the logical processing of the message might span a much longer time.
172 SPAN_KIND_PRODUCER = 4;
173
174 // Indicates that the span describes consumer receiving a message from a broker.
175 // Like the PRODUCER kind, there is often no direct critical path latency relationship
176 // between producer and consumer spans.
177 SPAN_KIND_CONSUMER = 5;
178 }
179
180 // Distinguishes between spans generated in a particular context. For example,
181 // two spans with the same name may be distinguished using `CLIENT` (caller)
182 // and `SERVER` (callee) to identify queueing latency associated with the span.
183 SpanKind kind = 6;
184
185 // start_time_unix_nano is the start time of the span. On the client side, this is the time
186 // kept by the local machine where the span execution starts. On the server side, this
187 // is the time when the server's application handler starts running.
188 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
189 //
190 // This field is semantically required and it is expected that end_time >= start_time.
191 fixed64 start_time_unix_nano = 7;
192
193 // end_time_unix_nano is the end time of the span. On the client side, this is the time
194 // kept by the local machine where the span execution ends. On the server side, this
195 // is the time when the server application handler stops running.
196 // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
197 //
198 // This field is semantically required and it is expected that end_time >= start_time.
199 fixed64 end_time_unix_nano = 8;
200
201 // attributes is a collection of key/value pairs. Note, global attributes
202 // like server name can be set using the resource API. Examples of attributes:
203 //
204 // "/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"
205 // "/http/server_latency": 300
206 // "example.com/myattribute": true
207 // "example.com/score": 10.239
208 //
209 // Attribute keys MUST be unique (it is not allowed to have more than one
210 // attribute with the same key).
211 //
212 // The attribute values SHOULD NOT contain empty values.
213 // The attribute values SHOULD NOT contain bytes values.
214 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
215 // double values.
216 // The attribute values SHOULD NOT contain kvlist values.
217 // The behavior of software that receives attributes containing such values can be unpredictable.
218 // These restrictions can change in a minor release.
219 // The restrictions take origin from the OpenTelemetry specification:
220 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
221 repeated opentelemetry.proto.common.v1.KeyValue attributes = 9;
222
223 // dropped_attributes_count is the number of attributes that were discarded. Attributes
224 // can be discarded because their keys are too long or because there are too many
225 // attributes. If this value is 0, then no attributes were dropped.
226 uint32 dropped_attributes_count = 10;
227
228 // Event is a time-stamped annotation of the span, consisting of user-supplied
229 // text description and key-value pairs.
230 message Event {
231 // time_unix_nano is the time the event occurred.
232 fixed64 time_unix_nano = 1;
233
234 // name of the event.
235 // This field is semantically required to be set to non-empty string.
236 string name = 2;
237
238 // attributes is a collection of attribute key/value pairs on the event.
239 // Attribute keys MUST be unique (it is not allowed to have more than one
240 // attribute with the same key).
241 //
242 // The attribute values SHOULD NOT contain empty values.
243 // The attribute values SHOULD NOT contain bytes values.
244 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
245 // double values.
246 // The attribute values SHOULD NOT contain kvlist values.
247 // The behavior of software that receives attributes containing such values can be unpredictable.
248 // These restrictions can change in a minor release.
249 // The restrictions take origin from the OpenTelemetry specification:
250 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
251 repeated opentelemetry.proto.common.v1.KeyValue attributes = 3;
252
253 // dropped_attributes_count is the number of dropped attributes. If the value is 0,
254 // then no attributes were dropped.
255 uint32 dropped_attributes_count = 4;
256 }
257
258 // events is a collection of Event items.
259 repeated Event events = 11;
260
261 // dropped_events_count is the number of dropped events. If the value is 0, then no
262 // events were dropped.
263 uint32 dropped_events_count = 12;
264
265 // A pointer from the current span to another span in the same trace or in a
266 // different trace. For example, this can be used in batching operations,
267 // where a single batch handler processes multiple requests from different
268 // traces or when the handler receives a request from a different project.
269 message Link {
270 // A unique identifier of a trace that this linked span is part of. The ID is a
271 // 16-byte array.
272 bytes trace_id = 1;
273
274 // A unique identifier for the linked span. The ID is an 8-byte array.
275 bytes span_id = 2;
276
277 // The trace_state associated with the link.
278 string trace_state = 3;
279
280 // attributes is a collection of attribute key/value pairs on the link.
281 // Attribute keys MUST be unique (it is not allowed to have more than one
282 // attribute with the same key).
283 //
284 // The attribute values SHOULD NOT contain empty values.
285 // The attribute values SHOULD NOT contain bytes values.
286 // The attribute values SHOULD NOT contain array values different than array of string values, bool values, int values,
287 // double values.
288 // The attribute values SHOULD NOT contain kvlist values.
289 // The behavior of software that receives attributes containing such values can be unpredictable.
290 // These restrictions can change in a minor release.
291 // The restrictions take origin from the OpenTelemetry specification:
292 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
293 repeated opentelemetry.proto.common.v1.KeyValue attributes = 4;
294
295 // dropped_attributes_count is the number of dropped attributes. If the value is 0,
296 // then no attributes were dropped.
297 uint32 dropped_attributes_count = 5;
298
299 // Flags, a bit field.
300 //
301 // Bits 0-7 (8 least significant bits) are the trace flags as defined in W3C Trace
302 // Context specification. To read the 8-bit W3C trace flag, use
303 // `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
304 //
305 // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
306 //
307 // Bits 8 and 9 represent the 3 states of whether the link is remote.
308 // The states are (unknown, is not remote, is remote).
309 // To read whether the value is known, use `(flags & SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK) != 0`.
310 // To read whether the link is remote, use `(flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
311 //
312 // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
313 // When creating new spans, bits 10-31 (most-significant 22-bits) MUST be zero.
314 //
315 // [Optional].
316 fixed32 flags = 6;
317 }
318
319 // links is a collection of Links, which are references from this span to a span
320 // in the same or different trace.
321 repeated Link links = 13;
322
323 // dropped_links_count is the number of dropped links after the maximum size was
324 // enforced. If this value is 0, then no links were dropped.
325 uint32 dropped_links_count = 14;
326
327 // An optional final status for this span. Semantically when Status isn't set, it means
328 // span's status code is unset, i.e. assume STATUS_CODE_UNSET (code = 0).
329 Status status = 15;
330 }
331
332 // The Status type defines a logical error model that is suitable for different
333 // programming environments, including REST APIs and RPC APIs.
334 message Status {
335 reserved 1;
336
337 // A developer-facing human readable error message.
338 string message = 2;
339
340 // For the semantics of status codes see
341 // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status
342 enum StatusCode {
343 // The default status.
344 STATUS_CODE_UNSET = 0;
345 // The Span has been validated by an Application developer or Operator to
346 // have completed successfully.
347 STATUS_CODE_OK = 1;
348 // The Span contains an error.
349 STATUS_CODE_ERROR = 2;
350 };
351
352 // The status code.
353 StatusCode code = 3;
354 }
355
356 // SpanFlags represents constants used to interpret the
357 // Span.flags field, which is protobuf 'fixed32' type and is to
358 // be used as bit-fields. Each non-zero value defined in this enum is
359 // a bit-mask. To extract the bit-field, for example, use an
360 // expression like:
361 //
362 // (span.flags & SPAN_FLAGS_TRACE_FLAGS_MASK)
363 //
364 // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
365 //
366 // Note that Span flags were introduced in version 1.1 of the
367 // OpenTelemetry protocol. Older Span producers do not set this
368 // field, consequently consumers should not rely on the absence of a
369 // particular flag bit to indicate the presence of a particular feature.
370 enum SpanFlags {
371 // The zero value for the enum. Should not be used for comparisons.
372 // Instead use bitwise "and" with the appropriate mask as shown above.
373 SPAN_FLAGS_DO_NOT_USE = 0;
374
375 // Bits 0-7 are used for trace flags.
376 SPAN_FLAGS_TRACE_FLAGS_MASK = 0x000000FF;
377
378 // Bits 8 and 9 are used to indicate that the parent span or link span is remote.
379 // Bit 8 (`HAS_IS_REMOTE`) indicates whether the value is known.
380 // Bit 9 (`IS_REMOTE`) indicates whether the span or link is remote.
381 SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK = 0x00000100;
382 SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK = 0x00000200;
383
384 // Bits 10-31 are reserved for future use.
385 }