Home | History | Annotate | Download | only in export 
      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    */
     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    */
     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    */
     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      */
     85     public abstract void export(Collection<SpanData> spanDataList);
     86   }
     87 
     88   private static final class NoopSpanExporter extends SpanExporter {
     89 
     90     @Override
     91     public void registerHandler(String name, Handler handler) {}
     92 
     93     @Override
     94     public void unregisterHandler(String name) {}
     95   }
     96 }
     97