# SpanKind describes the relationship between the Span, its parents, and its children in a Trace.
#
# SpanKind category reflects whether the Span is a "logical" remote child or parent. By "logical", we mean that the span is logically a remote child or parent, from the point of view of the library that is being instrumented. Spans with a remote parent are interesting because they are sources of external load. Spans with a remote child are interesting because they reflect a non-local system dependency.
#
# In order for SpanKind to be meaningful, callers SHOULD arrange that a single Span does not serve more than one purpose. For example, a server-side span SHOULD NOT be used directly as the parent of another remote span. As a simple guideline, instrumentation should create a new Span prior to extracting and serializing the SpanContext for a remote call.
# reference https://github.com/elastic/apm/blob/main/tests/agents/json-specs/span_types.json
# reference https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spankind
enum SpanKind{
    #Indicates that the span covers server-side handling of a synchronous RPC or other remote request. This span is often the child of a remote CLIENT span that was expected to wait for a response.
    SERVER
    #     Indicates that the span describes a request to some remote service. This span is usually the parent of a remote SERVER span and does not end until the response is received.
    CLIENT
    #    Indicates that the span describes the initiators of an asynchronous request. This parent span will often end before the corresponding child CONSUMER span, possibly even before the child span starts. In messaging scenarios with batching, tracing individual messages requires a new PRODUCER span per message to be created.
    PRODUCER
    #     Indicates that the span describes a child of an asynchronous PRODUCER request.
    CONSUMER
    #     Default value. Indicates that the span represents an internal operation within an application, as opposed to an operations with remote parents or children.
    INTERNAL
}

# Represents all the information that identifies Span in the Trace and MUST be propagated to child Spans and across process boundaries.
# A SpanContext contains the tracing identifiers and the options that are propagated from parent to child Spans.
# In ECS AKA - https://github.com/elastic/ecs/blob/main/schemas/tracing.yml
type SpanContext {
    # A unique identifier for a trace. All spans from the same trace share
    # the same `trace_id`.
    traceId: String!
    # A unique identifier for a span within a trace, assigned when the span
    # is created.
    spanId:ID!
    # Carries tracing-system specific context in a list of key value pairs.
    # Tracestate allows different vendors propagate additional information and inter-operate with their legacy Id formats
    tracestate:JSON

}

# A span represents a single operation within a trace. Spans can be
# nested to form a trace tree. Spans may also be linked to other spans
# from the same or different trace. And form graphs. 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 - there may be gaps or overlaps between spans in a trace.

# reference https://opentelemetry.io/docs/reference/specification/overview/#spancontext
# reference https://lightstep.com/opentelemetry/spans
type Span @model{
    # the identification details of the span (trace & span id)
    id:SpanContext!
    # The context (reference) of this span's parent span. If this is a root span, then this field must be empty.
    parentId:SpanContext
    name: String
    # timestamp of the span
    start: Time
    end: Time
    #
    events:[Event]
    spanKind:SpanKind
    # A Span may be linked to zero or more other Spans (defined by SpanContext) that are causally related.
    #    Links can point to Spans inside a single Trace or across different Traces. Links can be used to represent batched operations where a Span was initiated by multiple initiating Spans, each representing a single incoming item being processed in the batch.
    #
    # Another example of using a Link is to declare the relationship between the originating and following trace.
    #    This can be used when a Trace enters trusted boundaries of a service and service policy requires the generation of a new Trace rather than trusting the incoming Trace context.
    #    The new linked Trace may also represent a long running asynchronous data processing operation that was initiated by one of many fast incoming requests.
    #
    # When using the scatter/gather (also called fork/join) pattern, the root operation starts multiple downstream processing operations and all of them are aggregated back in a single Span.
    #    This last Span is linked to many operations it aggregates. All of them are the Spans from the same Trace. And similar to the Parent field of a Span.
    #    It is recommended, however, not to set a parent for the Span in this scenario as semantically the parent field represents a single parent scenario, in many cases the parent Span fully encloses the child Span (This is not the case in scatter/gather and batch scenarios).
    links:[SpanContext]
    # Span status is mapped to outcome
    outcome:EventOutcome
    # Key-Value pairs representing vendor specific properties
    attributes:JSON

}