1 /*
2  * Copyright 2017, OpenCensus Authors
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package io.opencensus.trace;
18 
19 import com.google.auto.value.AutoValue;
20 import java.util.Collections;
21 import java.util.HashMap;
22 import java.util.Map;
23 import javax.annotation.concurrent.Immutable;
24 
25 /**
26  * A link to a {@link Span} from a different trace.
27  *
28  * <p>It requires a {@link Type} which describes the relationship with the linked {@code Span} and
29  * the identifiers of the linked {@code Span}.
30  *
31  * <p>Used (for example) in batching operations, where a single batch handler processes multiple
32  * requests from different traces.
33  *
34  * @since 0.5
35  */
36 @Immutable
37 @AutoValue
38 public abstract class Link {
39   private static final Map<String, AttributeValue> EMPTY_ATTRIBUTES = Collections.emptyMap();
40 
41   /**
42    * The relationship with the linked {@code Span} relative to the current {@code Span}.
43    *
44    * @since 0.5
45    */
46   public enum Type {
47     /**
48      * When the linked {@code Span} is a child of the current {@code Span}.
49      *
50      * @since 0.5
51      */
52     CHILD_LINKED_SPAN,
53     /**
54      * When the linked {@code Span} is a parent of the current {@code Span}.
55      *
56      * @since 0.5
57      */
58     PARENT_LINKED_SPAN
59   }
60 
61   /**
62    * Returns a new {@code Link}.
63    *
64    * @param context the context of the linked {@code Span}.
65    * @param type the type of the relationship with the linked {@code Span}.
66    * @return a new {@code Link}.
67    * @since 0.5
68    */
fromSpanContext(SpanContext context, Type type)69   public static Link fromSpanContext(SpanContext context, Type type) {
70     return new AutoValue_Link(context.getTraceId(), context.getSpanId(), type, EMPTY_ATTRIBUTES);
71   }
72 
73   /**
74    * Returns a new {@code Link}.
75    *
76    * @param context the context of the linked {@code Span}.
77    * @param type the type of the relationship with the linked {@code Span}.
78    * @param attributes the attributes of the {@code Link}.
79    * @return a new {@code Link}.
80    * @since 0.5
81    */
fromSpanContext( SpanContext context, Type type, Map<String, AttributeValue> attributes)82   public static Link fromSpanContext(
83       SpanContext context, Type type, Map<String, AttributeValue> attributes) {
84     return new AutoValue_Link(
85         context.getTraceId(),
86         context.getSpanId(),
87         type,
88         Collections.unmodifiableMap(new HashMap<String, AttributeValue>(attributes)));
89   }
90 
91   /**
92    * Returns the {@code TraceId}.
93    *
94    * @return the {@code TraceId}.
95    * @since 0.5
96    */
getTraceId()97   public abstract TraceId getTraceId();
98 
99   /**
100    * Returns the {@code SpanId}.
101    *
102    * @return the {@code SpanId}
103    * @since 0.5
104    */
getSpanId()105   public abstract SpanId getSpanId();
106 
107   /**
108    * Returns the {@code Type}.
109    *
110    * @return the {@code Type}.
111    * @since 0.5
112    */
getType()113   public abstract Type getType();
114 
115   /**
116    * Returns the set of attributes.
117    *
118    * @return the set of attributes.
119    * @since 0.5
120    */
getAttributes()121   public abstract Map<String, AttributeValue> getAttributes();
122 
Link()123   Link() {}
124 }
125