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.export; 18 19 import io.opencensus.trace.Span; 20 import io.opencensus.trace.TraceOptions; 21 import java.util.Collection; 22 import javax.annotation.concurrent.ThreadSafe; 23 24 /** 25 * A service that is used by the library to export {@code SpanData} for all the spans that are part 26 * of a distributed sampled trace (see {@link TraceOptions#isSampled()}). 27 * 28 * @since 0.5 29 */ 30 @ThreadSafe 31 public abstract class SpanExporter { 32 private static final SpanExporter NOOP_SPAN_EXPORTER = new NoopSpanExporter(); 33 34 /** 35 * Returns the no-op implementation of the {@code ExportComponent}. 36 * 37 * @return the no-op implementation of the {@code ExportComponent}. 38 * @since 0.5 39 */ getNoopSpanExporter()40 public static SpanExporter getNoopSpanExporter() { 41 return NOOP_SPAN_EXPORTER; 42 } 43 44 /** 45 * Registers a new service handler that is used by the library to export {@code SpanData} for 46 * sampled spans (see {@link TraceOptions#isSampled()}). 47 * 48 * @param name the name of the service handler. Must be unique for each service. 49 * @param handler the service handler that is called for each ended sampled span. 50 * @since 0.5 51 */ registerHandler(String name, Handler handler)52 public abstract void registerHandler(String name, Handler handler); 53 54 /** 55 * Unregisters the service handler with the provided name. 56 * 57 * @param name the name of the service handler that will be unregistered. 58 * @since 0.5 59 */ unregisterHandler(String name)60 public abstract void unregisterHandler(String name); 61 62 /** 63 * An abstract class that allows different tracing services to export recorded data for sampled 64 * spans in their own format. 65 * 66 * <p>To export data this MUST be register to to the ExportComponent using {@link 67 * #registerHandler(String, Handler)}. 68 * 69 * @since 0.5 70 */ 71 public abstract static class Handler { 72 73 /** 74 * Exports a list of sampled (see {@link TraceOptions#isSampled()}) {@link Span}s using the 75 * immutable representation {@link SpanData}. 76 * 77 * <p>This may be called from a different thread than the one that called {@link Span#end()}. 78 * 79 * <p>Implementation SHOULD not block the calling thread. It should execute the export on a 80 * different thread if possible. 81 * 82 * @param spanDataList a list of {@code SpanData} objects to be exported. 83 * @since 0.5 84 */ export(Collection<SpanData> spanDataList)85 public abstract void export(Collection<SpanData> spanDataList); 86 } 87 88 private static final class NoopSpanExporter extends SpanExporter { 89 90 @Override registerHandler(String name, Handler handler)91 public void registerHandler(String name, Handler handler) {} 92 93 @Override unregisterHandler(String name)94 public void unregisterHandler(String name) {} 95 } 96 } 97