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