2019-06-14 22:09:41 +02:00
|
|
|
// Copyright 2019, OpenTelemetry Authors
|
|
|
|
//
|
|
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
|
|
// you may not use this file except in compliance with the License.
|
|
|
|
// You may obtain a copy of the License at
|
|
|
|
//
|
|
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
//
|
|
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
// See the License for the specific language governing permissions and
|
|
|
|
// limitations under the License.
|
|
|
|
|
2019-06-14 20:37:05 +02:00
|
|
|
package trace
|
|
|
|
|
|
|
|
import (
|
|
|
|
"context"
|
|
|
|
"time"
|
|
|
|
|
2019-06-19 19:44:46 +02:00
|
|
|
"google.golang.org/grpc/codes"
|
|
|
|
|
2019-11-01 20:40:29 +02:00
|
|
|
"go.opentelemetry.io/otel/api/core"
|
2019-06-14 20:37:05 +02:00
|
|
|
)
|
|
|
|
|
2019-10-22 22:19:11 +02:00
|
|
|
type Provider interface {
|
|
|
|
// GetTracer creates a named tracer that implements Tracer interface.
|
|
|
|
// If the name is an empty string then provider uses default name.
|
|
|
|
GetTracer(name string) Tracer
|
|
|
|
}
|
|
|
|
|
2019-06-28 06:26:16 +02:00
|
|
|
type Tracer interface {
|
2019-07-12 00:28:38 +02:00
|
|
|
// Start a span.
|
2019-06-28 06:26:16 +02:00
|
|
|
Start(context.Context, string, ...SpanOption) (context.Context, Span)
|
|
|
|
|
|
|
|
// WithSpan wraps the execution of the function body with a span.
|
|
|
|
// It starts a new span and sets it as an active span in the context.
|
|
|
|
// It then executes the body. It closes the span before returning the execution result.
|
|
|
|
WithSpan(
|
|
|
|
ctx context.Context,
|
|
|
|
operation string,
|
|
|
|
body func(ctx context.Context) error,
|
|
|
|
) error
|
|
|
|
}
|
2019-06-14 20:37:05 +02:00
|
|
|
|
2019-09-27 19:48:10 +02:00
|
|
|
type EndOptions struct {
|
|
|
|
EndTime time.Time
|
2019-09-03 20:03:51 +02:00
|
|
|
}
|
|
|
|
|
2019-09-27 19:48:10 +02:00
|
|
|
type EndOption func(*EndOptions)
|
2019-09-03 20:03:51 +02:00
|
|
|
|
2019-09-27 19:48:10 +02:00
|
|
|
func WithEndTime(endTime time.Time) EndOption {
|
|
|
|
return func(opts *EndOptions) {
|
|
|
|
opts.EndTime = endTime
|
2019-09-03 20:03:51 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-06-28 06:26:16 +02:00
|
|
|
type Span interface {
|
|
|
|
// Tracer returns tracer used to create this span. Tracer cannot be nil.
|
|
|
|
Tracer() Tracer
|
2019-06-14 20:37:05 +02:00
|
|
|
|
2019-09-27 19:48:10 +02:00
|
|
|
// End completes the span. No updates are allowed to span after it
|
|
|
|
// ends. The only exception is setting status of the span.
|
|
|
|
End(options ...EndOption)
|
2019-06-19 19:44:46 +02:00
|
|
|
|
2019-06-28 06:26:16 +02:00
|
|
|
// AddEvent adds an event to the span.
|
2019-09-03 20:03:51 +02:00
|
|
|
AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue)
|
2019-09-25 08:12:22 +02:00
|
|
|
// AddEventWithTimestamp adds an event with a custom timestamp
|
|
|
|
// to the span.
|
|
|
|
AddEventWithTimestamp(ctx context.Context, timestamp time.Time, msg string, attrs ...core.KeyValue)
|
2019-06-25 22:50:46 +02:00
|
|
|
|
2019-10-11 03:07:35 +02:00
|
|
|
// IsRecording returns true if the span is active and recording events is enabled.
|
|
|
|
IsRecording() bool
|
2019-06-19 19:44:46 +02:00
|
|
|
|
2019-09-21 09:26:20 +02:00
|
|
|
// AddLink adds a link to the span.
|
|
|
|
AddLink(link Link)
|
|
|
|
|
|
|
|
// Link creates a link between this span and the other span specified by the SpanContext.
|
|
|
|
// It then adds the newly created Link to the span.
|
|
|
|
Link(sc core.SpanContext, attrs ...core.KeyValue)
|
|
|
|
|
2019-09-27 19:48:10 +02:00
|
|
|
// SpanContext returns span context of the span. Returned SpanContext is usable
|
|
|
|
// even after the span ends.
|
2019-06-28 06:26:16 +02:00
|
|
|
SpanContext() core.SpanContext
|
2019-06-19 19:44:46 +02:00
|
|
|
|
2019-06-28 06:26:16 +02:00
|
|
|
// SetStatus sets the status of the span. The status of the span can be updated
|
2019-09-27 19:48:10 +02:00
|
|
|
// even after span ends.
|
2019-06-28 06:26:16 +02:00
|
|
|
SetStatus(codes.Code)
|
2019-07-12 00:28:38 +02:00
|
|
|
|
2019-08-26 20:53:12 +02:00
|
|
|
// SetName sets the name of the span.
|
|
|
|
SetName(name string)
|
|
|
|
|
2019-07-12 00:28:38 +02:00
|
|
|
// Set span attributes
|
|
|
|
SetAttribute(core.KeyValue)
|
|
|
|
SetAttributes(...core.KeyValue)
|
2019-06-28 06:26:16 +02:00
|
|
|
}
|
2019-06-14 20:37:05 +02:00
|
|
|
|
2019-06-28 06:26:16 +02:00
|
|
|
// SpanOption apply changes to SpanOptions.
|
|
|
|
type SpanOption func(*SpanOptions)
|
2019-06-19 19:44:46 +02:00
|
|
|
|
2019-06-28 06:26:16 +02:00
|
|
|
// SpanOptions provides options to set properties of span at the time of starting
|
|
|
|
// a new span.
|
|
|
|
type SpanOptions struct {
|
2019-10-11 03:07:35 +02:00
|
|
|
Attributes []core.KeyValue
|
|
|
|
StartTime time.Time
|
2019-10-21 19:15:49 +02:00
|
|
|
Relation Relation
|
2019-10-11 03:07:35 +02:00
|
|
|
Record bool
|
2019-10-24 01:25:14 +02:00
|
|
|
SpanKind SpanKind
|
2019-06-28 06:26:16 +02:00
|
|
|
}
|
2019-06-14 20:37:05 +02:00
|
|
|
|
2019-10-21 19:15:49 +02:00
|
|
|
// Relation is used to establish relationship between newly created span and the
|
2019-06-28 06:26:16 +02:00
|
|
|
// other span. The other span could be related as a parent or linked or any other
|
|
|
|
// future relationship type.
|
2019-10-21 19:15:49 +02:00
|
|
|
type Relation struct {
|
2019-06-28 06:26:16 +02:00
|
|
|
core.SpanContext
|
|
|
|
RelationshipType
|
|
|
|
}
|
2019-06-14 20:37:05 +02:00
|
|
|
|
2019-06-28 06:26:16 +02:00
|
|
|
type RelationshipType int
|
2019-06-14 20:37:05 +02:00
|
|
|
|
2019-07-01 20:25:40 +02:00
|
|
|
const (
|
|
|
|
ChildOfRelationship RelationshipType = iota
|
|
|
|
FollowsFromRelationship
|
|
|
|
)
|
|
|
|
|
2019-09-21 09:26:20 +02:00
|
|
|
// Link is used to establish relationship between two spans within the same Trace or
|
|
|
|
// across different Traces. Few examples of Link usage.
|
|
|
|
// 1. Batch Processing: A batch of elements may contain elements associated with one
|
|
|
|
// or more traces/spans. Since there can only be one parent SpanContext, Link is
|
|
|
|
// used to keep reference to SpanContext of all elements in the batch.
|
|
|
|
// 2. Public Endpoint: A SpanContext in incoming client request on a public endpoint
|
|
|
|
// is untrusted from service provider perspective. In such case it is advisable to
|
|
|
|
// start a new trace with appropriate sampling decision.
|
|
|
|
// However, it is desirable to associate incoming SpanContext to new trace initiated
|
|
|
|
// on service provider side so two traces (from Client and from Service Provider) can
|
|
|
|
// be correlated.
|
|
|
|
type Link struct {
|
|
|
|
core.SpanContext
|
|
|
|
Attributes []core.KeyValue
|
|
|
|
}
|
|
|
|
|
2019-10-24 01:25:14 +02:00
|
|
|
// SpanKind represents the role of a Span inside a Trace. Often, this defines how a Span
|
|
|
|
// will be processed and visualized by various backends.
|
|
|
|
type SpanKind string
|
|
|
|
|
|
|
|
const (
|
|
|
|
SpanKindInternal SpanKind = "internal"
|
|
|
|
SpanKindServer SpanKind = "server"
|
|
|
|
SpanKindClient SpanKind = "client"
|
|
|
|
SpanKindProducer SpanKind = "producer"
|
|
|
|
SpanKindConsumer SpanKind = "consumer"
|
|
|
|
)
|
|
|
|
|
2019-06-27 07:03:09 +02:00
|
|
|
// WithStartTime sets the start time of the span to provided time t, when it is started.
|
2019-10-24 01:25:14 +02:00
|
|
|
// In absence of this option, wall clock time is used as start time.
|
2019-06-27 07:03:09 +02:00
|
|
|
// This option is typically used when starting of the span is delayed.
|
2019-06-19 19:44:46 +02:00
|
|
|
func WithStartTime(t time.Time) SpanOption {
|
|
|
|
return func(o *SpanOptions) {
|
2019-06-27 07:03:09 +02:00
|
|
|
o.StartTime = t
|
2019-06-14 20:37:05 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-06-27 07:03:09 +02:00
|
|
|
// WithAttributes sets attributes to span. These attributes provides additional
|
|
|
|
// data about the span.
|
2019-06-19 19:44:46 +02:00
|
|
|
func WithAttributes(attrs ...core.KeyValue) SpanOption {
|
|
|
|
return func(o *SpanOptions) {
|
2019-06-27 07:03:09 +02:00
|
|
|
o.Attributes = attrs
|
2019-06-14 20:37:05 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-10-11 03:07:35 +02:00
|
|
|
// WithRecord specifies that the span should be recorded.
|
|
|
|
// Note that the implementation may still override this preference,
|
|
|
|
// e.g., if the span is a child in an unsampled trace.
|
|
|
|
func WithRecord() SpanOption {
|
2019-06-19 19:44:46 +02:00
|
|
|
return func(o *SpanOptions) {
|
2019-10-11 03:07:35 +02:00
|
|
|
o.Record = true
|
2019-06-14 20:37:05 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-06-27 07:03:09 +02:00
|
|
|
// ChildOf. TODO: do we need this?.
|
2019-06-19 19:44:46 +02:00
|
|
|
func ChildOf(sc core.SpanContext) SpanOption {
|
|
|
|
return func(o *SpanOptions) {
|
2019-10-21 19:15:49 +02:00
|
|
|
o.Relation = Relation{
|
2019-06-14 20:37:05 +02:00
|
|
|
SpanContext: sc,
|
|
|
|
RelationshipType: ChildOfRelationship,
|
2019-06-19 19:44:46 +02:00
|
|
|
}
|
2019-06-14 20:37:05 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-06-27 07:03:09 +02:00
|
|
|
// FollowsFrom. TODO: do we need this?.
|
2019-06-19 19:44:46 +02:00
|
|
|
func FollowsFrom(sc core.SpanContext) SpanOption {
|
|
|
|
return func(o *SpanOptions) {
|
2019-10-21 19:15:49 +02:00
|
|
|
o.Relation = Relation{
|
2019-06-14 20:37:05 +02:00
|
|
|
SpanContext: sc,
|
|
|
|
RelationshipType: FollowsFromRelationship,
|
2019-06-19 19:44:46 +02:00
|
|
|
}
|
2019-06-14 20:37:05 +02:00
|
|
|
}
|
|
|
|
}
|
2019-10-24 01:25:14 +02:00
|
|
|
|
|
|
|
// WithSpanKind specifies the role a Span on a Trace.
|
|
|
|
func WithSpanKind(sk SpanKind) SpanOption {
|
|
|
|
return func(o *SpanOptions) {
|
|
|
|
o.SpanKind = sk
|
|
|
|
}
|
|
|
|
}
|