> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.
# ListTraces
> Tracing
## OpenAPI
````yaml openapi/api_v1_data_openapi3_DOCUMENTATION_ONLY.json POST /api/v1/data/traces
openapi: 3.0.3
info:
description: |
The Data API provides HTTP/JSON REST endpoints for reading and writing data
to the Chronosphere system.
Use this link to download the raw Swagger specification:
/api/v1/data/swagger.json
title: Data V1 API
version: v1
servers:
- url: https://{tenant}.chronosphere.io
variables:
tenant:
default: tenant
description: tenant ID assigned by the service provider
security:
- ApiKeyAuth: []
tags:
- name: DataV1
paths:
/api/v1/data/traces:
post:
tags:
- DataV1
description: Tracing
operationId: ListTraces
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/datav1ListTracesRequest'
required: true
x-originalParamName: body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/datav1ListTracesResponse'
description: A successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/googlerpcStatus'
description: An unexpected error response.
components:
schemas:
datav1ListTracesRequest:
properties:
end_time:
description: End time for the search.
format: date-time
type: string
operation:
description: >-
Operation to filter on. An empty value doesn't apply any operation
filter.
type: string
query_type:
allOf:
- $ref: '#/components/schemas/ListTracesRequestQueryType'
description: >-
Type of query to perform.
TRACE_IDS: Search for specific trace IDs.
SERVICE_OPERATION: Search for traces with a specific service and
operation, over a specific time frame.
service:
description: >-
Service to filter on. An empty value doesn't apply any service
filter.
type: string
start_time:
description: Start time for the search.
format: date-time
type: string
tag_filters:
description: Tag filter to apply. An empty value doesn't apply any tag filter.
items:
$ref: '#/components/schemas/ListTracesRequestTagFilter'
type: array
trace_ids:
description: Trace IDs to search for.
items:
type: string
type: array
type: object
datav1ListTracesResponse:
properties:
traces:
items:
$ref: '#/components/schemas/v1TracesData'
type: array
type: object
googlerpcStatus:
properties:
code:
format: int32
type: integer
details:
items:
$ref: '#/components/schemas/protobufAny'
type: array
message:
type: string
type: object
ListTracesRequestQueryType:
enum:
- TRACE_IDS
- SERVICE_OPERATION
type: string
ListTracesRequestTagFilter:
properties:
key:
description: The key (or name) of the span tag that is inspected by this filter.
type: string
numeric_value:
allOf:
- $ref: '#/components/schemas/TagFilterNumericFilter'
description: >-
Matcher used to evaluate the span tag value as a numeric value (if
the
tag with the given key is found and the value type is numerical).
value:
allOf:
- $ref: '#/components/schemas/TagFilterStringFilter'
description: >-
Matcher used to evaluate the span tag value (if the tag with the
given
key is found and the value type is a string).
type: object
v1TracesData:
description: >-
TracesData represents the traces data that can be stored in a persistent
storage,
OR can be embedded by other protocols that transfer OTLP traces data but
do
not implement the OTLP protocol.
The main difference between this message and collector protocol is that
in this message there will not be any "control" or "metadata" specific
to
OTLP protocol.
When new fields are added into this message, the OTLP request MUST be
updated
as well.
properties:
resource_spans:
description: >-
An array of ResourceSpans.
For data coming from a single resource this array will typically
contain
one element. Intermediary nodes that receive data from multiple
origins
typically batch the data before forwarding further and in that case
this
array will contain multiple elements.
items:
$ref: '#/components/schemas/v1ResourceSpans'
type: array
type: object
protobufAny:
additionalProperties: {}
properties:
'@type':
type: string
type: object
TagFilterNumericFilter:
properties:
comparison:
allOf:
- $ref: '#/components/schemas/NumericFilterComparisonType'
description: >-
The comparison operation to be applied to an input against the given
filter value.
value:
description: The filter value used in comparison against match candidates.
format: double
type: number
type: object
TagFilterStringFilter:
properties:
in_values:
description: Values the filter tests against when using IN or NOT_IN match type.
items:
type: string
type: array
match:
allOf:
- $ref: '#/components/schemas/StringFilterStringFilterMatchType'
description: If EXACT, compared strings have the exact value of the filter value.
value:
description: The value the filter compares to the target trace or span field.
type: string
type: object
v1ResourceSpans:
description: A collection of ScopeSpans from a Resource.
properties:
resource:
allOf:
- $ref: '#/components/schemas/v1Resource'
description: |-
The resource for the spans in this message.
If this field is not set then no resource info is known.
schema_url:
description: >-
The Schema URL, if known. This is the identifier of the Schema that
the resource data
is recorded in. Notably, the last part of the URL path is the
version number of the
schema: http[s]://server[:port]/path/. To learn more about
Schema URL see
https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
This schema_url applies to the data in the "resource" field. It does
not apply
to the data in the "scope_spans" field which have their own
schema_url field.
type: string
scope_spans:
description: A list of ScopeSpans that originate from a resource.
items:
$ref: '#/components/schemas/v1ScopeSpans'
type: array
type: object
NumericFilterComparisonType:
enum:
- EQUAL
- NOT_EQUAL
- GREATER_THAN
- GREATER_THAN_OR_EQUAL
- LESS_THAN
- LESS_THAN_OR_EQUAL
type: string
StringFilterStringFilterMatchType:
enum:
- EXACT
- REGEX
- EXACT_NEGATION
- REGEX_NEGATION
- IN
- NOT_IN
type: string
v1Resource:
description: Resource information.
properties:
attributes:
description: >-
Set of attributes that describe the resource.
Attribute keys MUST be unique (it is not allowed to have more than
one
attribute with the same key).
items:
$ref: '#/components/schemas/v1KeyValue'
type: array
dropped_attributes_count:
description: >-
dropped_attributes_count is the number of dropped attributes. If the
value is 0, then
no attributes were dropped.
format: int64
type: integer
entity_refs:
description: >-
Set of entities that participate in this Resource.
Note: keys in the references MUST exist in attributes of this
message.
Status: [Development]
items:
$ref: '#/components/schemas/v1EntityRef'
type: array
type: object
v1ScopeSpans:
description: A collection of Spans produced by an InstrumentationScope.
properties:
schema_url:
description: >-
The Schema URL, if known. This is the identifier of the Schema that
the span data
is recorded in. Notably, the last part of the URL path is the
version number of the
schema: http[s]://server[:port]/path/. To learn more about
Schema URL see
https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
This schema_url applies to all spans and span events in the "spans"
field.
type: string
scope:
allOf:
- $ref: '#/components/schemas/v1InstrumentationScope'
description: >-
The instrumentation scope information for the spans in this message.
Semantically when InstrumentationScope isn't set, it is equivalent
with
an empty instrumentation scope name (unknown).
spans:
description: A list of Spans that originate from an instrumentation scope.
items:
$ref: '#/components/schemas/v1Span'
type: array
type: object
v1KeyValue:
description: |-
KeyValue is a key-value pair that is used to store Span attributes, Link
attributes, etc.
properties:
key:
type: string
value:
$ref: '#/components/schemas/v1AnyValue'
type: object
v1EntityRef:
description: >-
A reference to an Entity.
Entity represents an object of interest associated with produced
telemetry: e.g spans, metrics, profiles, or logs.
Status: [Development]
properties:
description_keys:
description: |-
Descriptive (non-identifying) attribute keys of the entity.
MAY change over the lifetime of the entity. MAY be empty.
These attribute keys are not part of entity's identity.
These keys MUST exist in the containing {message}.attributes.
items:
type: string
type: array
id_keys:
description: >-
Attribute Keys that identify the entity.
MUST not change during the lifetime of the entity. The Id must
contain at least one attribute.
These keys MUST exist in the containing {message}.attributes.
items:
type: string
type: array
schema_url:
description: >-
This schema_url applies to the data in this message and to the
Resource attributes
referenced by id_keys and description_keys.
TODO: discuss if we are happy with this somewhat complicated
definition of what
the schema_url applies to.
This field obsoletes the schema_url field in
ResourceMetrics/ResourceSpans/ResourceLogs.
title: >-
The Schema URL, if known. This is the identifier of the Schema that
the entity data
is recorded in. To learn more about Schema URL see
https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
type: string
type:
description: >-
Defines the type of the entity. MUST not change during the lifetime
of the entity.
For example: "service" or "host". This field is required and MUST
not be empty
for valid entities.
type: string
type: object
v1InstrumentationScope:
description: >-
InstrumentationScope is a message representing the instrumentation scope
information
such as the fully qualified name and version.
properties:
attributes:
description: >-
Additional attributes that describe the scope. [Optional].
Attribute keys MUST be unique (it is not allowed to have more than
one
attribute with the same key).
items:
$ref: '#/components/schemas/v1KeyValue'
type: array
dropped_attributes_count:
format: int64
type: integer
name:
description: An empty instrumentation scope name means the name is unknown.
type: string
version:
type: string
type: object
v1Span:
description: >-
A Span represents a single operation performed by a single component of
the system.
The next available field id is 17.
properties:
attributes:
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"
"/http/server_latency": 300
"example.com/myattribute": true
"example.com/score": 10.239
The OpenTelemetry API specification further restricts the allowed
value types:
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute
Attribute keys MUST be unique (it is not allowed to have more than
one
attribute with the same key).
items:
$ref: '#/components/schemas/v1KeyValue'
title: >-
attributes is a collection of key/value pairs. Note, global
attributes
like server name can be set using the resource API. Examples of
attributes:
type: array
dropped_attributes_count:
description: >-
dropped_attributes_count is 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 no attributes were dropped.
format: int64
type: integer
dropped_events_count:
description: >-
dropped_events_count is the number of dropped events. If the value
is 0, then no
events were dropped.
format: int64
type: integer
dropped_links_count:
description: >-
dropped_links_count is the number of dropped links after the maximum
size was
enforced. If this value is 0, then no links were dropped.
format: int64
type: integer
end_time_unix_nano:
description: >-
end_time_unix_nano is 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.
Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1
January 1970.
This field is semantically required and it is expected that end_time
>= start_time.
format: uint64
type: string
events:
description: events is a collection of Event items.
items:
$ref: '#/components/schemas/v1SpanEvent'
type: array
flags:
description: >-
Flags, a bit field.
Bits 0-7 (8 least significant bits) are the trace flags as defined
in W3C Trace
Context specification. To read the 8-bit W3C trace flag, use
`flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag
definitions.
Bits 8 and 9 represent the 3 states of whether a span's parent
is remote. The states are (unknown, is not remote, is remote).
To read whether the value is known, use `(flags &
SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK) != 0`.
To read whether the span is remote, use `(flags &
SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
When creating span messages, if the message is logically forwarded
from another source
with an equivalent flags fields (i.e., usually another OTLP span
message), the field SHOULD
be copied as-is. If creating from a source that does not have an
equivalent flags field
(such as a runtime representation of an OpenTelemetry span), the
high 22 bits MUST
be set to zero.
Readers MUST NOT assume that bits 10-31 (22 most significant bits)
will be zero.
[Optional].
format: int64
type: integer
kind:
allOf:
- $ref: '#/components/schemas/SpanSpanKind'
description: >-
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 queueing latency associated with
the span.
links:
description: >-
links is a collection of Links, which are references from this span
to a span
in the same or different trace.
items:
$ref: '#/components/schemas/SpanLink'
type: array
name:
description: >-
A description of the span's operation.
For example, the 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 at the same call point in an application.
This makes it easier to correlate spans in different traces.
This field is semantically required to be set to non-empty string.
Empty value is equivalent to an unknown span name.
This field is required.
type: string
parent_span_id:
description: >-
The `span_id` of this span's parent span. If this is a root span,
then this
field must be empty. The ID is an 8-byte array.
format: byte
type: string
span_id:
description: >-
A unique identifier for a span within a trace, assigned when the
span
is created. The ID is an 8-byte array. An ID with all zeroes OR of
length
other than 8 bytes is considered invalid (empty string in OTLP/JSON
is zero-length and thus is also invalid).
This field is required.
format: byte
type: string
start_time_unix_nano:
description: >-
start_time_unix_nano is 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.
Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1
January 1970.
This field is semantically required and it is expected that end_time
>= start_time.
format: uint64
type: string
status:
allOf:
- $ref: '#/components/schemas/tracev1Status'
description: >-
An optional final status for this span. Semantically when Status
isn't set, it means
span's status code is unset, i.e. assume STATUS_CODE_UNSET (code =
0).
trace_id:
description: >-
A unique identifier for a trace. All spans from the same trace share
the same `trace_id`. The ID is a 16-byte array. An ID with all
zeroes OR
of length other than 16 bytes is considered invalid (empty string in
OTLP/JSON
is zero-length and thus is also invalid).
This field is required.
format: byte
type: string
trace_state:
description: >-
trace_state conveys information about request position in multiple
distributed tracing graphs.
It is a trace_state in w3c-trace-context format:
https://www.w3.org/TR/trace-context/#tracestate-header
See also https://github.com/w3c/distributed-tracing for more details
about this field.
type: string
type: object
v1AnyValue:
description: >-
AnyValue is used to represent any type of attribute value. AnyValue may
contain a
primitive value such as a string or integer or it may contain an
arbitrary nested
object containing arrays, key-value lists and primitives.
properties:
array_value:
$ref: '#/components/schemas/v1ArrayValue'
bool_value:
type: boolean
bytes_value:
format: byte
type: string
double_value:
format: double
type: number
int_value:
format: int64
type: string
kvlist_value:
$ref: '#/components/schemas/v1KeyValueList'
string_value:
type: string
type: object
v1SpanEvent:
description: >-
Event is a time-stamped annotation of the span, consisting of
user-supplied
text description and key-value pairs.
properties:
attributes:
description: >-
attributes is a collection of attribute key/value pairs on the
event.
Attribute keys MUST be unique (it is not allowed to have more than
one
attribute with the same key).
items:
$ref: '#/components/schemas/v1KeyValue'
type: array
dropped_attributes_count:
description: >-
dropped_attributes_count is the number of dropped attributes. If the
value is 0,
then no attributes were dropped.
format: int64
type: integer
name:
description: |-
name of the event.
This field is semantically required to be set to non-empty string.
type: string
time_unix_nano:
description: time_unix_nano is the time the event occurred.
format: uint64
type: string
type: object
SpanSpanKind:
description: >-
SpanKind is the type of span. Can be used to specify additional
relationships between spans
in addition to a parent/child relationship.
- SPAN_KIND_INTERNAL: Indicates that the span represents an internal operation within an application,
as opposed to an operation happening at the boundaries. Default value.
- SPAN_KIND_SERVER: Indicates that the span covers server-side handling of an RPC or other
remote network request.
- SPAN_KIND_CLIENT: Indicates that the span describes a request to some remote service.
- SPAN_KIND_PRODUCER: Indicates that the span describes a producer sending a message to a broker.
Unlike CLIENT and SERVER, there is often no direct critical path latency
relationship
between producer and consumer spans. A PRODUCER span ends when the
message was accepted
by the broker while the logical processing of the message might span a
much longer time.
- SPAN_KIND_CONSUMER: Indicates that the span describes consumer receiving a message from a broker.
Like the PRODUCER kind, there is often no direct critical path latency
relationship
between producer and consumer spans.
enum:
- SPAN_KIND_INTERNAL
- SPAN_KIND_SERVER
- SPAN_KIND_CLIENT
- SPAN_KIND_PRODUCER
- SPAN_KIND_CONSUMER
type: string
SpanLink:
description: >-
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.
properties:
attributes:
description: >-
attributes is a collection of attribute key/value pairs on the link.
Attribute keys MUST be unique (it is not allowed to have more than
one
attribute with the same key).
items:
$ref: '#/components/schemas/v1KeyValue'
type: array
dropped_attributes_count:
description: >-
dropped_attributes_count is the number of dropped attributes. If the
value is 0,
then no attributes were dropped.
format: int64
type: integer
flags:
description: >-
Flags, a bit field.
Bits 0-7 (8 least significant bits) are the trace flags as defined
in W3C Trace
Context specification. To read the 8-bit W3C trace flag, use
`flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag
definitions.
Bits 8 and 9 represent the 3 states of whether the link is remote.
The states are (unknown, is not remote, is remote).
To read whether the value is known, use `(flags &
SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK) != 0`.
To read whether the link is remote, use `(flags &
SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
Readers MUST NOT assume that bits 10-31 (22 most significant bits)
will be zero.
When creating new spans, bits 10-31 (most-significant 22-bits) MUST
be zero.
[Optional].
format: int64
type: integer
span_id:
description: A unique identifier for the linked span. The ID is an 8-byte array.
format: byte
type: string
trace_id:
description: >-
A unique identifier of a trace that this linked span is part of. The
ID is a
16-byte array.
format: byte
type: string
trace_state:
description: The trace_state associated with the link.
type: string
type: object
tracev1Status:
description: >-
The Status type defines a logical error model that is suitable for
different
programming environments, including REST APIs and RPC APIs.
properties:
code:
allOf:
- $ref: '#/components/schemas/StatusStatusCode'
description: The status code.
message:
description: A developer-facing human readable error message.
type: string
type: object
v1ArrayValue:
description: >-
ArrayValue is a list of AnyValue messages. We need ArrayValue as a
message
since oneof in AnyValue does not allow repeated fields.
properties:
values:
description: Array of values. The array may be empty (contain 0 elements).
items:
$ref: '#/components/schemas/v1AnyValue'
type: array
type: object
v1KeyValueList:
description: >-
KeyValueList is a list of KeyValue messages. We need KeyValueList as a
message
since `oneof` in AnyValue does not allow repeated fields. Everywhere
else where we need
a list of KeyValue messages (e.g. in Span) we use `repeated KeyValue`
directly to
avoid unnecessary extra wrapping (which slows down the protocol). The 2
approaches
are semantically equivalent.
properties:
values:
description: >-
A collection of key/value pairs of key-value pairs. The list may be
empty (may
contain 0 elements).
The keys MUST be unique (it is not allowed to have more than one
value with the same key).
items:
$ref: '#/components/schemas/v1KeyValue'
type: array
type: object
StatusStatusCode:
description: >-
- STATUS_CODE_OK: The Span has been validated by an Application
developer or Operator to
have completed successfully.
- STATUS_CODE_ERROR: The Span contains an error.
enum:
- STATUS_CODE_OK
- STATUS_CODE_ERROR
title: >-
For the semantics of status codes see
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status
type: string
securitySchemes:
ApiKeyAuth:
description: Chronosphere API token
in: header
name: API-Token
type: apiKey
````