001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    package org.apache.hadoop.tracing;
019    
020    import java.io.IOException;
021    import java.util.LinkedList;
022    import java.util.List;
023    
024    import org.apache.hadoop.classification.InterfaceAudience;
025    import org.apache.hadoop.classification.InterfaceStability;
026    import org.apache.hadoop.fs.CommonConfigurationKeys;
027    import org.apache.hadoop.io.retry.AtMostOnce;
028    import org.apache.hadoop.io.retry.Idempotent;
029    import org.apache.hadoop.ipc.ProtocolInfo;
030    import org.apache.hadoop.security.KerberosInfo;
031    
032    /**
033     * Protocol interface that provides tracing.
034     */
035    @KerberosInfo(
036        serverPrincipal=CommonConfigurationKeys.HADOOP_SECURITY_SERVICE_USER_NAME_KEY)
037    @InterfaceAudience.Public
038    @InterfaceStability.Evolving
039    public interface TraceAdminProtocol {
040      public static final long versionID = 1L;
041    
042      /**
043       * List the currently active trace span receivers.
044       * 
045       * @throws IOException        On error.
046       */
047      @Idempotent
048      public SpanReceiverInfo[] listSpanReceivers() throws IOException;
049    
050      /**
051       * Add a new trace span receiver.
052       * 
053       * @param desc                The span receiver description.
054       * @return                    The ID of the new trace span receiver.
055       *
056       * @throws IOException        On error.
057       */
058      @AtMostOnce
059      public long addSpanReceiver(SpanReceiverInfo desc) throws IOException;
060    
061      /**
062       * Remove a trace span receiver.
063       *
064       * @param spanReceiverId      The id of the span receiver to remove.
065       * @throws IOException        On error.
066       */
067      @AtMostOnce
068      public void removeSpanReceiver(long spanReceiverId) throws IOException;
069    }